Containerized AWSume

A container with AWSume and AWS CLI to manage your shell's environment and perform tasks on the AWS API.

Usage

You can find the latest documentation for the AWS CLI at the user guide⁠ and the documentation for AWSume at awsu.me⁠.

Please note for the examples below:

• host> means "perform this command in your shell"
• awsume> means "perform this command in the gesellix/awsume container"

Prepare your AWS CLI config and credentials

Create a basic AWS CLI profile for your user

First you'll need to create IAM user access keys⁠ and while you're already on your AWS user's My Security Credentials page, please note your MFA device's ARN.

The aws configure command helps creating or updating your profiles:

host> docker run --rm -it -v ~/.aws:/root/.aws/ gesellix/awsume # run the container's shell
awsume> aws configure --profile my-account       # use the aws cli to configure your user's profile
AWS Access Key ID [None]: AWSACCESSKEYID         # ... (enter the requested details)
AWS Secret Access Key [None]: Secret+Access/Key  # ...
Default region name [None]: eu-central-1         # ...
Default output format [None]: json               # ...
awsume> [ctrl+d]                                 # exit the container
host> cat ~/.aws/config                          # verify that everything has been written to your local user's home

If Multi Factor Authentication (MFA) is mandatory, manually add the following entry in your profile's section at ~/.aws/config:

host> echo "mfa_serial = arn:aws:iam::123456789:mfa/..." >> ~/.aws/config

Add any roles you want to assume as new profiles

The aws CLI won't help you here - you'll have to edit your ~/.aws/config manually. The result could look like this:

[profile my-account]
region = eu-central-1
output = json
mfa_serial = arn:aws:iam::123456789:mfa/user.name

[profile dev]
role_arn = arn:aws:iam::1283847458738:role/My-DevRole
source_profile = my-account

[profile prod]
role_arn = arn:aws:iam::3894787978734:role/My-ProdRole
source_profile = my-account

Manage your shell's environment

List configured profiles:

host> docker run --rm -v ~/.aws/:/root/.aws/ gesellix/awsume awsume -l

Get AWS environment variables for a new session:

host> docker run --rm -v ~/.aws/:/root/.aws/ gesellix/awsume awsume --show-commands --mfa-token 868990 dev 2> /dev/null
export AWS_ACCESS_KEY_ID=AWSACCESSKEYID
export AWS_SECRET_ACCESS_KEY=Secret+Access/Key
export AWS_SESSION_TOKEN=...==
export AWS_SECURITY_TOKEN=...==
export AWS_REGION=eu-central-1
export AWS_DEFAULT_REGION=eu-central-1
export AWSUME_PROFILE=dev

Use the awsume console plugin to generate a url to the console

Related docs: https://github.com/trek10inc/awsume-console-plugin⁠

host> docker run --rm -it -v ~/.aws:/root/.aws/ gesellix/awsume # run the container's shell
awsume> awsume <profile> -cl
awsume> awsume <profile> -csl cfn # go directly to cloudformation

Tips for working with the awsume container:

1. Attach a volume to the /root directory to persist your authentication between docker runs:

   docker run --rm -v ~/.aws/:/root/.aws/ -v awsume_data:/root gesellix/awsume awsume <profile>

2. If you add this to your ~/.bashrc or ~/.zshrc file and use macOs...

   awsc () {
     URL=$( { docker run --rm -v ~/.aws/:/root/.aws/ -v awsume_data:/root gesellix/awsume awsume "$1" -csl "$2"; } 2>&1 )
     /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome $(echo "$URL" | grep "http")
   }
   

   Copy

   ...then you can open a URL that goes to a specific service (ex: IAM) with Google Chrome by just running this:

   awsc <profile> iam
   

   Copy

   Note: This will only work if you are in an authenticated session.

Build the Docker image

If you want to change the Docker image for your specific needs, you'll need to change the relevant files, e.g. Dockerfile, and rebuild the image:

host> docker build -t gesellix/awsume .