How do I manage secrets and access keys for Amazon ECS tasks and services?

Resolution

To manage secrets and access keys that aren't hardcoded, use AWS Secrets Manager or Parameter Store, a capability of AWS Systems Manager.

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

Create a secret

To create a secret, use the Secrets Manager console or the AWS CLI. To use Parameter Store to store the secret, run the following put-parameter command:

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

Note: Replace awsExampleParameter with your parameter and awsExampleValue with your secret.

Allow Amazon ECS tasks to access your secrets

Amazon ECS uses an AWS Identity and Access Management (IAM) task execution role to get secret information from Secrets Manager or Parameter Store. Create an IAM policy for the role that has the minimum required permissions. If you use Secrets Manager, then the IAM role must have secretsmanager:GetSecretValue permissions. If you use Parameter Store, then the IAM role must have ssm:GetParameters and kms:Decrypt permissions.

Example Secrets Manager policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "secretsmanager:GetSecretValue",
      "Resource": "arn:aws:secretsmanager:region:account-id:secret:secret-name"
    }
  ]
}

Note: Replace arn:aws:secretsmanager:region:account-id:secret:secret-name with your secret ARN.

Example Parameter Store policy:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ssm:GetParameter",
                "ssm:GetParameters",
                "ssm:GetParameterHistory"
            ],
            "Resource": "arn:aws:ssm:region:account-id:parameter/parameter-name"
        },
        {
            "Effect": "Allow",
            "Action": "kms:Decrypt",
            "Resource": "arn:aws:kms:region:account-id:key/kms-key-id"
        }
    ]
}

Note: Replace arn:aws:ssm:region:account-id:parameter/parameter-name with your parameter's ARN and arn:aws:kms:region:account-id:key/kms-key-id with your AWS Key Management Service (AWS KMS) key.

Attach the IAM policy to the Amazon ECS task execution role.

Access your Amazon ECS task secrets

You can pass sensitive data, such as API keys or credentials, as parameters or environment variables. First, modify your Amazon ECS task definition to include your environment variables or secret mappings.

Example secret mapping in a task definition:

{
  "name": "MY_SECRET",
  "valueFrom": "arn:aws:secretsmanager:region:account-id:secret:secret-name"
}

Then, pass the environment variables to the Amazon ECS container.

Example containerDefinitions in task definition:

  - name: my-container
    environment:
      - name: Example_PASSWORD
        valueFrom: arn:aws:ssm:us-west-2:123456789012:parameter/my-app/example-password

Manage your secrets with CI/CD

Use environment variables to dynamically pass secrets during continuous integration and continuous delivery (CI/CD) deployments. Get secrets from Secrets Manager or Parameter Store in deployment scripts. Don't hardcode secrets in task definitions. Instead, use parameters or placeholders. For more information and best practices, see Strengthen the DevOps pipeline and protect data with AWS Secrets Manager, AWS KMS, and AWS Certificate Manager.

For example, if you use AWS CodePipeline, then configure a build step that uses the AWS CLI to get secrets:

bashCopy codeaws secretsmanager get-secret-value --secret-id secret-name --query 'SecretString' --output text

Note: Replace secret-name with your secret.

Troubleshoot issues with secrets management

If you encounter issues when you use secrets in Amazon ECS, then take the following actions:

• Make sure that the Amazon ECS task's IAM role has the correct secretsmanager:GetSecretValue or ssm:GetParameter permissions.

• If you receive Denied errors, then make sure that the IAM policy is attached to the correct Amazon ECS task execution role. Also, make sure that the IAM policy's secret ARN is accurate.

• If Amazon ECS can't get the secret, then verify that you're using the correct AWS Region and secret. To test the secret, run the following get-secret-value command outside of Amazon ECS:

  aws secretsmanager get-secret-value --secret-id secret-name --region region-code

  Note: Replace secret-name with you secret and region-code with your Region.