# Amazon ECR Construct Library
<!--BEGIN STABILITY BANNER-->---
---
<!--END STABILITY BANNER-->
This package contains constructs for working with Amazon Elastic Container Registry.
## Repositories
Define a repository by creating a new instance of `Repository`. A repository
holds multiple verions of a single container image.
```python
repository = ecr.Repository(self, "Repository")
```
## Image scanning
Amazon ECR image scanning helps in identifying software vulnerabilities in your container images. You can manually scan container images stored in Amazon ECR, or you can configure your repositories to scan images when you push them to a repository. To create a new repository to scan on push, simply enable `imageScanOnPush` in the properties
```python
repository = ecr.Repository(self, "Repo",
image_scan_on_push=True
)
```
To create an `onImageScanCompleted` event rule and trigger the event target
```python
# repository: ecr.Repository
# target: SomeTarget
repository.on_image_scan_completed("ImageScanComplete").add_target(target)
```
### Authorization Token
Besides the Amazon ECR APIs, ECR also allows the Docker CLI or a language-specific Docker library to push and pull
images from an ECR repository. However, the Docker CLI does not support native IAM authentication methods and
additional steps must be taken so that Amazon ECR can authenticate and authorize Docker push and pull requests.
More information can be found at at [Registry Authentication](https://docs.aws.amazon.com/AmazonECR/latest/userguide/Registries.html#registry_auth).
A Docker authorization token can be obtained using the `GetAuthorizationToken` ECR API. The following code snippets
grants an IAM user access to call this API.
```python
user = iam.User(self, "User")
ecr.AuthorizationToken.grant_read(user)
```
If you access images in the [Public ECR Gallery](https://gallery.ecr.aws/) as well, it is recommended you authenticate to the registry to benefit from
higher rate and bandwidth limits.
> See `Pricing` in https://aws.amazon.com/blogs/aws/amazon-ecr-public-a-new-public-container-registry/ and [Service quotas](https://docs.aws.amazon.com/AmazonECR/latest/public/public-service-quotas.html).
The following code snippet grants an IAM user access to retrieve an authorization token for the public gallery.
```python
user = iam.User(self, "User")
ecr.PublicGalleryAuthorizationToken.grant_read(user)
```
This user can then proceed to login to the registry using one of the [authentication methods](https://docs.aws.amazon.com/AmazonECR/latest/public/public-registries.html#public-registry-auth).
### Image tag immutability
You can set tag immutability on images in our repository using the `imageTagMutability` construct prop.
```python
ecr.Repository(self, "Repo", image_tag_mutability=ecr.TagMutability.IMMUTABLE)
```
### Encryption
By default, Amazon ECR uses server-side encryption with Amazon S3-managed encryption keys which encrypts your data at rest using an AES-256 encryption algorithm. For more control over the encryption for your Amazon ECR repositories, you can use server-side encryption with KMS keys stored in AWS Key Management Service (AWS KMS). Read more about this feature in the [ECR Developer Guide](https://docs.aws.amazon.com/AmazonECR/latest/userguide/encryption-at-rest.html).
When you use AWS KMS to encrypt your data, you can either use the default AWS managed key, which is managed by Amazon ECR, by specifying `RepositoryEncryption.KMS` in the `encryption` property. Or specify your own customer managed KMS key, by specifying the `encryptionKey` property.
When `encryptionKey` is set, the `encryption` property must be `KMS` or empty.
In the case `encryption` is set to `KMS` but no `encryptionKey` is set, an AWS managed KMS key is used.
```python
ecr.Repository(self, "Repo",
encryption=ecr.RepositoryEncryption.KMS
)
```
Otherwise, a customer-managed KMS key is used if `encryptionKey` was set and `encryption` was optionally set to `KMS`.
```python
import aws_cdk.aws_kms as kms
ecr.Repository(self, "Repo",
encryption_key=kms.Key(self, "Key")
)
```
## Automatically clean up repositories
You can set life cycle rules to automatically clean up old images from your
repository. The first life cycle rule that matches an image will be applied
against that image. For example, the following deletes images older than
30 days, while keeping all images tagged with prod (note that the order
is important here):
```python
# repository: ecr.Repository
repository.add_lifecycle_rule(tag_prefix_list=["prod"], max_image_count=9999)
repository.add_lifecycle_rule(max_image_age=Duration.days(30))
```
Raw data
{
"_id": null,
"home_page": "https://github.com/aws/aws-cdk",
"name": "aws-cdk.aws-ecr",
"maintainer": "",
"docs_url": null,
"requires_python": "~=3.7",
"maintainer_email": "",
"keywords": "",
"author": "Amazon Web Services",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/e4/7e/a79803397cc3ed7a31dab1ca27981fa2dd8536af176de989d8770d9e0c10/aws-cdk.aws-ecr-1.203.0.tar.gz",
"platform": null,
"description": "# Amazon ECR Construct Library\n\n<!--BEGIN STABILITY BANNER-->---\n\n\n\n\n\n\n---\n<!--END STABILITY BANNER-->\n\nThis package contains constructs for working with Amazon Elastic Container Registry.\n\n## Repositories\n\nDefine a repository by creating a new instance of `Repository`. A repository\nholds multiple verions of a single container image.\n\n```python\nrepository = ecr.Repository(self, \"Repository\")\n```\n\n## Image scanning\n\nAmazon ECR image scanning helps in identifying software vulnerabilities in your container images. You can manually scan container images stored in Amazon ECR, or you can configure your repositories to scan images when you push them to a repository. To create a new repository to scan on push, simply enable `imageScanOnPush` in the properties\n\n```python\nrepository = ecr.Repository(self, \"Repo\",\n image_scan_on_push=True\n)\n```\n\nTo create an `onImageScanCompleted` event rule and trigger the event target\n\n```python\n# repository: ecr.Repository\n# target: SomeTarget\n\n\nrepository.on_image_scan_completed(\"ImageScanComplete\").add_target(target)\n```\n\n### Authorization Token\n\nBesides the Amazon ECR APIs, ECR also allows the Docker CLI or a language-specific Docker library to push and pull\nimages from an ECR repository. However, the Docker CLI does not support native IAM authentication methods and\nadditional steps must be taken so that Amazon ECR can authenticate and authorize Docker push and pull requests.\nMore information can be found at at [Registry Authentication](https://docs.aws.amazon.com/AmazonECR/latest/userguide/Registries.html#registry_auth).\n\nA Docker authorization token can be obtained using the `GetAuthorizationToken` ECR API. The following code snippets\ngrants an IAM user access to call this API.\n\n```python\nuser = iam.User(self, \"User\")\necr.AuthorizationToken.grant_read(user)\n```\n\nIf you access images in the [Public ECR Gallery](https://gallery.ecr.aws/) as well, it is recommended you authenticate to the registry to benefit from\nhigher rate and bandwidth limits.\n\n> See `Pricing` in https://aws.amazon.com/blogs/aws/amazon-ecr-public-a-new-public-container-registry/ and [Service quotas](https://docs.aws.amazon.com/AmazonECR/latest/public/public-service-quotas.html).\n\nThe following code snippet grants an IAM user access to retrieve an authorization token for the public gallery.\n\n```python\nuser = iam.User(self, \"User\")\necr.PublicGalleryAuthorizationToken.grant_read(user)\n```\n\nThis user can then proceed to login to the registry using one of the [authentication methods](https://docs.aws.amazon.com/AmazonECR/latest/public/public-registries.html#public-registry-auth).\n\n### Image tag immutability\n\nYou can set tag immutability on images in our repository using the `imageTagMutability` construct prop.\n\n```python\necr.Repository(self, \"Repo\", image_tag_mutability=ecr.TagMutability.IMMUTABLE)\n```\n\n### Encryption\n\nBy default, Amazon ECR uses server-side encryption with Amazon S3-managed encryption keys which encrypts your data at rest using an AES-256 encryption algorithm. For more control over the encryption for your Amazon ECR repositories, you can use server-side encryption with KMS keys stored in AWS Key Management Service (AWS KMS). Read more about this feature in the [ECR Developer Guide](https://docs.aws.amazon.com/AmazonECR/latest/userguide/encryption-at-rest.html).\n\nWhen you use AWS KMS to encrypt your data, you can either use the default AWS managed key, which is managed by Amazon ECR, by specifying `RepositoryEncryption.KMS` in the `encryption` property. Or specify your own customer managed KMS key, by specifying the `encryptionKey` property.\n\nWhen `encryptionKey` is set, the `encryption` property must be `KMS` or empty.\n\nIn the case `encryption` is set to `KMS` but no `encryptionKey` is set, an AWS managed KMS key is used.\n\n```python\necr.Repository(self, \"Repo\",\n encryption=ecr.RepositoryEncryption.KMS\n)\n```\n\nOtherwise, a customer-managed KMS key is used if `encryptionKey` was set and `encryption` was optionally set to `KMS`.\n\n```python\nimport aws_cdk.aws_kms as kms\n\n\necr.Repository(self, \"Repo\",\n encryption_key=kms.Key(self, \"Key\")\n)\n```\n\n## Automatically clean up repositories\n\nYou can set life cycle rules to automatically clean up old images from your\nrepository. The first life cycle rule that matches an image will be applied\nagainst that image. For example, the following deletes images older than\n30 days, while keeping all images tagged with prod (note that the order\nis important here):\n\n```python\n# repository: ecr.Repository\n\nrepository.add_lifecycle_rule(tag_prefix_list=[\"prod\"], max_image_count=9999)\nrepository.add_lifecycle_rule(max_image_age=Duration.days(30))\n```\n\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "The CDK Construct Library for AWS::ECR",
"version": "1.203.0",
"project_urls": {
"Homepage": "https://github.com/aws/aws-cdk",
"Source": "https://github.com/aws/aws-cdk.git"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "971004aaa84ea4253b5c8361cff444593d0b7e0ceeb5b5a3c4b5fedd9f8f7653",
"md5": "d2ab8f348a9e83b49eb07f579fa38c79",
"sha256": "37e298aec93cfa6dea304fef58e2c2e11aef0473d1500a5e6b0c23a6ae29f56f"
},
"downloads": -1,
"filename": "aws_cdk.aws_ecr-1.203.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d2ab8f348a9e83b49eb07f579fa38c79",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "~=3.7",
"size": 140071,
"upload_time": "2023-05-31T22:54:31",
"upload_time_iso_8601": "2023-05-31T22:54:31.548025Z",
"url": "https://files.pythonhosted.org/packages/97/10/04aaa84ea4253b5c8361cff444593d0b7e0ceeb5b5a3c4b5fedd9f8f7653/aws_cdk.aws_ecr-1.203.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e47ea79803397cc3ed7a31dab1ca27981fa2dd8536af176de989d8770d9e0c10",
"md5": "e1281b43ec93f53322474b16ddfa1255",
"sha256": "4ad0bdbf379e778f3c3235edde7618d52ff6b5fb405e70deaa01a9fe640faed3"
},
"downloads": -1,
"filename": "aws-cdk.aws-ecr-1.203.0.tar.gz",
"has_sig": false,
"md5_digest": "e1281b43ec93f53322474b16ddfa1255",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=3.7",
"size": 141559,
"upload_time": "2023-05-31T23:02:04",
"upload_time_iso_8601": "2023-05-31T23:02:04.106169Z",
"url": "https://files.pythonhosted.org/packages/e4/7e/a79803397cc3ed7a31dab1ca27981fa2dd8536af176de989d8770d9e0c10/aws-cdk.aws-ecr-1.203.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-31 23:02:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aws",
"github_project": "aws-cdk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "aws-cdk.aws-ecr"
}
JSON
