Pass sensitive data to an Amazon ECS container - Amazon Elastic Container Service
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Pass sensitive data to an Amazon ECS container

You can safely pass sensitive data, such as credentials to a database, into your container.

Secrets, such as API keys and database credentials, are frequently used by applications to gain access other systems. They often consist of a username and password, a certificate, or API key. Access to these secrets should be restricted to specific IAM principals that are using IAM and injected into containers at runtime.

Secrets can be seamlessly injected into containers from Amazon Secrets Manager and Amazon EC2 Systems Manager Parameter Store. These secrets can be referenced in your task as any of the following.

  1. They're referenced as environment variables that use the secrets container definition parameter.

  2. They're referenced as secretOptions if your logging platform requires authentication. For more information, see logging configuration options.

  3. They're referenced as secrets pulled by images that use the repositoryCredentials container definition parameter if the registry where the container is being pulled from requires authentication. Use this method when pulling images from Amazon ECR Public Gallery. For more information, see Private registry authentication for tasks.

We recommend that you do the following when setting up secrets management.

Use Amazon Secrets Manager or Amazon Systems Manager Parameter Store for storing secret materials

You should securely store API keys, database credentials, and other secret materials in Secrets Manager or as an encrypted parameter in Systems Manager Parameter Store. These services are similar because they're both managed key-value stores that use Amazon KMS to encrypt sensitive data. Secrets Manager, however, also includes the ability to automatically rotate secrets, generate random secrets, and share secrets across accounts. If these important features, use Secrets Manager otherwise use encrypted parameters.


Secrets that are referenced in tasks aren't rotated automatically. If your secret changes, you must force a new deployment or launch a new task to retrieve the latest secret value. For more information, see the following topics:

Retrieve data from an encrypted Amazon S3 bucket

You should store secrets in an encrypted Amazon S3 bucket and use task roles to restrict access to those secrets. This prevents value of environment variables can inadvertently leak in logs and are revealed when running docker inspect. When you do this, your application must be written to read the secret from the Amazon S3 bucket. For instructions, see Setting default server-side encryption behavior for Amazon S3 buckets.

Mount the secret to a volume using a sidecar container

Because there's an elevated risk of data leakage with environment variables, you should run a sidecar container that reads your secrets from Amazon Secrets Manager and write them to a shared volume. This container can run and exit before the application container by using Amazon ECS container ordering. When you do this, the application container subsequently mounts the volume where the secret was written. Like the Amazon S3 bucket method, your application must be written to read the secret from the shared volume. Because the volume is scoped to the task, the volume is automatically deleted after the task stops. For an example of a sidecar container, see the aws-secret-sidecar-injector project.

On Amazon EC2, the volume that the secret is written to can be encrypted with a Amazon KMS customer managed key. On Amazon Fargate, volume storage is automatically encrypted using a service managed key.