cdk-ecr-deployment


Namecdk-ecr-deployment JSON
Version 4.0.3 PyPI version JSON
download
home_pagehttps://github.com/cdklabs/cdk-ecr-deployment
SummaryCDK construct to deploy docker image to Amazon ECR
upload_time2025-09-08 14:18:02
maintainerNone
docs_urlNone
authorAmazon Web Services<aws-cdk-dev@amazon.com>
requires_python~=3.9
licenseApache-2.0
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls. 
            # cdk-ecr-deployment

[![Release](https://github.com/cdklabs/cdk-ecr-deployment/actions/workflows/release.yml/badge.svg)](https://github.com/cdklabs/cdk-ecr-deployment/actions/workflows/release.yml)
[![npm version](https://img.shields.io/npm/v/cdk-ecr-deployment)](https://www.npmjs.com/package/cdk-ecr-deployment)
[![PyPI](https://img.shields.io/pypi/v/cdk-ecr-deployment)](https://pypi.org/project/cdk-ecr-deployment)
[![npm](https://img.shields.io/npm/dw/cdk-ecr-deployment?label=npm%20downloads)](https://www.npmjs.com/package/cdk-ecr-deployment)
[![PyPI - Downloads](https://img.shields.io/pypi/dw/cdk-ecr-deployment?label=pypi%20downloads)](https://pypi.org/project/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

```python
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=["*"]
))
```

## Sample: [test/example.ecr-deployment.ts](./test/example.ecr-deployment.ts)

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

```console
yarn --frozen-lockfile --check-files
yarn build
```

Then run the example like this:

```shell
# 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.**

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

```console
export DOCKERHUB_SECRET_ARN="<ARN>"
```

Finally run:

```shell
# 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](./API.md)

## Tech Details & Contribution

The core of this project relies on [containers/image](https://github.com/containers/image) which is used by [Skopeo](https://github.com/containers/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](https://github.com/containers/image/blob/master/types/types.go). You could take a look at [docker-archive](https://github.com/containers/image/blob/ccb87a8d0f45cf28846e307eb0ec2b9d38a458c2/docker/archive/transport.go) 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](https://github.com/aws/aws-lambda-go/issues/107). You need to go into the CloudWatch Log Group to find the real error.

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/cdklabs/cdk-ecr-deployment",
    "name": "cdk-ecr-deployment",
    "maintainer": null,
    "docs_url": null,
    "requires_python": "~=3.9",
    "maintainer_email": null,
    "keywords": null,
    "author": "Amazon Web Services<aws-cdk-dev@amazon.com>",
    "author_email": null,
    "download_url": "https://files.pythonhosted.org/packages/a9/b7/14917402b99511b9e13416aa9baa7d940b1ca6ceeb833d0be61f2262ac85/cdk_ecr_deployment-4.0.3.tar.gz",
    "platform": null,
    "description": "# cdk-ecr-deployment\n\n[![Release](https://github.com/cdklabs/cdk-ecr-deployment/actions/workflows/release.yml/badge.svg)](https://github.com/cdklabs/cdk-ecr-deployment/actions/workflows/release.yml)\n[![npm version](https://img.shields.io/npm/v/cdk-ecr-deployment)](https://www.npmjs.com/package/cdk-ecr-deployment)\n[![PyPI](https://img.shields.io/pypi/v/cdk-ecr-deployment)](https://pypi.org/project/cdk-ecr-deployment)\n[![npm](https://img.shields.io/npm/dw/cdk-ecr-deployment?label=npm%20downloads)](https://www.npmjs.com/package/cdk-ecr-deployment)\n[![PyPI - Downloads](https://img.shields.io/pypi/dw/cdk-ecr-deployment?label=pypi%20downloads)](https://pypi.org/project/cdk-ecr-deployment)\n\nCDK construct to synchronize single docker image between docker registries.\n\n> [!IMPORTANT]\n>\n> Please use the latest version of this package, which is `v4`.\n>\n> (Older versions are no longer supported).\n\n## Features\n\n* Copy image from ECR/external registry to (another) ECR/external registry\n* Copy an archive tarball image from s3 to ECR/external registry\n\n## Examples\n\n```python\nfrom aws_cdk.aws_ecr_assets import DockerImageAsset\n\n\nimage = DockerImageAsset(self, \"CDKDockerImage\",\n    directory=path.join(__dirname, \"docker\")\n)\n\n# Copy from cdk docker image asset to another ECR.\necrdeploy.ECRDeployment(self, \"DeployDockerImage1\",\n    src=ecrdeploy.DockerImageName(image.image_uri),\n    dest=ecrdeploy.DockerImageName(f\"{cdk.Aws.ACCOUNT_ID}.dkr.ecr.us-west-2.amazonaws.com/my-nginx:latest\")\n)\n\n# Copy from docker registry to ECR.\necrdeploy.ECRDeployment(self, \"DeployDockerImage2\",\n    src=ecrdeploy.DockerImageName(\"nginx:latest\"),\n    dest=ecrdeploy.DockerImageName(f\"{cdk.Aws.ACCOUNT_ID}.dkr.ecr.us-west-2.amazonaws.com/my-nginx2:latest\")\n)\n\n# Copy from private docker registry to ECR.\n# The format of secret in aws secrets manager must be either:\n# - plain text in format <username>:<password>\n# - json in format {\"username\":\"<username>\",\"password\":\"<password>\"}\necrdeploy.ECRDeployment(self, \"DeployDockerImage3\",\n    src=ecrdeploy.DockerImageName(\"javacs3/nginx:latest\", \"username:password\"),\n    # src: new ecrdeploy.DockerImageName('javacs3/nginx:latest', 'aws-secrets-manager-secret-name'),\n    # src: new ecrdeploy.DockerImageName('javacs3/nginx:latest', 'arn:aws:secretsmanager:us-west-2:000000000000:secret:id'),\n    dest=ecrdeploy.DockerImageName(f\"{cdk.Aws.ACCOUNT_ID}.dkr.ecr.us-west-2.amazonaws.com/my-nginx3:latest\")\n).add_to_principal_policy(iam.PolicyStatement(\n    effect=iam.Effect.ALLOW,\n    actions=[\"secretsmanager:GetSecretValue\"\n    ],\n    resources=[\"*\"]\n))\n```\n\n## Sample: [test/example.ecr-deployment.ts](./test/example.ecr-deployment.ts)\n\nAfter cloning the repository, install dependencies and run a full build:\n\n```console\nyarn --frozen-lockfile --check-files\nyarn build\n```\n\nThen run the example like this:\n\n```shell\n# Run the following command to try the sample.\nnpx cdk deploy -a \"npx ts-node -P tsconfig.dev.json --prefer-ts-exts test/example.ecr-deployment.ts\"\n```\n\nTo run the DockerHub example you will first need to setup a Secret in AWS Secrets Manager to provide DockerHub credentials.\nReplace `username:access-token` with your credentials.\n**Please note that Secrets will occur a cost.**\n\n```console\naws secretsmanager create-secret --name DockerHubCredentials --secret-string \"username:access-token\"\n```\n\nFrom the output, copy the ARN of your new secret and export it as env variable\n\n```console\nexport DOCKERHUB_SECRET_ARN=\"<ARN>\"\n```\n\nFinally run:\n\n```shell\n# Run the following command to try the sample.\nnpx cdk deploy -a \"npx ts-node -P tsconfig.dev.json --prefer-ts-exts test/dockerhub-example.ecr-deployment.ts\"\n```\n\nIf your Secret is encrypted, you might have to adjust the example to also grant decrypt permissions.\n\n## [API](./API.md)\n\n## Tech Details & Contribution\n\nThe core of this project relies on [containers/image](https://github.com/containers/image) which is used by [Skopeo](https://github.com/containers/skopeo).\nPlease take a look at those projects before contribution.\n\nTo support a new docker image source(like docker tarball in s3), you need to implement [image transport interface](https://github.com/containers/image/blob/master/types/types.go). You could take a look at [docker-archive](https://github.com/containers/image/blob/ccb87a8d0f45cf28846e307eb0ec2b9d38a458c2/docker/archive/transport.go) transport for a good start.\n\nAny 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](https://github.com/aws/aws-lambda-go/issues/107). You need to go into the CloudWatch Log Group to find the real error.\n",
    "bugtrack_url": null,
    "license": "Apache-2.0",
    "summary": "CDK construct to deploy docker image to Amazon ECR",
    "version": "4.0.3",
    "project_urls": {
        "Homepage": "https://github.com/cdklabs/cdk-ecr-deployment",
        "Source": "https://github.com/cdklabs/cdk-ecr-deployment"
    },
    "split_keywords": [],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "1da2a10d1a7e8eb20c6562341e0e8e031155626aa7169eef003ba7f720dafcea",
                "md5": "e76b06287f7050772bcbdf19773fa7e0",
                "sha256": "ab7b4b8dceaf90879e11df85b4a0923272155589c204cfeff9d9ec7a0fb2076e"
            },
            "downloads": -1,
            "filename": "cdk_ecr_deployment-4.0.3-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "e76b06287f7050772bcbdf19773fa7e0",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": "~=3.9",
            "size": 21340208,
            "upload_time": "2025-09-08T14:17:59",
            "upload_time_iso_8601": "2025-09-08T14:17:59.581130Z",
            "url": "https://files.pythonhosted.org/packages/1d/a2/a10d1a7e8eb20c6562341e0e8e031155626aa7169eef003ba7f720dafcea/cdk_ecr_deployment-4.0.3-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "a9b714917402b99511b9e13416aa9baa7d940b1ca6ceeb833d0be61f2262ac85",
                "md5": "a4f9477e6d6cf3daf9356b4edca9f203",
                "sha256": "62696cd5296c8546f1142aa532418259a3c2494648ecffb7a7e6e518f2c1787a"
            },
            "downloads": -1,
            "filename": "cdk_ecr_deployment-4.0.3.tar.gz",
            "has_sig": false,
            "md5_digest": "a4f9477e6d6cf3daf9356b4edca9f203",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": "~=3.9",
            "size": 21341390,
            "upload_time": "2025-09-08T14:18:02",
            "upload_time_iso_8601": "2025-09-08T14:18:02.203137Z",
            "url": "https://files.pythonhosted.org/packages/a9/b7/14917402b99511b9e13416aa9baa7d940b1ca6ceeb833d0be61f2262ac85/cdk_ecr_deployment-4.0.3.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-09-08 14:18:02",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "cdklabs",
    "github_project": "cdk-ecr-deployment",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "cdk-ecr-deployment"
}
Amazon Web Services<aws-cdk-dev@amazon.com>
Elapsed time: 4.07934s