AWS Developer Tools Blog

AWS CLI v2 Docker image

With the release of 2.0.6 of the AWS CLI v2, we are excited to announce the AWS CLI v2 is now available as a Docker image.

This allows users to use the AWS CLI v2 in a container-based environment without having to manage the installation of the AWS CLI v2 themselves. While there are a variety of ways to utilize this Docker image, especially in a CI/CD setting, I am going to cover how we can run the AWS CLI v2 in a Docker container on our local machine.

Prerequisites

In order to use the AWS CLI v2 Docker image, you must have the docker CLI installed. To install the docker CLI, you can follow these instructions from the Docker website.

Getting started

Once docker is installed, we can then run the AWS CLI v2 in a container using the docker run command:

$ docker run --rm -it amazon/aws-cli --version
aws-cli/2.0.6 Python/3.7.3 Linux/4.9.184-linuxkit botocore/2.0.0dev10

This command is equivalent to running aws --version on a locally installed version of the AWS CLI v2, but instead running the command from within a Docker container.

Specifically, docker run downloads the amazon/aws-cli image from DockerHub if has not been already downloaded, spins up a container from the amazon/aws-cli image, and executes aws --version in the container. Note that the aws executable was not specified in the docker run command because the entrypoint for the image is defined as the aws executable. Thus, any arguments following amazon/aws-cli will be proxied as commands and parameters to the aws executable in the container. As to the other docker run options in the provided command:

  • --rm indicates to clean up the container when the command exits. By default, a container’s file system persists even after the container exits.
  • -it indicates to open a pseudo-TTY with stdin. This allows you to provide input to the AWS CLI v2 while its running in a container such as with the aws configure and aws help commands.

For more information on the docker run command, please refer to the reference guide from the Docker website.

Providing credentials and configuration

Because the AWS CLI v2 is being run in a container, the container prevents the CLI from accessing configuration and credentials on the host system. If we want to share file system credentials and configuration from the host system to the container, we can mount the host system’s ~/.aws directory to the container with the -v flag when executing the docker run command:

$ docker run --rm -ti -v ~/.aws:/root/.aws amazon/aws-cli s3 ls
2020-03-25 00:30:48 aws-cli-docker-demo

In this docker run command, the ~/.aws directory is mounted to the container at /root/.aws, which allows the AWS CLI v2 running in the container to locate credentials and configuration. Note that it is mounted at /root/.aws because the AWS CLI v2 is ran as root by default in the container. For more information about the -v flag and mounting, please refer to the reference guide from the Docker website.

Interacting with host file system

For some AWS CLI v2 commands, you’ll want to either read files from the host system in the container or write files from the container to the host system. This can be accomplished with the -v flag as well. For example, we can download an S3 object to your local file system:

$ docker run --rm -ti -v ~/.aws:/root/.aws -v $(pwd):/aws amazon/aws-cli s3 cp s3://aws-cli-docker-demo/hello .
download: s3://aws-cli-docker-demo/hello to ./hello

And confirm the downloaded file exists the local file system:

$ cat hello
Hello from Docker!

In the previous docker run command, we mounted the current working directory of the host to the container’s /aws directory, which is the working directory for the container. So by downloading the object hello to the current working directory of the container (/aws), the file is saved to the host system’s current working directory as well.

Tags

The amazon/aws-cli Docker image currently supports two sets of tags: the latest tag and <major.minor.patch> version tags.

latest tag

In the previous docker run commands, we were implicitly using the latest tag. This tag represents the latest released version of the AWS CLI. You can also explicitly request the latest by appending :latest to the image name. For example:

$ docker run --rm -it amazon/aws-cli:latest --version

It is recommended to use the latest tag whenever you want to just use the latest version of the AWS CLI. If you are using docker run, it is important to note that it will only download the image if it is not on your system. So it is possible to be using an image that is tagged as latest on your system that is out of date with the image tagged as latest on DockerHub. In order to ensure you are using the latest version of the AWS CLI v2, it is recommended to manually pull the image tagged as latest first:

$ docker pull amazon/aws-cli:latest

It is also important to note that there are no backwards compatibility guarantees between updates to the latest tag. If backwards compatibility is required for your use case, it is recommended to use a specific <major.minor.patch> version tag instead.

<major.minor.patch> version tags

These tags represent specific released versions of the AWS CLI v2. So if we wanted to use the 2.0.6 version of the AWS CLI, we can specify 2.0.6 as the tag:

$ docker run --rm -it amazon/aws-cli:2.0.6 --version
aws-cli/2.0.6 Python/3.7.3 Linux/4.9.184-linuxkit botocore/2.0.0dev10

If you are planning to use the amazon/aws-cli Docker image in production, it is recommended to pin to a specific <major.minor.patch> tag as version tags are immutable; they will only ever be pushed to once.

Shortening command usage

In the previous sections, the docker run commands were quite long. If you plan to be manually running the AWS CLI v2 from a Docker container in your workflow, you can set the following alias:

$ alias aws='docker run --rm -ti -v ~/.aws:/root/.aws -v $(pwd):/aws amazon/aws-cli'

This will allow you to run the AWS CLI v2 from within a Docker container as if it was installed on your host system:

$ aws --version
aws-cli/2.0.6 Python/3.7.3 Linux/4.9.184-linuxkit botocore/2.0.0dev10

You can also pin the version of the AWS CLI v2 to use by pinning to a tag in your alias. For example, this alias will pin the version of the AWS CLI v2 to 2.0.6:

$ alias aws='docker run --rm -ti -v ~/.aws:/root/.aws -v $(pwd):/aws amazon/aws-cli:2.0.6'

Next steps

For more information on the Docker image, please visit its DockerHub repository and the user guide for the AWS CLI v2. For any issues or feature requests related to the Docker image, please file an issue on our GitHub repository. We look forward to hearing your feedback.