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.
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.
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.
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:
--rmindicates to clean up the container when the command exits. By default, a container’s file system persists even after the container exits.
-itindicates 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
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
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.
amazon/aws-cli Docker image currently supports two sets of tags: the
latest tag and
<major.minor.patch> version tags.
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
$ 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
$ alias aws='docker run --rm -ti -v ~/.aws:/root/.aws -v $(pwd):/aws amazon/aws-cli:2.0.6'
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.