CdklabsCdkEcrDeployment

cdk-ecr-deployment

CDK construct to synchronize single docker image between docker registries.

Please use the latest version of this package, which is v4.

(Older versions are no longer supported).

Features

• Copy image or multi-architecture image index from ECR/external registry to (another) ECR/external registry
• Copy an archive tarball image from s3 to ECR/external registry

Usage

using Amazon.CDK.AWS.Ecr.Assets;


var image = new DockerImageAsset(this, "CDKDockerImage", new DockerImageAssetProps {
    Directory = Join(__dirname, "docker")
});

// Copy from cdk docker image asset to another ECR.
// Copy from cdk docker image asset to another ECR.
new ECRDeployment(this, "DeployDockerImage1", new ECRDeploymentProps {
    Src = new DockerImageName(image.ImageUri),
    Dest = new DockerImageName($"{cdk.Aws.ACCOUNT_ID}.dkr.ecr.us-west-2.amazonaws.com/my-nginx:latest")
});

// Copy from docker registry to ECR.
// Copy from docker registry to ECR.
new ECRDeployment(this, "DeployDockerImage2", new ECRDeploymentProps {
    Src = new DockerImageName("nginx:latest"),
    Dest = new 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>"}
// 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 ECRDeployment(this, "DeployDockerImage3", new ECRDeploymentProps {
    Src = new 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 DockerImageName($"{cdk.Aws.ACCOUNT_ID}.dkr.ecr.us-west-2.amazonaws.com/my-nginx3:latest")
}).AddToPrincipalPolicy(new PolicyStatement(new PolicyStatementProps {
    Effect = Effect.ALLOW,
    Actions = new [] { "secretsmanager:GetSecretValue" },
    Resources = new [] { "*" }
}));

// Copy multi-architecture image index (manifest) with all architectures.
// Copy multi-architecture image index (manifest) with all architectures.
new ECRDeployment(this, "DeployDockerImage4", new ECRDeploymentProps {
    Src = new DockerImageName("public.ecr.aws/nginx/nginx:latest"),
    Dest = new DockerImageName($"{cdk.Aws.ACCOUNT_ID}.dkr.ecr.us-west-2.amazonaws.com/my-nginx4:manifest"),
    CopyImageIndex = true,
    ArchImageTags = new Dictionary<string, string> {
        { "amd64", "my-nginx-amd64" },
        { "arm64", "my-nginx-arm64" }
    }
});

// Copy image to a public ECR registry.
// The required ecr-public and sts permissions are automatically attached
// when the destination is a public.ecr.aws URI.
// Copy image to a public ECR registry.
// The required ecr-public and sts permissions are automatically attached
// when the destination is a public.ecr.aws URI.
new ECRDeployment(this, "DeployDockerImage5", new ECRDeploymentProps {
    Src = new DockerImageName($"{cdk.Aws.ACCOUNT_ID}.dkr.ecr.us-west-2.amazonaws.com/my-nginx:latest"),
    Dest = new DockerImageName("public.ecr.aws/your-alias/your-repo:latest"),
    CopyImageIndex = true,
    ArchImageTags = new Dictionary<string, string> {
        { "amd64", "latest-amd64" },
        { "arm64", "latest-arm64" }
    }
});

Examples: examples/

The examples/ directory contains a runnable CDK app per scenario (local image asset, specific architecture, multi-arch index, retry config, S3 archive, and private-registry credentials). See examples/README.md.

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

yarn install --immutable
yarn build

Then synth or deploy any example:

npx cdk synth --app "npx ts-node examples/docker-image-asset.ts"
npx cdk deploy --app "npx ts-node examples/docker-image-asset.ts"

The private-registry-credentials example needs a Secret in AWS Secrets Manager with your DockerHub credentials (note: secrets incur a cost):

aws secretsmanager create-secret --name DockerHubCredentials --secret-string "username:access-token"
export DOCKERHUB_SECRET_ARN="<ARN>"

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

API

Tech Details & Contributions

The core of this project relies on containers/image (published as the Go module go.podman.io/image/v5) which is used by Skopeo. Please take a look at those projects before contributing.

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.