|
| 1 | +# AWS ECS - Support for Private Registry Authentication |
| 2 | + |
| 3 | +To address issue [#1698](https://github.com/awslabs/aws-cdk/issues/1698), the ECS construct library should provide a way for customers to specify [`repositoryCredentials`](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ContainerDefinition.html#ECS-Type-ContainerDefinition-repositoryCredentials) on their container. |
| 4 | + |
| 5 | +Minimally, this would mean adding a new string field on `ContainerDefinition`, however this doesn't provide any added value in terms of logical grouping or resource creation. We can instead modify the existing ECS CDK construct [`ContainerImage`](https://github.com/awslabs/aws-cdk/blob/master/packages/%40aws-cdk/aws-ecs/lib/container-image.ts) so that repository credentials are specified along with the image they're meant to access. |
| 6 | + |
| 7 | +## General approach |
| 8 | + |
| 9 | +The [`ecs.ContainerImage`](https://github.com/awslabs/aws-cdk/blob/master/packages/%40aws-cdk/aws-ecs/lib/container-image.ts) class already includes constructs for 3 types of images: |
| 10 | + |
| 11 | +* DockerHubImage |
| 12 | +* EcrImage |
| 13 | +* AssetImage |
| 14 | + |
| 15 | +DockerHub images are assumed public, however DockerHub also provides private repositories and there's currently no way to specify credentials for them in the CDK. |
| 16 | + |
| 17 | +There's also no explicit way to specify images hosted outside of DockerHub, AWS, or your local machine. Customers hosting their own registries or using another registry host, like Quay.io or JFrog Artifactory, would need to be able to specify both the image URI and the registry credentials in order to pull their images down for ECS tasks. |
| 18 | + |
| 19 | +Fundamentally, specifying images hosted in DockerHub or elsewhere works the same, because when passed an image URI vs. a plain (or namespaced) image name + tag, the Docker daemon does the right thing and tries to pull the image from the specified registery. |
| 20 | + |
| 21 | +Therefore, we should rename the existing `DockerHubImage` type be more generic and add the ability to optionally specify credentials. |
| 22 | + |
| 23 | + |
| 24 | +## Code changes |
| 25 | + |
| 26 | +Given the above, we should make the following changes to support private registry authentication: |
| 27 | + |
| 28 | +1. Define `RepositoryCredentials` interface & class, add to `IContainerImage` |
| 29 | +2. Rename `DockerHubImage` construct to be more generic, optionally accept and set `RepositoryCreds` |
| 30 | + |
| 31 | + |
| 32 | +# Part 1: How to define registry credentials |
| 33 | + |
| 34 | +For extensibility, we can define a new `IRepositoryCreds` interface to house the AWS Secrets Manager secret with the creds and a new `RepositoryCreds` class which satisfies it using specific constructs (e.g., "fromSecret"). |
| 35 | + |
| 36 | +```ts |
| 37 | +export interface IRepositoryCreds { |
| 38 | + readonly secret: secretsManager.Secret; |
| 39 | +} |
| 40 | + |
| 41 | +export class RepositoryCreds { |
| 42 | + public readonly secret: secretsManager.Secret; |
| 43 | + |
| 44 | + public static fromSecret(secret: secretsManager.Secret) { |
| 45 | + this.secret = secret; |
| 46 | + } |
| 47 | + |
| 48 | + public bind(containerDefinition: ContainerDefinition): void { |
| 49 | + // grant the execution role read access so the secret can be read prior to image pull |
| 50 | + this.secret.grantRead(containerDefinition.taskDefinition.obtainExecutionRole()); |
| 51 | + } |
| 52 | +} |
| 53 | +``` |
| 54 | + |
| 55 | +The `IContainerImage` interface will be updated to include an optional `repositoryCredentials` property: |
| 56 | +```ts |
| 57 | +export interface IContainerImage { |
| 58 | + // ... |
| 59 | + readonly imageName: string; |
| 60 | + |
| 61 | + /** |
| 62 | + * NEW: The credentials required to access the image |
| 63 | + */ |
| 64 | + readonly repositoryCredentials?: IRepositoryCreds; |
| 65 | + |
| 66 | + // ... |
| 67 | + bind(containerDefinition: ContainerDefinition): void; |
| 68 | +} |
| 69 | +``` |
| 70 | + |
| 71 | + |
| 72 | +# Part 2: Rename `DockerHubImage` class to `WebHostedImage`, add optional creds |
| 73 | + |
| 74 | +The `DockerHubImage` construct will be renamed to `WebHostedImage`, and augmented to take in optional "credentials" via keyword props: |
| 75 | +```ts |
| 76 | +// define props |
| 77 | +export interface WebHostedImageProps { |
| 78 | + credentials: RepositoryCreds; |
| 79 | +} |
| 80 | + |
| 81 | +// "DockerHubImage" class --> "WebHostedImage" |
| 82 | +export class WebHostedImage implements IContainerImage { |
| 83 | + public readonly imageName: string; |
| 84 | + public readonly credentials: IRepositoryCreds; |
| 85 | + |
| 86 | + // add credentials to constructor |
| 87 | + constructor(imageName: string, props: WebHostedImageProps) { |
| 88 | + this.imageName = imageName |
| 89 | + this.credentials = props.credentials |
| 90 | + } |
| 91 | + |
| 92 | + public bind(_containerDefinition: ContainerDefinition): void { |
| 93 | + // bind repositoryCredentials to ContainerDefinition |
| 94 | + this.repositoryCredentials.bind(); |
| 95 | + } |
| 96 | +} |
| 97 | +``` |
| 98 | + |
| 99 | +We will also update the API on `ContainerImage` to match: |
| 100 | +```ts |
| 101 | +export class ContainerImage { |
| 102 | + //... |
| 103 | + public static fromInternet(imageName: string, props: WebHostedImageProps) { |
| 104 | + return new WebHostedImage(imageName, props); |
| 105 | + } |
| 106 | + // ... |
| 107 | + |
| 108 | +} |
| 109 | +``` |
| 110 | + |
| 111 | +Example use: |
| 112 | +```ts |
| 113 | +const taskDefinition = new ecs.Ec2TaskDefinition(stack, 'TaskDef'); |
| 114 | + |
| 115 | +const secret = secretsManager.Secret.import(stack, 'myRepoSecret', { |
| 116 | + secretArn: 'arn:aws:secretsmanager:.....' |
| 117 | +}) |
| 118 | + |
| 119 | +taskDefinition.AddContainer('myPrivateContainer', { |
| 120 | + image: ecs.ContainerImage.fromInternet('userx/test', { |
| 121 | + credentials: ecs.RepositoryCreds.fromSecret(secret) |
| 122 | + }); |
| 123 | +}); |
| 124 | + |
| 125 | +``` |
0 commit comments