atlas-go

README

Atlas Go

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.