Amazon Elastic Container Service
Developer Guide (API Version 2014-11-13)

Specifying Sensitive Data

Amazon ECS enables you to inject sensitive data into your containers by storing your sensitive data in either AWS Secrets Manager secrets or AWS Systems Manager Parameter Store parameters and then referencing them in your container definition. This feature is supported by tasks using both the EC2 and Fargate launch types.

Secrets can be exposed to a container in the following ways:

  • To inject sensitive data into your containers as environment variables, use the secrets container definition parameter.

  • To reference sensitive information in the log configuration of a container, use the secretOptions container definition parameter.

Considerations for Specifying Sensitive Data

The following should be considered when specifying sensitive data for containers:

  • For tasks that use the Fargate launch type, this feature requires that your task use platform version 1.3.0 or later. For information, see AWS Fargate Platform Versions.

  • For tasks that use the EC2 launch type, this feature requires that your container instance have version 1.22.0 or later of the container agent. However, we recommend using the latest container agent version. For information about checking your agent version and updating to the latest version, see Updating the Amazon ECS Container Agent.

  • Sensitive data is injected into your container when the container is initially started. If the secret or Parameter Store parameter is subsequently updated or rotated, the container will not receive the updated value automatically. You must either launch a new task or if your task is part of a service you can update the service and use the Force new deployment option to force the service to launch a fresh task.

  • For Windows tasks that are configured to use the awslogs logging driver, you must also set the ECS_ENABLE_AWSLOGS_EXECUTIONROLE_OVERRIDE environment variable on your container instance. This can be done with User Data using the following syntax:

    <powershell> [Environment]::SetEnvironmentVariable("ECS_ENABLE_AWSLOGS_EXECUTIONROLE_OVERRIDE", $TRUE, "Machine") Initialize-ECSAgent -Cluster <cluster name> -EnableTaskIAMRole -LoggingDrivers '["json-file","awslogs"]' </powershell>
  • This feature is not available in the GovCloud (US-East) region.

Injecting Sensitive Data as an Environment Variable

Within your container definition, specify secrets with the name of the environment variable to set in the container and the full ARN of either the Secrets Manager secret or Systems Manager Parameter Store parameter containing the sensitive data to present to the container. The parameter that you reference must be from within the same account but can be from a different Region than the container using the parameter.

Important

If the Systems Manager Parameter Store parameter exists in the same Region as the task you are launching, then you can use either the full ARN or name of the parameter. If the parameter exists in a different Region, then the full ARN must be specified.

For a full tutorial on creating an Secrets Manager secret and injecting it into a container as an environment variable, see Tutorial: Specifying Sensitive Data Using Secrets Manager Secrets.

The following is a snippet of a task definition showing the format when referencing an Secrets Manager secret.

{ "containerDefinitions": [{ "secrets": [{ "name": "environment_variable_name", "valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:secret_name-AbCdEf" }] }] }

The following is a snippet of a task definition showing the format when referencing an Systems Manager Parameter Store parameter.

{ "containerDefinitions": [{ "secrets": [{ "name": "environment_variable_name", "valueFrom": "arn:aws:ssm:region:aws_account_id:parameter/parameter_name" }] }] }

Injecting Sensitive Data in a Log Configuration

Within your container definition, when specifying a logConfiguration you can specify secretOptions with the name of the log driver option to set in the container and the full ARN of either the Secrets Manager secret or Systems Manager Parameter Store parameter containing the sensitive data to present to the container. The parameter that you reference must be from within the same account but can be from a different Region than the container using the parameter.

Important

If the Systems Manager Parameter Store parameter exists in the same Region as the task you are launching, then you can use either the full ARN or name of the parameter. If the parameter exists in a different Region, then the full ARN must be specified.

The following is a snippet of a task definition showing the format when referencing an Secrets Manager secret.

{ "containerDefinitions": [{ "logConfiguration": [{ "logDriver": "splunk", "options": { "splunk-url": "https://cloud.splunk.com:8080" }, "secretOptions": [{ "name": "splunk-token", "valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:secret_name-AbCdEf" }] }] }] }

The following is a snippet of a task definition showing the format when referencing an Systems Manager Parameter Store parameter.

