

ATLAS GO


[Latest Version] [Build Status] [Go Documentation]

Atlas Go is the official Go client for HashiCorp's Atlas service.


Usage

Authenticating with username and password

Atlas Go can automatically generate an API authentication token given a
username and password. For example:

    client := atlas.DefaultClient()
    token, err := client.Login("username", "password")
    if err != nil {
      panic(err)
    }

The Login function returns an API token that can be used to sign
requests. This function also sets the Token parameter on the Atlas
Client, so future requests are signed with this access token.

IF YOU HAVE TWO-FACTOR AUTHENTICATION ENABLED, YOU MUST MANUALLY
GENERATE AN ACCESS TOKEN ON THE ATLAS WEBSITE.

Usage with on-premise Atlas

Atlas Go supports on-premise Atlas installs, but you must specify the
URL of the Atlas server in the client:

    client, err := atlas.NewClient("https://url.to.your.atlas.server")
    if err != nil {
      panic(err)
    }


Example

The following example generates a new access token for a user named
"sethvargo", generates a new Application named "frontend", and uploads
the contents of a path to said application with some user-supplied
metadata:

    client := atlas.DefaultClient()
    token, err := client.Login("sethvargo", "b@c0n")
    if err != nil {
      log.Fatalf("err logging in: %s", err)
    }

    app, err := client.CreateApp("sethvargo", "frontend")
    if err != nil {
      log.Fatalf("err creating app: %s", err)
    }

    metadata := map[string]interface{
      "developed-on": runtime.GOOS,
    }

    data, size := functionThatReturnsAnIOReaderAndSize()
    version, err := client.UploadApp(app, metadata, data, size)
    if err != nil {
      log.Fatalf("err uploading app: %s", err)
    }

    // version is the unique version of the application that was just uploaded
    version


FAQ

Q: CAN I SPECIFY MY TOKEN VIA AN ENVIRONMENT VARIABLE? A: All of
HashiCorp's products support the ATLAS_TOKEN environment variable. You
can set this value in your shell profile or securely in your environment
and it will be used.

Q: HOW CAN I AUTHENTICATE IF I HAVE TWO-FACTOR AUTHENTICATION ENABLED?
A: If you have two-factor authentication enabled, you must generate an
access token via the Atlas website and pass it to the client
initialization. The Atlas Go client does not support generating access
tokens from two-factor authentication enabled accounts via the command
line.

Q: WHY DO I NEED TO SPECIFY THE "USER" FOR AN APPLICATION, BUILD
CONFIGURATION, AND RUNTIME? A: Since you can be a collaborator on
different projects, we wanted to have absolute clarity around which
artifact you are currently interacting with.


Contributing

To hack on Atlas Go, you will need a modern Go environment. To compile
the atlas-go binary and run the test suite, simply execute:

    $ make

This will compile the atlas-go binary into bin/atlas-go and run the test
suite.

If you just want to run the tests:

    $ make test

Or to run a specific test in the suite:

    go test ./... -run SomeTestFunction_name

Submit Pull Requests and Issues to the Atlas Go project on GitHub.
