gesellix/awsume repository overview

⁠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 .