{ "containerDefinitions": [{ "logConfiguration": [{ "logDriver": "fluentd", "options": { "tag": "fluentd demo" }, "secretOptions": [{ "name": "fluentd-address", "valueFrom": "arn:aws:ssm:region:aws_account_id:parameter:parameter_name" }] }] }] }

Required IAM Permissions for Amazon ECS Secrets

To use this feature, you must have the Amazon ECS task execution role and reference it in your task definition. This allows the container agent to pull the necessary AWS Systems Manager or Secrets Manager resources. For more information, see Amazon ECS Task Execution IAM Role.

Important

For tasks that use the EC2 launch type, you must use the ECS agent configuration variable ECS_ENABLE_AWSLOGS_EXECUTIONROLE_OVERRIDE=true to use this feature. You can add it to the ./etc/ecs/ecs.config file during container instance creation or you can add it to an existing instance and then restart the ECS agent. For more information, see Amazon ECS Container Agent Configuration.

To provide access to the AWS Systems Manager Parameter Store parameters that you create, manually add the following permissions as an inline policy to the task execution role. For more information, see Adding and Removing IAM Policies.

  • ssm:GetParameters—Required if you are referencing a Systems Manager Parameter Store parameter in a task definition.

  • secretsmanager:GetSecretValue—Required if you are referencing a Secrets Manager secret either directly or if your Systems Manager Parameter Store parameter is referencing a Secrets Manager secret in a task definition.

  • kms:Decrypt—Required only if your secret uses a custom KMS key and not the default key. The ARN for your custom key should be added as a resource.

The following example inline policy adds the required permissions:

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ssm:GetParameters", "secretsmanager:GetSecretValue", "kms:Decrypt" ], "Resource": [ "arn:aws:ssm:<region>:<aws_account_id>:parameter/parameter_name", "arn:aws:secretsmanager:<region>:<aws_account_id>:secret:secret_name", "arn:aws:kms:<region>:<aws_account_id>:key/key_id" ] } ] }

Creating an AWS Secrets Manager Secret

You can use the Secrets Manager console to create a secret for your sensitive data. For more information, see Creating a Basic Secret in the AWS Secrets Manager User Guide.

To create a basic secret

Use Secrets Manager to create a secret for your sensitive data.

  1. Open the Secrets Manager console at https://console.aws.amazon.com/secretsmanager/.

  2. Choose Store a new secret.

  3. For Select secret type, choose Other type of secrets.

  4. Specify the details of your custom secret as Key and Value pairs. For example, you can specify a key of UserName, and then supply the appropriate user name as its value. Add a second key with the name of Password and the password text as its value. You could also add entries for Database name, Server address, TCP port, and so on. You can add as many pairs as you need to store the information you require.

    Alternatively, you can choose the Plaintext tab and enter the secret value in any way you like.

  5. Choose the AWS KMS encryption key that you want to use to encrypt the protected text in the secret. If you don't choose one, Secrets Manager checks to see if there's a default key for the account, and uses it if it exists. If a default key doesn't exist, Secrets Manager creates one for you automatically. You can also choose Add new key to create a custom CMK specifically for this secret. To create your own AWS KMS CMK, you must have permissions to create CMKs in your account.

  6. Choose Next.

  7. For Secret name, type an optional path and name, such as production/MyAwesomeAppSecret or development/TestSecret, and choose Next. You can optionally add a description to help you remember the purpose of this secret later.

    The secret name must be ASCII letters, digits, or any of the following characters: /_+=.@-

  8. (Optional) At this point, you can configure rotation for your secret. For this procedure, leave it at Disable automatic rotation and choose Next.

    For information about how to configure rotation on new or existing secrets, see Rotating Your AWS Secrets Manager Secrets.

  9. Review your settings, and then choose Store secret to save everything you entered as a new secret in Secrets Manager.

Creating an AWS Systems Manager Parameter Store Parameter

You can use the AWS Systems Manager console to create a Systems Manager Parameter Store parameter for your sensitive data. For more information, see Walkthrough: Create and Use a Parameter in a Command (Console) in the AWS Systems Manager User Guide.

