DEV Community

Cover image for Getting Started with AWS CLI v2 as a Docker Container

Getting Started with AWS CLI v2 as a Docker Container

AWS CLI is a command-line tool used to interact with, and manage AWS resources. Any task that calls the AWS APIs from the AWS Management Console can also be done from your terminal using the AWS CLI.

Using the CLI is powerful because repetitive tasks can be scripted and automated. For example, you can write a script to show you all the S3 buckets in your account instead of clicking multiple times in the console to get the same result each time.

The AWS CLI version 2 was released on February 10, 2020. It introduced many new features, including the option to install the AWS CLI as a Docker container. Docker is an open-source containerization platform that allows developers to package applications into containers.

Containers contain just the application and its dependencies, making them lightweight and portable across different operating systems.

The advantage of using Docker images is that they are universal and can be easily shared via the DockerHub. Containerization enables you to use the AWS CLI version 2 in a container-based environment without having to manage the installation and dependencies yourself, as was the case with the Python PIP installer for the AWS CLI v1.

What you will learn

In this blog post, we will look at the following;

  • How to download and run the AWS CLI v2 docker image
  • How to share host credentials for programmatic access to AWS
  • How to shorten the Docker command
  • How to update the AWS


  1. An AWS account with an IAM user that has programmatic access.
  2. An access key ID and secret access key for the IAM user. See how to create an IAM user here.
  3. All commands are run on UNIX-based systems. If you are using windows, you can install the Windows system for Linux here to follow up.

Installing Docker

You must have Docker installed on your computer to be able to use AWS CLI v2 docker image. To install Docker, do the following:

  • If you are using macOS or Windows 10, go to to download Docker Desktop. Chose a stable version and click on download.
  • Once the installer is downloaded, double-click on it to install Docker on your computer. The defaults are enough for this tutorial to succeed, so accept all of them.
  • If you are using a Linux distro like Ubuntu, you can follow the official Docker documentation here on how to install it on your computer.

When Docker has finished installing and is running, you should see the Docker's whale icon on your taskbar if you are using Windows. On macOS, the whale icon is on the menu bar near the clock.

To confirm if the Docker installation was successful, type the following command on your terminal;

➜  ~ docker version
Client: Docker Engine - Community
 Cloud integration: 1.0.9
 Version:           20.10.5
 API version:       1.41
 Go version:        go1.13.15
 Git commit:        55c4c88
 Built:             Tue Mar  2 20:13:00 2021
 OS/Arch:           darwin/amd64
 Context:           default
 Experimental:      true
Enter fullscreen mode Exit fullscreen mode

Version: 20.10.5 is proof that you are ready to go to the next step.

Download and run the AWS CLI v2 container.

The official AWS CLI version 2 Docker image is hosted on DockerHub in the amazon/aws-cli repository. Docker Hub is an online public repository for storing and sharing Docker images.

In order to install the AWS CLI on your local computer, you will need to use the docker run command.

When the docker run command is run for the first time, it will check the local cache on your computer for a copy of the AWS CLI, but it wouldn't find it there on the first run. By default, the next step will be to look for and download the image from Docker Hub online.

docker run --rm -it amazon/aws-cli --version
Enter fullscreen mode Exit fullscreen mode

rm flag is for clean up. Docker will automatically remove the file system when the container it exited. This

it flag is for interactive. When the container is run with this flag, you get connected to the container's pseudo-TTY with stdin creating an interactive bash shell in the container. You can then input the commands to interact with your AWS environment.

version flag executes a command to display the version of the AWS CLI.

Alt Text

The download will happen only once from DockerHub. Future docker run commands will run the container directly from a copy in the local docker image cache on your computer so you won't see any downloads. The capture below shows how the command gets executed directly.
Alt Text

Sharing host credentials.

A docker container provides isolation so by default, the CLI will not be able to access the file system on your computer. This means no direct access to configuration scripts and credentials.

