Private registry authentication for tasks - 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).

Private registry authentication for tasks

Use private registry to store your credentials in Amazon Secrets Manager, and then reference them in your task definition. This provides a way to reference container images that exist in private registries outside of Amazon that require authentication in your task definitions. This feature is supported by tasks hosted on Fargate, Amazon EC2 instances, and external instances using Amazon ECS Anywhere.

Important

If your task definition references an image that's stored in Amazon ECR, this topic doesn't apply. For more information, see Using Amazon ECR Images with Amazon ECS in the Amazon Elastic Container Registry User Guide.

For tasks hosted on Amazon EC2 instances, this feature requires version 1.19.0 or later of the container agent. However, we recommend using the latest container agent version. For information about how to check your agent version and update to the latest version, see Updating the Amazon ECS container agent.

For tasks hosted on Fargate, this feature requires platform version 1.2.0 or later. For information, see Fargate Linux platform versions.

Within your container definition, specify the repositoryCredentials object with the details of the secret that you created. The secret you reference can be from a different Amazon Web Services Region or a different account than the task using it.

Note

When using the Amazon ECS API, Amazon CLI, or Amazon SDK, if the secret exists in the same Amazon Web Services Region as the task that you're launching then you can use either the full ARN or name of the secret. If the secret exists in a different account, the full ARN of the secret must be specified. When using the Amazon Web Services Management Console, the full ARN of the secret must be specified always.

The following is a snippet of a task definition that shows the required parameters:

Substitute private-repo with the private repository host name and private-image with the image name.

"containerDefinitions": [
    {
        "image": "private-repo/private-image",
        "repositoryCredentials": {
            "credentialsParameter": "arn:aws:secretsmanager:region:aws_account_id:secret:secret_name"
        }
    }
]
Note

Another method of enabling private registry authentication uses Amazon ECS container agent environment variables to authenticate to private registries. This method is only supported for tasks hosted on Amazon EC2 instances. For more information, see Configuring Amazon ECS container instances for private Docker images .

To use private registry

  1. The Amazon ECS task execution role is required to use this feature. This allows the container agent to pull the container image. For more information, see Amazon ECS task execution IAM role.

    To provide access to the secrets that you create, add the following permissions as an inline policy to the task execution role. For more information, see Adding and Removing IAM Policies.

    • secretsmanager:GetSecretValue

    • kms:Decrypt—Required only if your key uses a custom KMS key and not the default key. The Amazon Resource Name (ARN) for your custom key must be added as a resource.

    The following is an example inline policy that adds the permissions.

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

  2. Use Amazon Secrets Manager to create a secret for your private registry credentials. For information about how to create a secret, see Create an Amazon Secrets Manager secret in the Amazon Secrets Manager User Guide.

    Enter your private registry credentials using the following format:

    {
  "username" : "privateRegistryUsername",
  "password" : "privateRegistryPassword"
}

  3. Register a task definition. For more information, see Creating a task definition using the console.