Cdk-ecr-deployment NPM

cdk-ecr-deployment

CDK construct to synchronize single docker image between docker registries.

!IMPORTANT
Please use the latest version of this package, which is v4.
(Older versions are no longer supported).

Features

Copy image from ECR/external registry to (another) ECR/external registry
Copy an archive tarball image from s3 to ECR/external registry

Examples

import { DockerImageAsset } from 'aws-cdk-lib/aws-ecr-assets';

const image = new DockerImageAsset(this, 'CDKDockerImage', {
  directory: path.join(__dirname, 'docker'),
});

// Copy from cdk docker image asset to another ECR.
new ecrdeploy.ECRDeployment(this, 'DeployDockerImage1', {
  src: new ecrdeploy.DockerImageName(image.imageUri),
  dest: new ecrdeploy.DockerImageName(`${cdk.Aws.ACCOUNT_ID}.dkr.ecr.us-west-2.amazonaws.com/my-nginx:latest`),
});

// Copy from docker registry to ECR.
new ecrdeploy.ECRDeployment(this, 'DeployDockerImage2', {
  src: new ecrdeploy.DockerImageName('nginx:latest'),
  dest: new ecrdeploy.DockerImageName(`${cdk.Aws.ACCOUNT_ID}.dkr.ecr.us-west-2.amazonaws.com/my-nginx2:latest`),
});

// Copy from private docker registry to ECR.
// The format of secret in aws secrets manager must be either:
// - plain text in format <username>:<password>
// - json in format {"username":"<username>","password":"<password>"}
new ecrdeploy.ECRDeployment(this, 'DeployDockerImage3', {
  src: new ecrdeploy.DockerImageName('javacs3/nginx:latest', 'username:password'),
  // src: new ecrdeploy.DockerImageName('javacs3/nginx:latest', 'aws-secrets-manager-secret-name'),
  // src: new ecrdeploy.DockerImageName('javacs3/nginx:latest', 'arn:aws:secretsmanager:us-west-2:000000000000:secret:id'),
  dest: new ecrdeploy.DockerImageName(`${cdk.Aws.ACCOUNT_ID}.dkr.ecr.us-west-2.amazonaws.com/my-nginx3:latest`),
}).addToPrincipalPolicy(new iam.PolicyStatement({
  effect: iam.Effect.ALLOW,
  actions: [
    'secretsmanager:GetSecretValue',
  ],
  resources: ['*'],
}));

Sample: test/example.ecr-deployment.ts

After cloning the repository, install dependencies and run a full build:

yarn --frozen-lockfile --check-files
yarn build

Then run the example like this:

# Run the following command to try the sample.
npx cdk deploy -a "npx ts-node -P tsconfig.dev.json --prefer-ts-exts test/example.ecr-deployment.ts"

To run the DockerHub example you will first need to setup a Secret in AWS Secrets Manager to provide DockerHub credentials. Replace username:access-token with your credentials. Please note that Secrets will occur a cost.

aws secretsmanager create-secret --name DockerHubCredentials --secret-string "username:access-token"

From the output, copy the ARN of your new secret and export it as env variable

export DOCKERHUB_SECRET_ARN="<ARN>"

Finally run:

# Run the following command to try the sample.
npx cdk deploy -a "npx ts-node -P tsconfig.dev.json --prefer-ts-exts test/dockerhub-example.ecr-deployment.ts"

If your Secret is encrypted, you might have to adjust the example to also grant decrypt permissions.

API

Tech Details & Contribution

The core of this project relies on containers/image which is used by Skopeo. Please take a look at those projects before contribution.

To support a new docker image source(like docker tarball in s3), you need to implement image transport interface. You could take a look at docker-archive transport for a good start.

Any error in the custom resource provider will show up in the CloudFormation error log as Invalid PhysicalResourceId, because of this: https://github.com/aws/aws-lambda-go/issues/107. You need to go into the CloudWatch Log Group to find the real error.