Skip to main content

Get Started with AWSH

In a Nutshell
What will I learn?Let's discover how to get started with AWSH in less than 10 minutes. We will load some AWS credentials and have a look around our AWS account.
Difficulty

What you'll need​

Software & Services​

  • Docker version 16.14 or above:
info

If you don't yet have Docker installed or access to Docker then you can follow the official documentation from the folks at Docker to find the right version for your operating system and get up and running

https://docs.docker.com/get-docker/

Permissions & Access​

The built in ReadOnlyAccess IAM Policy provides all the permissions needed to get and collect data from the AWS APIs for now. You can attach this existing IAM Policy provided by AWS to the IAM User, Group or Role that corresponds to the identity that you have AWS credentials for.

For a full list of all the permissions being granted by this IAM Policy you can view the ReadOnlyAccess Policy in your AWS account

Tutorial​

Starting AWSH​

To run AWSH in its simplest form just launch a new terminal from within your Operating System and start the AWSH Container directly

docker run -it --rm hestio/awsh

Running that command should give you a terminal window with a running instance of AWSH

asciicast

Persistent Data​

Using AWSH without any data or configuration persistance is probably not what you want. You will benefit much more from having your configuration persist between sessions so that you can resume right where you left off next time you launch AWSH again

To do that we will create a simple wrapper script awsh that will create a persistent data store and share some useful files you have in your HOME directory with the AWSH container.

/usr/local/bin/awsh
#!/usr/bin/env bash

PUID=$(id -u)
PGID=$(id -g)

# Ensure paths exist
[ -d "${HOME}/.awsh/identities" ] || mkdir -p "${HOME}/.awsh/identities"
[ -d "${HOME}/workspace" ] || mkdir -p "${HOME}/workspace"

# Ensure config files exist
touch ${HOME}/.bashrc_local ${HOME}/.netrc ${HOME}/.terraformrc

# Start the container
docker run \
    -it \
    --rm \
    --network=host \
    --user ${PUID}:${PGID} \
    -v ${HOME}/.awsh:/home/awsh/.awsh \
    -v ${HOME}/.bashrc_local:/home/awsh/.bashrc_local \
    -v ${HOME}/.netrc:/home/awsh/.netrc \
    -v ${HOME}/.terraformrc:/home/awsh/.terraformrc \
    -v ${HOME}/workspace:/home/awsh/workspace \
    -v /tmp:/tmp \
    -e "HOME=/home/awsh" \
    -e "PUID=${PUID}" \
    -e "PGID=${PGID}" \
    -e "http_proxy=${http_proxy}" \
    -e "https_proxy=${https_proxy}" \
    -e "no_proxy=${no_proxy}" \
    hestio/awsh

Now that we've created our wrapper script we can use it to launch a new AWSH session and start using it with AWS

asciicast

Running that command should give you a terminal window with a running instance of AWSH and map in several useful paths from your HOME directory that are commonly used by many of the tools in the AWS ecosystem.

tip

If you'd like the ability to add or import other customizations to your AWSH sessions you can take advantage of the hook built into both AWSH and BLOX that will check for the existance of ${HOME}/.bashrc_local on startup and process it as part of normal shell init

~/.bashrc_local
#!/bin/bash

## Aliases
alias vim="vi"

cat > ~/.gitconfig <<EOF
[credential "https://git.com"]
  username = [email protected]
  helper = store
[user]
  name = Lukasz Czarnota
  email = [email protected]
EOF

For more detailed information please see the full documentation here. For now, let's continue with loading some credentials and having a look around.

Load some AWS credentials​

At the AWSH prompt, load some existing credentials for your AWS account. These can be IAM User or IAM STS Temporary credentials. Simply paste them into the AWSH terminal and use CTRL+D when done.

AWSH❯
awsh creds load

Once you have loaded some credentials your default terminal prompt will update to provide more useful information to help you navigate AWS at the CLI. Let's have a look;

Example Output
Screenshot: Example Output
  1. Which container you are using. This will be BLOX or AWSH depending on which set of containerized tools you are using
  2. AWS credentials, either from temporary (STS) or persistent (IAM User) API access
  3. Once loaded, some summary information about the credentials is shown for use with any AWS tooling that does not support the default order of precedence (command line -> environment -> files)
  4. Time. Yes, boring maybe but it is extremely useful when reviewing how long commands took to complete previously. Some of those API calls to manage AWS resources can take up to an hour!
  5. AWS Account alias.
  6. The name of the AWS identity that the credentials provided are for
  7. The default AWS Region that will be used when not adding --region ab-cdef-n to any commands
  8. The remaining duration on your temporary credentials if known.