To create a Parameter Store parameter

  1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

  2. In the navigation pane, choose Parameter Store, Create parameter.

  3. For Name, type a hierarchy and a parameter name. For example, type test/database_password.

  4. For Description, type an optional description.

  5. For Type, choose String, StringList, or SecureString.

    Note

    • If you choose SecureString, the KMS Key ID field appears. If you don't provide a KMS CMK ID, a KMS CMK ARN, an alias name, or an alias ARN, then the system uses alias/aws/ssm, which is the default KMS CMK for Systems Manager. To avoid using this key, choose a custom key. For more information, see Use Secure String Parameters in the AWS Systems Manager User Guide.

    • When you create a secure string parameter in the console by using the key-id parameter with either a custom KMS CMK alias name or an alias ARN, you must specify the prefix alias/ before the alias. The following is an ARN example:

      arn:aws:kms:us-east-2:123456789012:alias/MyAliasName

      The following is an alias name example:

      alias/MyAliasName
  6. For Value, type a value. For example, MyFirstParameter. If you chose SecureString, the value is masked as you type.

  7. Choose Create parameter.

Creating a Task Definition that References a Secret

You can use the Amazon ECS console to create a task definition that references either a Secrets Manager secret or a Systems Manager Parameter Store parameter.

To create a task definition that specifies a secret

  1. Open the Amazon ECS console at https://console.aws.amazon.com/ecs/.

  2. In the navigation pane, choose Task Definitions, Create new Task Definition.

  3. On the Select launch type compatibility page, choose the launch type for your tasks and choose Next step.

    Note

    This step only applies to Regions that currently support Amazon ECS using AWS Fargate. For more information, see Amazon ECS on AWS Fargate.

  4. For Task Definition Name, type a name for your task definition. Up to 255 letters (uppercase and lowercase), numbers, hyphens, and underscores are allowed.

  5. For Task execution role, either select your existing task execution role or choose Create new role to have one created for you. This role authorizes Amazon ECS to pull private images for your task. For more information, see Required IAM Permissions for Private Registry Authentication.

    Important

    If the Task execution role field does not appear, choose Configure via JSON and manually add the executionRoleArn field to specify your task execution role. The following code shows the syntax:

    "executionRoleArn": "arn:aws:iam::aws_account_id:role/ecsTaskExecutionRole"
  6. For each container to create in your task definition, complete the following steps:

    1. Under Container Definitions, choose Add container.

    2. For Container name, type a name for your container. Up to 255 letters (uppercase and lowercase), numbers, hyphens, and underscores are allowed.

    3. For Image, type the image name or path to your private image. Up to 255 letters (uppercase and lowercase), numbers, hyphens, and underscores are allowed.

    4. Expand Advanced container configuration.

    5. For container secrets referenced as environment variables, under Environment, for Environment variables, complete the following fields:

      1. For Key, enter the name of the environment variable to set in the container. This corresponds to the name field in the secrets section of a container definition.

      2. For Value, choose ValueFrom. For Add value, enter the full ARN of the Secrets Manager secret or the name or full ARN of the AWS Systems Manager Parameter Store parameter that contains the data to present to your container as an environment variable.

        Note

        If the Systems Manager Parameter Store parameter exists in the same Region as the task you are launching, then you can use either the full ARN or name of the secret. If the parameter exists in a different Region, then the full ARN must be specified.

    6. For secrets referenced in the log configuration for a container, under Storage and Logging, for Log configuration, complete the following fields:

      1. Clear the Auto-configure CloudWatch Logs option.

      2. Under Log options, for Key, enter the name of the log configuration option to set.

      3. For Value, choose ValueFrom. For Add value, enter the full ARN or the Secrets Manager secret or the name or full ARN of the AWS Systems Manager Parameter Store parameter that contains the data to present to your log configuration as a log option.

        Note

        If the Systems Manager Parameter Store parameter exists in the same Region as the task you are launching, then you can use either the full ARN or the name of the secret. If the parameter exists in a different Region, then the full ARN must be specified.

    7. Fill out the remaining required fields and any optional fields to use in your container definitions. More container definition parameters are available in the Advanced container configuration menu. For more information, see Task Definition Parameters.

    8. Choose Add.

  7. When your containers are added, choose Create.