How can I securely pass secrets or sensitive information to containers in an Amazon ECS task?

Short description

Passing sensitive data in plaintext can cause security issues. The data might be discoverable in the AWS Management Console or through AWS APIs such as DescribeTaskDefinition.

As a security best practice, pass sensitive information to containers as environment variables. To securely inject data into containers, reference the values stored in Parameter Store, a capability of AWS Systems Manager. You can also use AWS Secrets Manager in an Amazon ECS task definition.

Then, you can expose your sensitive information as environment variables or in the log configuration of a container.

AWS supports data injection only for the following options:

• Tasks that use AWS Fargate platform version 1.3.0 or later with the AWS Fargate launch type
• Container instances that use the amazon-ecs-agent version 1.22.0 or later with the Amazon Elastic Compute Cloud (Amazon EC2) launch type. For more information, see CHANGELOG on the GitHub website.

Resolution

To pass secrets or sensitive information to containers in an Amazon ECS task, complete the following tasks.

Create the IAM role and policies

Complete the following steps:

1. Store your sensitive information in either Parameter Store or Secrets Manager.

   For Parameter Store, run the following command:

   aws ssm put-parameter --type SecureString --name awsExampleParameter --value awsExampleValue

   Note: Replace awsExampleParameter with your own parameters. Replace awsExampleValue with your secret value.

   For Secrets Manager, run the following command:

   aws secretsmanager create-secret --name awsExampleParameter --secret-string awsExampleValue

   Note: Replace awsExampleParameter with your own parameters. Replace awsExampleValue with your secret value.

   The ECS container agent uses a task execution AWS Identity and Access Management (IAM) role to fetch the information. The information is fetched from the Parameter Store or Secrets Manager. The task execution IAM role must grant permissions to the following actions: ssm:GetParameters, secretsmanager:GetSecretValue, and kms:Decrypt.

2. Open the IAM console.

3. Create a role with a trust relation for ecs-tasks.amazonaws.com. For example:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Sid": "",
         "Effect": "Allow",
         "Principal": {
           "Service": "ecs-tasks.amazonaws.com"
         },
         "Action": "sts:AssumeRole"
       }
     ]
   }

4. To create an inline policy for your role in the IAM console, choose Roles, select the role that you created.

5. Choose Add inline policy on the Permissions tab, and then choose the JSON tab.

6. Create a policy with the following code:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": [
           "ssm:GetParameters",
           "secretsmanager:GetSecretValue"
         ],
         "Resource": [
           "arn:aws:ssm:us-east-1:awsExampleAccountID:parameter/awsExampleParameter",
           "arn:aws:secretsmanager:us-east-1:awsExampleAccountID:secret:awsExampleParameter*"
         ]
       }
     ]
   }

   Replace us-east-1 and awsExampleAccountID with the AWS Region and account where your parameters are stored. Replace awsExampleParameter with the name of the parameters that you created.

   Note: You can use an AWS Key Management Service (AWS KMS) customer managed key to encrypt data in Parameter Store or Secrets Manager. To use the customer managed key, you need get permissions for kms:Decrypt.

7. (Optional) Attach the managed policy AmazonECSTaskExecutionRolePolicy to the role that you created.

Important: A managed policy is required for tasks that use images stored in Amazon Elastic Container Registry (Amazon ECR) or send logs to Amazon CloudWatch.

Reference sensitive information in the ECS task definition

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshoot AWS CLI errors. Also, make sure that you're using the most recent AWS CLI version.

To use the Amazon ECS console to reference sensitive information in the ECS task definition, complete the following steps:

1. Open the Amazon ECS console.
2. From the navigation pane, choose Task Definitions, and then choose Create new Task Definition.
3. Choose your launch type, and then choose Next step.
4. For Task execution role, choose the task execution IAM role that you created.
5. On the Container Definitions section, under the Environment variables section, choose Add environment variable.
6. For Key, enter a key for your environment variable.
7. On the ValueType dropdown list, choose ValueFrom.
8. In the text box for the key, enter the Amazon Resource Name (ARN) of your Parameter Store or Secrets Manager resource.
   Note: You can also specify secrets in the log driver configuration.

To use the AWS CLI to reference sensitive information in the ECS task definition, complete the following steps:

1. Use the secrets section to reference Parameter Store or Secrets Manager resources in the task definition as environment variables. Or, use the secretOptions section to reference Parameter Store or Secrets Manager as log configuration options.

   Example:

   {
     "requiresCompatibilities": [
       "EC2"
     ],
     "family": "Web",
     "networkMode": "awsvpc",
     "containerDefinitions": [
       {
         "name": "web",
         "image": "httpd",
         "memory": 128,
         "essential": true,
         "portMappings": [
           {
             "containerPort": 80,
             "protocol": "tcp"
           }
         ],
         "logConfiguration": {
           "logDriver": "splunk",
           "options": {
             "splunk-url": "https://sample.splunk.com:8080"
           },
           "secretOptions": [
             {
               "name": "splunk-token",
               "valueFrom": "arn:aws:secretsmanager:us-east-1:awsExampleAccountID:secret:awsExampleParameter"
             }
           ]
         },
         "secrets": [
           {
             "name": "DATABASE_PASSWORD",
             "valueFrom": "arn:aws:ssm:us-east-1:awsExampleAccountID:parameter/awsExampleParameter"
           }
         ]
       }
     ],
     "executionRoleArn": "arn:aws:iam::awsExampleAccountID:role/awsExampleRoleName"
   }

   Note: In the preceding example, replace us-east-1 and awsExampleAccountID with your Region and account ID. Replace awsExampleParameter with the parameter that you created. Replace awsExampleRoleName with the role that you created.

2. To register the task definition, run the register-task-definition command:

   aws ecs register-task-definition --family-name yourTaskDefinitionFamily --cli-input-json file://pathToYourJsonFile

When you launch a task with this definition, the ECS container agent automatically resolves the secrets. Then, the container agent injects the values as environment variables to the container.

Important: When the container is initially started, sensitive data is injected into your container. If the secret or Parameter Store parameter is updated or rotated, then the container doesn't automatically receive the updated value. You must launch a new task. If your task is part of a service, then update the service. Then, to force the service to launch a fresh task, use the Force new deployment option.

To force a new deployment, complete the following steps:

1. Open the Amazon ECS console.
2. Choose Clusters, and then select the cluster with your service.
3. Select the Force New Deployment check box, and then choose Update Service.
   Note: To force a new deployment from the AWS CLI, run the update-service command with the --force-new-deployment flag.