Skip to content

Containerized AWS CLI for LocalStack

Using a containerized version of the AWS CLI is a convenient method for interacting with a LocalStack instance, particularly when the CLI is not installed natively on the host machine or when operating within a strictly containerized environment^[README.md]. This approach leverages Docker networking to allow the official amazon/aws-cli image to communicate with the LocalStack service running in a separate container^[README.md].

Configuration

To ensure the AWS CLI container can resolve the LocalStack service address, both the LocalStack container and the AWS CLI container must be attached to the same Docker network^[README.md]. A common practice is to create an external network named localstack and configure the Docker Compose file to use it^[README.md].

The AWS CLI container requires specific environment variables and volume mounts to function correctly with LocalStack:

  • Network: Connected to the localstack network^[README.md].
  • Endpoint: The --endpoint-url must be set to http://localstack:4566^[README.md].
  • Credentials: Credentials are often mounted from the host (e.g., -v ~/.aws:/root/.aws), though LocalStack typically ignores the actual values of the keys^[README.md].
  • Hostname: The LOCALSTACK_HOSTNAME environment variable is often set to localstack^[README.md].

Usage

Executing commands involves running the Docker image with the necessary flags appended by the desired AWS command^[README.md].

docker run --network localstack --rm -it amazon/aws-cli --endpoint-url=http://localstack:4566 <COMMAND>

For improved usability, it is common to create a shell alias (e.g., laws) that encapsulates the Docker run configuration^[README.md].

alias laws='docker run --network localstack -it -v ~/.aws:/root/.aws -e LOCALSTACK_HOSTNAME=localstack amazon/aws-cli --endpoint-url=http://localstack:4566'

Sources

^[README.md]