What is the best way to pass AWS credentials to a Docker container?
Solution 1
The best way is to use IAM Role and do not deal with credentials at all. (see http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html )
Credentials could be retrieved from http://169.254.169.254.....
Since this is a private ip address, it could be accessible only from EC2 instances.
All modern AWS client libraries "know" how to fetch, refresh and use credentials from there. So in most cases you don't even need to know about it. Just run ec2 with correct IAM role and you good to go.
As an option you can pass them at the runtime as environment variables ( i.e docker run -e AWS_ACCESS_KEY_ID=xyz -e AWS_SECRET_ACCESS_KEY=aaa myimage
)
You can access these environment variables by running printenv at the terminal.
Solution 2
A lot has changed in Docker since this question was asked, so here's an attempt at an updated answer.
First, specifically with AWS credentials on containers already running inside of the cloud, using IAM roles as Vor suggests is a really good option. If you can do that, then add one more plus one to his answer and skip the rest of this.
Once you start running things outside of the cloud, or have a different type of secret, there are two key places that I recommend against storing secrets:
-
Environment variables: when these are defined on a container, every process inside the container has access to them, they are visible via /proc, apps may dump their environment to stdout where it gets stored in the logs, and most importantly, they appear in clear text when you inspect the container.
-
In the image itself: images often get pushed to registries where many users have pull access, sometimes without any credentials required to pull the image. Even if you delete the secret from one layer, the image can be disassembled with common Linux utilities like
tar
and the secret can be found from the step where it was first added to the image.
So what other options are there for secrets in Docker containers?
Option A: If you need this secret only during the build of your image, cannot use the secret before the build starts, and do not have access to BuildKit yet, then a multi-stage build is a best of the bad options. You would add the secret to the initial stages of the build, use it there, and then copy the output of that stage without the secret to your release stage, and only push that release stage to the registry servers. This secret is still in the image cache on the build server, so I tend to use this only as a last resort.
Option B: Also during build time, if you can use BuildKit which was released in 18.09, there are currently experimental features to allow the injection of secrets as a volume mount for a single RUN line. That mount does not get written to the image layers, so you can access the secret during build without worrying it will be pushed to a public registry server. The resulting Dockerfile looks like:
# syntax = docker/dockerfile:experimental
FROM python:3
RUN pip install awscli
RUN --mount=type=secret,id=aws,target=/root/.aws/credentials aws s3 cp s3://... ...
And you build it with a command in 18.09 or newer like:
DOCKER_BUILDKIT=1 docker build -t your_image --secret id=aws,src=$HOME/.aws/credentials .
Option C: At runtime on a single node, without Swarm Mode or other orchestration, you can mount the credentials as a read only volume. Access to this credential requires the same access that you would have outside of docker to the same credentials file, so it's no better or worse than the scenario without docker. Most importantly, the contents of this file should not be visible when you inspect the container, view the logs, or push the image to a registry server, since the volume is outside of that in every scenario. This does require that you copy your credentials on the docker host, separate from the deploy of the container. (Note, anyone with the ability to run containers on that host can view your credential since access to the docker API is root on the host and root can view the files of any user. If you don't trust users with root on the host, then don't give them docker API access.)
For a docker run
, this looks like:
docker run -v $HOME/.aws/credentials:/home/app/.aws/credentials:ro your_image
Or for a compose file, you'd have:
version: '3'
services:
app:
image: your_image
volumes:
- $HOME/.aws/credentials:/home/app/.aws/credentials:ro
Option D: With orchestration tools like Swarm Mode and Kubernetes, we now have secrets support that's better than a volume. With Swarm Mode, the file is encrypted on the manager filesystem (though the decryption key is often there too, allowing the manager to be restarted without an admin entering a decrypt key). More importantly, the secret is only sent to the workers that need the secret (running a container with that secret), it is only stored in memory on the worker, never disk, and it is injected as a file into the container with a tmpfs mount. Users on the host outside of swarm cannot mount that secret directly into their own container, however, with open access to the docker API, they could extract the secret from a running container on the node, so again, limit who has this access to the API. From compose, this secret injection looks like:
version: '3.7'
secrets:
aws_creds:
external: true
services:
app:
image: your_image
secrets:
- source: aws_creds
target: /home/user/.aws/credentials
uid: '1000'
gid: '1000'
mode: 0700
You turn on swarm mode with docker swarm init
for a single node, then follow the directions for adding additional nodes. You can create the secret externally with docker secret create aws_creds $HOME/.aws/credentials
. And you deploy the compose file with docker stack deploy -c docker-compose.yml stack_name
.
I often version my secrets using a script from: https://github.com/sudo-bmitch/docker-config-update
Option E: Other tools exist to manage secrets, and my favorite is Vault because it gives the ability to create time limited secrets that automatically expire. Every application then gets its own set of tokens to request secrets, and those tokens give them the ability to request those time limited secrets for as long as they can reach the vault server. That reduces the risk if a secret is ever taken out of your network since it will either not work or be quick to expire. The functionality specific to AWS for Vault is documented at https://www.vaultproject.io/docs/secrets/aws/index.html
Solution 3
Yet another approach is to create temporary read-only volume in docker-compose.yaml. AWS CLI and SDK (like boto3 or AWS SDK for Java etc.) are looking for default
profile in ~/.aws/credentials
file.
If you want to use other profiles, you just need also to export AWS_PROFILE variable before running docker-compose
command.
export AWS_PROFILE=some_other_profile_name
version: '3'
services:
service-name:
image: docker-image-name:latest
environment:
- AWS_PROFILE=${AWS_PROFILE}
volumes:
- ~/.aws/:/root/.aws:ro
In this example, I used root user on docker. If you are using other user, just change /root/.aws
to user home directory.
:ro
- stands for read-only docker volume
It is very helpful when you have multiple profiles in ~/.aws/credentials
file and you are also using MFA. Also helpful when you want to locally test docker-container before deploying it on ECS on which you have IAM Roles, but locally you don't.
Solution 4
Another approach is to pass the keys from the host machine to the docker container. You may add the following lines to the docker-compose
file.
services:
web:
build: .
environment:
- AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID}
- AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY}
- AWS_DEFAULT_REGION=${AWS_DEFAULT_REGION}
Solution 5
The following one-liner works for me even when my credentials are set up by aws-okta or saml2aws:
$ docker run -v$HOME/.aws:/root/.aws:ro \
-e AWS_ACCESS_KEY_ID \
-e AWS_CA_BUNDLE \
-e AWS_CLI_FILE_ENCODING \
-e AWS_CONFIG_FILE \
-e AWS_DEFAULT_OUTPUT \
-e AWS_DEFAULT_REGION \
-e AWS_PAGER \
-e AWS_PROFILE \
-e AWS_ROLE_SESSION_NAME \
-e AWS_SECRET_ACCESS_KEY \
-e AWS_SESSION_TOKEN \
-e AWS_SHARED_CREDENTIALS_FILE \
-e AWS_STS_REGIONAL_ENDPOINTS \
amazon/aws-cli s3 ls
Please note that for advanced use cases you might need to allow rw
(read-write) permissions, so omit the ro
(read-only) limitation when mounting the .aws
volume in -v$HOME/.aws:/root/.aws:ro
Related videos on Youtube
suraj chopade
Updated on July 30, 2022Comments
-
suraj chopade almost 2 years
I am running docker-container on Amazon EC2. Currently I have added AWS Credentials to Dockerfile. Could you please let me know the best way to do this?
-
Randy L almost 6 yearsHow about if I am running a Docker container on my laptop which is supposed to also magically work in ECS when I push it there? I am gonna guess I use the --volume flag...someone must have already answered...
-
-
honktronic over 7 yearsIs there a good way to do this during local development/testing that doesn't compromise security in production? I'd love to make sure an image works without deploying it fully.
-
Vor over 7 yearsan alternative that I posted with environment variables works fine in dev/local environment.
-
Akavall about 7 yearsI wonder if this is a typo, but I need to enter
AWS_SECRET_ACCESS_KEY
, notAWS_SECRET_KEY
, anyway your answer was very helpful. Thank You. -
Joe about 6 years@honktronic - I asked myself the same question and came up with this: stackoverflow.com/a/49956609/13087
-
Adam Westbrook over 5 yearsTo put it simply (for those who get to this answer the same way I did); A docker container running on EC2 will inherit the same role as the host instance. (I needed an "ELI5" like this when AWS CLI commands in my containers mysteriously worked despite there being no credentials passed to them!)
-
Altair7852 over 5 yearsEasy way to get the key values from your local profile to assign to environment variable for development purposes (as suggested in cameroneckelberry.co/words/…): "aws --profile default configure get aws_access_key_id"
-
John Camerin about 5 yearsThe correct region environment variable is AWS_REGION. See stackoverflow.com/questions/44151982/…
-
prafi about 5 yearsPlease check the official doc which mentions
AWS_DEFAULT_REGION
docs.aws.amazon.com/cli/latest/userguide/… -
John Camerin about 5 yearsWhen I used AWS_DEFAULT_REGION, I got an exception that a default region could not be found. My search led to docs.aws.amazon.com/sdk-for-java/v1/developer-guide/… which specifies AWS_REGION environment variable, and that worked for me.
-
Artur Siepietowski over 4 yearsOn windows .aws` catalogue is located
"%UserProfile%\.aws"
. So I assume that you have to change:- ~/.aws/:/root/.aws:ro
to- %UserProfile%\.aws:/root/.aws:ro
-
wlarcheveque over 4 yearsThis will only work with single build processes and not multistage.
-
Davos about 4 yearsIf you are using temporary credentials then you may also need
AWS_SESSION_TOKEN=${AWS_SESSION_TOKEN}
-
ErikE about 4 years@wlarcheveque Care to elaborate?
-
dragon788 almost 4 yearsBe VERY careful using the
- host:container
syntax, if the file/folder doesn't exist on the host it gets created (as root) and the awscli won't thank you for feeding it a zero byte file. You should use the "long form" that specifies the type is bind, the host path, and the container path on separate lines, this fails if the file doesn't exist, which is what you want in your docker-compose.dev.yml but not in your docker-compose.yml (prod/AWS deploy). -
user793886 over 3 yearsWill this work for windows docker containers or just linux containers? We are dealing with windows docker containers running in windows EC2 and ECS with EC2 windows launch type . Using AWS SDK can i access an AWS service(ex secret manager) by assumed role of host EC2 instance ?
-
piedpiper over 3 yearsdo you need to export AWS_ACCESS_KEY_ID etc. using `export AWS_ACCESS_KEY_ID="myaccesskeyid"? the AWS_ACCESS_KEY_ID env var was undefined for me.
-
Harsh Math about 3 yearsThis is so simple and saved me so much time.. thanks @Vor
-
lukass77 almost 3 yearsHi Abhay - you are missing an "S" on AWS_SECRET_ACCES_KEY
-
wkhatch almost 3 yearswhile passing in the key and secret via env vars is definitely the easiest, it's discouraged, as you'll now have a dependency on long term credentials. IMO, this whole discussion shines a bright light on the horrible disconnect presented (and not at all addressed in the AWS SDK docs) between using the sdk locally, during development, and in production on one of their instances in whatever service you may be using. It's unfortunate, to say the least. I mean, just reading the work arounds demonstrates how crappy this is. Local, local with docker, containerized deployment... all different... meh
-
Abhay Maniyar over 2 yearsThanks @lukass77 for pointing that out. Updated.
-
Jun711 over 2 yearswhat to do when I don't use docker compose?
-
BMitch over 2 years@Jun711 the docker run on the previous line didn't cover that?
-
Jun711 over 2 yearsit doesn't seem to work. This is the command I used
docker run -v $HOME/.aws/credentials:/home/app/.aws/credentials:ro -it -p 8080:8080 imageName:tagName
. The boto3 error message wasUnable to locate credentials
. I am not sure if it matters but the permission for credentials file isls -la $HOME/.aws/credentials
-rw------- -
BMitch over 2 years@Jun711 if you're on linux, the uid of the file on the host needs to match the uid of the container user. Otherwise, I'd recommend posting a new question with a minimal reproducible example to get help with your question.
-
Jun711 over 2 yearsI am on Mac, I changed the container path to root instead of
/home/app/
and it worked.docker run -v $HOME/.aws/credentials:/root/.aws/credentials:ro -it -p 8080:8080 imageName:tagName
Do you know how I can access that root dir? I useddocker exec imageId ls -la
but I couldn't find my aws credentials file there -
Gabriel Simas over 2 yearsYes, worked for me:
docker run -d -e ASPNETCORE_ENVIRONMENT=development -v "%UserProfile%\.aws\credentials":/root/.aws/credentials:ro --name containerName imageName
-
funder7 over 2 yearsSo @wkhatch, how would you solve the problem?
-
funder7 over 2 yearsIt's a working solution, I would avoid to set the file with
777
permissions, as any other user with access to the host will be able to read the credentials file... Not very good, as the point of using env variables is to keep crendentials away from anyone/anything that is not the aws service that needs them! Maybe 744 is more appropriate