Private registry authentication for jobs - Amazon Batch
Required IAM permissions for private registry authenticationUsing private registry authentication
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 jobs

Private registry authentication for jobs using Amazon Secrets Manager enables you to store your credentials securely and then reference them in your job definition. This provides a way to reference container images that exist in private registries outside of Amazon that require authentication in your job definitions. This feature is supported by jobs hosted on Amazon EC2 instances and Fargate.

Important

If your job 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 jobs 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 in the Amazon Elastic Container Service Developer Guide.

For jobs hosted on Fargate, this feature requires platform version 1.2.0 or later. For information, see Amazon Fargate Linux platform versions in the Amazon Elastic Container Service Developer Guide.

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 job using it.

Note

When using the Amazon Batch API, Amazon CLI, or Amazon SDK, if the secret exists in the same Amazon Web Services Region as the job 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 job definition that shows the required parameters:

"containerProperties": [
  {
    "image": "private-repo/private-image",
    "repositoryCredentials": {
      "credentialsParameter": "arn:aws-cn:secretsmanager:region:123456789012:secret:secret_name"
    }
  }
]

Required IAM permissions for private registry authentication

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

To provide access to the secrets that you create, add the following permissions as an inline policy to the 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-cn:secretsmanager:region:123456789012:secret:secret_name",
        "arn:aws-cn:kms:region:123456789012:key/key_id"
      ]
    }
  ]
}

Using private registry authentication

To create a basic secret

Use Amazon Secrets Manager to create a secret for your private registry credentials.

  1. Open the Amazon Secrets Manager console at https://console.amazonaws.cn/secretsmanager/.

  2. Choose Store a new secret.

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

  4. Select Plaintext and enter your private registry credentials using the following format:

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

  5. Choose Next.

  6. For Secret name, enter 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: /_+=.@-.

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

    For instructions on how to configure rotation on new or existing secrets, see Rotating Your Amazon Secrets Manager Secrets.

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

Register a job definition and under Private registry, turn on Private registry authentication. Then, in Secrets Manager ARN or name, enter the Amazon Resource Name (ARN) of the secret. For more information, see Required IAM permissions for private registry authentication.