Authenticate with AWS inside of Geodesic using 'aws-vault' (Deprecated)

Intro

In this how-to, we'll provide a step-by-step guide on how we used to recommend authenticating with AWS inside of Geodesic, using aws-vault. This remains for historical reference and for companies who have been using aws-vault for a while and want to train new users. Cloud Posse no longer recommends this workflow. See Authenticate with AWS using Leapp for the currently recommended procedure.

Prerequisites

System Requirements

You'll need to have an AWS Account with the ability to create credentials and have Docker installed on your local machine. That's all.

SweetOps Know-how

We expect you've gone through the tutorial on "Getting started with Geodesic" prior to this How-To since that contains some important understanding of what Geodesic is, how it works, and what it's doing.

How-To

1. Install and start Geodesic

First, at your terminal, let's install Geodesic!

docker run cloudposse/geodesic:latest-debian | bash

This will install Geodesic as a script at /usr/local/bin/geodesic, which you can then invoke like so:

geodesic

This small script is just a wrapper around running Geodesic via docker with a couple extra options (like mounting $HOME to /localhost). It should drop you into the Geodesic shell like you would expect.

2. Authenticate with AWS + aws-vault

Geodesic ships with aws-vault to help manage our credentials and retrieve access tokens from AWS to provide us with authenticated sessions. To set up a new profile, first create a new IAM user and programmatic Access Key ID and Secret Key and be sure to copy those values down somewhere. Now, in your Geodesic shell, let's do the following:

# Since our Geodesic shell is on Linux, let's use the file backend which Linux supports.
# NOTE: It's not possible to use the OSX Keychain with `aws-vault` running inside of a Docker container.
export AWS_VAULT_BACKEND=file

# Add our new credentials to aws-vault under whatever profile name you would like. i.e. replace $YOUR_PROFILE_NAME
# This will prompt you for the Access Key ID and Secret Key that you copied down earlier, which you should input.
aws-vault add $YOUR_PROFILE_NAME

Now we've added our credentials to aws-vault and we can easily use aws-vault exec to execute an authenticated command on the AWS CLI like so:

# List all the buckets in your account:
aws-vault exec $YOUR_PROFILE_NAME -- aws s3 ls

# Or get some information on your user:
aws-vault exec luke.skywalker -- aws sts get-caller-identity

3. Start a AWS Profile Session

That's cool... but what about if you want to start a full blown session as the profile you added so you don't need to keep typing aws-vault exec? Well, Geodesic comes bundled with a handy assume-role utility that you can use to do that. First though, we need to update our /localhost/.aws/config file to support aws-vault. To do that, on your local machine, open up $HOME/.aws/config with your favorite editor and add the following config entry:

# ... your existing AWS Config file contents ...

[profile $YOUR_PROFILE_NAME]
credential_process = aws-vault exec $YOUR_PROFILE_NAME --json

Great, now that we've set that up, our profile is ready to use with our assume-role utility:

# Now we run `assume-role` with our newly created profile and this will start a new shell session which is authenticated as that profile for us.
assume-role $YOUR_PROFILE_NAME

# We should now see our profile name in our command line prompt and we can now run our AWS CLI
# commands without having to manually invoke `aws-vault exec` each time
aws s3 ls
aws sts get-caller-identity

Conclusion

Here is a simple use-case of setting up a set of AWS credentials within Geodesic, but there is plenty more you can do here since Geodesic also comes bundled with saml2aws and aws-google-auth. Use what works for you and your organization!