Basic Usage​

  • Each of the helper commands present in AWSH can be invoked using

    AWSH❯
    awsh <command>

  • To find a complete list of all of the available commands you can use the auto-complete built into the CLI (Default: TAB-TAB) after typing awsh

    AWSH❯
    awsh <TAB><TAB>

    acm-import-certificate     report-access              sg-revoke-rules
    auth-report                report-ec2-lb              ssh
    creds                      report-inventory           subnet-claim-ip
    dump-account               report-s3-usage            token-krb5formauth-create
    identity-create            scp                        token-mfaauth-create
    list                       session-load               vpc-viz
    login                      session-purge              whoami
    logout                     session-save
    region                     sg-add

  • Some AWSH commands also support completions which can be surfaced in the same way (Default: TAB-TAB) after typing a supported AWSH command (awsh list)

    AWSH❯
    awsh list <TAB><TAB>

    acm                            ecs-task-definitions           nacl
    acm-detailed                   ecs-tasks                      natgw
    alb                            eip                            network-prefix-list
    alb-listener                   eks-addon-versions             rds
    ami                            eks-addons                     rds-detailed
    batch-compute-environments     eks-clusters                   rds-option-groups
    batch-job-definitions          eks-fargate-profiles           rds-parameter-group
    batch-job-queues               eks-identity-provider-configs  rds-snapshot
    batch-jobs                     eks-nodegroups                 rds-subnet-groups
    cgw                            eks-updates                    redshift-snapshot
    cloudtrail                     elb                            route-table
    costs-by-month-and-service     elb-detailed                   route-table-routes
    fsx                            route53-zone
    dx-connection                  iam-access-keys                s3bucket
    dx-interface                   iam-account-password-policy    s3hm
    ebs-snapshot                   iam-account-summary            sg
    ebs-snapshot-detailed          iam-cert                       sg-rules
    ebs-volume                     iam-groups                     ssm-instances
    ebs-volume-detailed            iam-groups-policy-attachments  subnet
    ec2-instance                   iam-groups-users               tgw
    ec2-instance-detailed          iam-instance-profile           tgw-gateway-attachments
    ec2-instance-ssm-status        iam-policies                   tgw-gateway-vpc-attachments
    ecs-attributes                 iam-role                       tgw-route-table
    ecs-capacity-providers         iam-role-policy-attachments    tgw-route-table-routes
    ecs-clusters                   iam-user                       vpc
    ecs-container-instances        igw                            vpc-endpoints
    ecs-describe-clusters          kms-alias                      vpn
    ecs-services                   kms-key                        vpngw
    ecs-task-definition            lambda
    ecs-task-definition-families   lambda-detailed

Examples​

AWS Session Required

Some commands will require an active session with AWS to ensure that you are not attempting to make AWS API calls without first being logged in

Attempting a command that requires an AWS session
Screenshot: Attempting a command that requires an AWS session

  • What identity is active?

    AWSH❯
    awsh whoami
    ❯ awsh whoami
    UserId                      Account  Arn
    ---------------------  ------------  ----------------------------------------------
    AKIASP2TPHJSRXZCD6VR   123456789012  arn:aws:iam::123456789012:user/luk

  • Changing the default AWS Region

    AWSH❯
    awsh region

    asciicast

  • What VPCs are in this AWS Region?

    AWSH❯
    awsh list vpc

    asciicast

    There are lots of list commands available. For a complete reference, please refer to the User Guide

  • Who has access to AWS?

    AWSH❯
    awsh auth-report

    See dedicated tutorial AWSH Access Report

  • What is our AWS spend?

    AWSH❯
    awsh list costs-by-month-and-service
    Example Output
    Screenshot: Example Output

    See dedicated tutorial AWSH Inventory Report

Now that you've had a look around why not check out the full documentation here.


Open Source

Did you know that both AWSH and BLOX are completely Open Source? That's right - the software is available free of charge, and we make some of our revenue by helping others install, use, and troubleshoot it. Take copy for yourself!

AWSH: Containerized tools with lightweight access to AWS CLI and APIs in mind.
GitHub license Docker Pulls

BLOX: Containerized tools for engineering teams who need to work with AWS and IAC every day.
GitHub license Docker Pulls