In order to speed up your programmatic access via the AWS CLI Docker image, you will need to share your AWS credentials with the container.

It is a common practice to save frequently used configuration settings and credentials in files so as to always avoid retyping them each time you need them. In the case of the AWS CLI, it uses the settings found in the profile named default. You may still override this default behaviour and store your credentials and configurations elsewhere but for the purpose of this tutorial, we will use the default.

If you already have your AWS credentials stored on your local computer, you may skip this step and move straight to mounting the host system's directory to the container. But if you don't, you can save your save your credentials by using the aws configure command and passing the parameters of your secret access key ID and secrete access key

aws configure
AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
Default region name [None]: us-west-2
Default output format [None]: json
Enter fullscreen mode Exit fullscreen mode

The AWS CLI stores sensitive credential information (that you specify with aws configure command) **** in a local file named credentials, in a folder named .aws in your home directory.

In order to share the credentials on your host computer with the AWS CLI v2 Docker container, you will need to mount the host system's ~/.aws directory to the container's /root/.aws.

docker run --rm -it -v ~/.aws:/root/.aws amazon/aws-cli command
Enter fullscreen mode Exit fullscreen mode

After the command is run, the AWS CLI version 2 running in the container will be able to locate the host file information.

Note that we added the -v flag (same as —volume) which is used to bind-mount the AWS credential file to the docker image.

Each time you run the AWS CLI v2 Docker image and mount the AWS credentials, you will be able to execute CLI commands with the permissions allowed for the IAM user.

There is no fun in having to type out such a long command. The good news is that you do not have to do so each time, which leads us to the next task in this tutorial, on how to shorten the Docker command.

Shortening the Docker command

Each time you want to run the AWS CLI docker container, you will practically use the same set of commands to run the container, with docker run, pass the -rm flag to remove the file system when the container is exited and -it to connect to the pseudo-TTY to run bash commands. The good news is that you can use alias' in Linux and macOS or doskey in Windows to avoid typing the same lines each time.

alias aws='docker run --rm -it amazon/aws-cli'
Enter fullscreen mode Exit fullscreen mode

If you always access the host file system to run the AWS CLI with your AWS credentials then it even becomes more important to shorten the repetitive part of the command. The code snippet below shortens it into an alias aws.

alias aws='docker run --rm -it -v ~/.aws:/root/.aws -v $(pwd):/aws amazon/aws-cli'
Enter fullscreen mode Exit fullscreen mode

To test the alias, we are going to simply check the version of the AWS CLI.

aws --version
Enter fullscreen mode Exit fullscreen mode

You can run other AWS commands and receive the same outputs just like you did with the AWS CLI v1.

aws s3 ls
Enter fullscreen mode Exit fullscreen mode

Updating the AWS CLIv2

By default, when we ran the aws cli docker image, it downloaded the latest image by default because we didn't specify tag a specific version. The latest image is always tagged latest. So when next the docker run command is used, only the existing image tagged latest in the cache will be used. Docker run looks first at the local cache for the image so because there is already an image tagged latest, it will not seek to download the latest image from DockerHub until we explicitly tell it to do so.

This is done by passing the latest tag for the image.

docker pull amazon/aws-cli:latest
Enter fullscreen mode Exit fullscreen mode


Many companies are already invested into container-based deployment tools and workflows like Docker. So being able to execute the AWS CLI from a container benefits from the advantages of containers such as portability, isolation and also security. Other tools such as the AWS Serverless Application Model (SAM) also make use of docker for testing applications locally. I personally do not use the AWS CLI v2 docker image in production but I am just experimenting with it. If you have experience with it, please let me know in the comment section.

Further Reading

Top comments (1)

____class____ profile image
jj • Edited

This dockerized approach has a major drawback in my opinion, which is the fact that docker image published by Amazon uses the root user. This combined with bind mounts, will end up messing file ownership on your host.

For example. If your run aws configure, ownership of newly written files in your host's ~/.aws folder will now be set to root. Same if you copy files from S3, etc...