cdk-ecr-deployment 4.2.0

CDK construct to deploy docker image to Amazon ECR

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 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

Examples

from aws_cdk.aws_ecr_assets import DockerImageAsset


image = DockerImageAsset(self, "CDKDockerImage",
    directory=path.join(__dirname, "docker")
)

# Copy from cdk docker image asset to another ECR.
ecrdeploy.ECRDeployment(self, "DeployDockerImage1",
    src=ecrdeploy.DockerImageName(image.image_uri),
    dest=ecrdeploy.DockerImageName(f"{cdk.Aws.ACCOUNT_ID}.dkr.ecr.us-west-2.amazonaws.com/my-nginx:latest")
)

# Copy from docker registry to ECR.
ecrdeploy.ECRDeployment(self, "DeployDockerImage2",
    src=ecrdeploy.DockerImageName("nginx:latest"),
    dest=ecrdeploy.DockerImageName(f"{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>"}
ecrdeploy.ECRDeployment(self, "DeployDockerImage3",
    src=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=ecrdeploy.DockerImageName(f"{cdk.Aws.ACCOUNT_ID}.dkr.ecr.us-west-2.amazonaws.com/my-nginx3:latest")
).add_to_principal_policy(iam.PolicyStatement(
    effect=iam.Effect.ALLOW,
    actions=["secretsmanager:GetSecretValue"
    ],
    resources=["*"]
))

# Copy multi-architecture image index (manifest) with all architectures.
ecrdeploy.ECRDeployment(self, "DeployDockerImage4",
    src=ecrdeploy.DockerImageName("public.ecr.aws/nginx/nginx:latest"),
    dest=ecrdeploy.DockerImageName(f"{cdk.Aws.ACCOUNT_ID}.dkr.ecr.us-west-2.amazonaws.com/my-nginx4:manifest"),
    copy_image_index=True,
    arch_image_tags={
        "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.
ecrdeploy.ECRDeployment(self, "DeployDockerImage5",
    src=ecrdeploy.DockerImageName(f"{cdk.Aws.ACCOUNT_ID}.dkr.ecr.us-west-2.amazonaws.com/my-nginx:latest"),
    dest=ecrdeploy.DockerImageName("public.ecr.aws/your-alias/your-repo:latest"),
    copy_image_index=True,
    arch_image_tags={
        "amd64": "latest-amd64",
        "arm64": "latest-arm64"
    }
)

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.