├── doc_source ├── glossary.md ├── registry-settings.md ├── image-push.md ├── delete-repository-policy.md ├── repository-delete.md ├── image-info.md ├── usage-reports.md ├── repository-edit.md ├── registry-permissions-delete.md ├── registry-permissions.md ├── image-scanning-troubleshooting.md ├── images.md ├── infrastructure-security.md ├── monitoring-usage.md ├── Registries.md ├── security.md ├── delete_image.md ├── image-tag-mutability.md ├── monitoring.md ├── repository-info.md ├── lpp_creation.md ├── lp_creation.md ├── ecr-compliance.md ├── monitoring-quotas-alarms.md ├── Repositories.md ├── ecr-supported-iam-actions-tagging.md ├── ECR_on_ECS.md ├── docker-pull-ecr-image.md ├── registry-settings-examples.md ├── data-protection.md ├── docker-push-multi-architecture-image.md ├── registry-settings-configure.md ├── docker-push-ecr-image.md ├── registry-permissions-create.md ├── getting-started-console.md ├── amazon_linux_container_image.md ├── image-manifest-formats.md ├── set-repository-policy.md ├── repository-policies.md ├── repository-create.md ├── replication.md ├── ecr-eventbridge.md ├── registry-permissions-examples.md ├── what-is-ecr.md ├── image-retag.md ├── ECR_on_EKS.md ├── ecr_managed_policies.md ├── push-oci-artifact.md ├── doc-history.md ├── common-errors.md ├── index.md ├── service-quotas.md ├── troubleshooting.md ├── common-errors-docker.md ├── using-service-linked-roles.md ├── security_iam_troubleshoot.md ├── get-set-up-for-amazon-ecr.md ├── LifecyclePolicies.md ├── repository-policy-examples.md ├── registry_auth.md ├── security_iam_id-based-policy-examples.md ├── ecr-using-tags.md └── image-scanning.md ├── .github └── PULL_REQUEST_TEMPLATE.md ├── CODE_OF_CONDUCT.md ├── LICENSE-SUMMARY ├── README.md ├── LICENSE-SAMPLECODE └── CONTRIBUTING.md /doc_source/glossary.md: -------------------------------------------------------------------------------- 1 | # AWS glossary 2 | 3 | For the latest AWS terminology, see the [AWS glossary](https://docs.aws.amazon.com/general/latest/gr/glos-chap.html) in the *AWS General Reference*\. -------------------------------------------------------------------------------- /.github/PULL_REQUEST_TEMPLATE.md: -------------------------------------------------------------------------------- 1 | *Issue #, if available:* 2 | 3 | *Description of changes:* 4 | 5 | 6 | By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice. 7 | -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | ## Code of Conduct 2 | This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct). 3 | For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact 4 | opensource-codeofconduct@amazon.com with any additional questions or comments. 5 | -------------------------------------------------------------------------------- /LICENSE-SUMMARY: -------------------------------------------------------------------------------- 1 | Copyright 2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. 2 | 3 | The documentation is made available under the Creative Commons Attribution-ShareAlike 4.0 International License. See the LICENSE file. 4 | 5 | The sample code within this documentation is made available under a modified MIT license. See the LICENSE-SAMPLECODE file. 6 | -------------------------------------------------------------------------------- /doc_source/registry-settings.md: -------------------------------------------------------------------------------- 1 | # Private registry settings 2 | 3 | Amazon ECR uses **registry settings** to configure features at the registry level\. The private registry settings are configured separately for each Region\. Currently, the only registry setting is the replication setting, which is used to configure cross\-Region and cross\-account replication of the images in your repositories\. For more information, see [Private image replication](replication.md)\. -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | ## Amazon ECR User Guide 2 | 3 | The open source version of the Amazon ECR user guide. You can submit feedback & requests for changes by submitting issues in this repo or by making proposed changes & submitting a pull request. 4 | 5 | ## License Summary 6 | 7 | The documentation is made available under the Creative Commons Attribution-ShareAlike 4.0 International License. See the LICENSE file. 8 | 9 | The sample code within this documentation is made available under a modified MIT license. See the LICENSE-SAMPLECODE file. 10 | -------------------------------------------------------------------------------- /doc_source/image-push.md: -------------------------------------------------------------------------------- 1 | # Pushing an image 2 | 3 | You can push your Docker images, manifest lists, and Open Container Initiative \(OCI\) images and compatible artifacts to your repository\. The following pages describe these in more detail\. 4 | 5 | **Note** 6 | Your images can be replicated to other repositories across Regions in your own registry and across accounts by specifying a replication configuration in your registry settings\. For more information, see [Private registry settings](registry-settings.md)\. 7 | 8 | **Topics** 9 | + [Pushing a Docker image](docker-push-ecr-image.md) 10 | + [Pushing a multi\-architecture image](docker-push-multi-architecture-image.md) 11 | + [Pushing a Helm chart](push-oci-artifact.md) -------------------------------------------------------------------------------- /doc_source/delete-repository-policy.md: -------------------------------------------------------------------------------- 1 | # Deleting a repository policy statement 2 | 3 | If you no longer want an existing repository policy statement to apply to a repository, you can delete it\. 4 | 5 | **To delete a repository policy statement** 6 | 7 | 1. Open the Amazon ECR console at [https://console\.aws\.amazon\.com/ecr/repositories](https://console.aws.amazon.com/ecr/repositories)\. 8 | 9 | 1. From the navigation bar, choose the Region that contains the repository to delete a policy statement from\. 10 | 11 | 1. In the navigation pane, choose **Repositories**\. 12 | 13 | 1. On the **Repositories** page, choose the repository to delete a policy statement from\. 14 | 15 | 1. In the navigation pane, choose **Permissions**, **Edit**\. 16 | 17 | 1. On the **Edit permissions** page, choose **Delete**\. -------------------------------------------------------------------------------- /doc_source/repository-delete.md: -------------------------------------------------------------------------------- 1 | # Deleting a repository 2 | 3 | If you're finished using a repository, you can delete it\. When you delete a repository in the AWS Management Console, all of the images contained in the repository are also deleted; this cannot be undone\. 4 | 5 | **To delete a repository** 6 | 7 | 1. Open the Amazon ECR console at [https://console\.aws\.amazon\.com/ecr/repositories](https://console.aws.amazon.com/ecr/repositories)\. 8 | 9 | 1. From the navigation bar, choose the Region that contains the repository to delete\. 10 | 11 | 1. In the navigation pane, choose **Repositories**\. 12 | 13 | 1. On the **Repositories** page, select the repository to delete and choose **Delete**\. 14 | 15 | 1. In the **Delete *repository\_name*** window, verify that the selected repositories should be deleted and choose **Delete**\. 16 | **Important** 17 | Any images in the selected repositories are also deleted\. -------------------------------------------------------------------------------- /LICENSE-SAMPLECODE: -------------------------------------------------------------------------------- 1 | Copyright 2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. 2 | 3 | Permission is hereby granted, free of charge, to any person obtaining a copy of this 4 | software and associated documentation files (the "Software"), to deal in the Software 5 | without restriction, including without limitation the rights to use, copy, modify, 6 | merge, publish, distribute, sublicense, and/or sell copies of the Software, and to 7 | permit persons to whom the Software is furnished to do so. 8 | 9 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, 10 | INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A 11 | PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT 12 | HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION 13 | OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 14 | SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 15 | -------------------------------------------------------------------------------- /doc_source/image-info.md: -------------------------------------------------------------------------------- 1 | # Viewing image details 2 | 3 | After you have pushed an image to your repository, you can view its information in the AWS Management Console\. The details included are as follows: 4 | + Image URI 5 | + Image tags 6 | + Artifact media type 7 | + Image manifest type 8 | + Scanning status 9 | + The size of the image in MB 10 | + When the image was pushed to the repository 11 | + The replication status 12 | 13 | **To view image details \(AWS Management Console\)** 14 | 15 | 1. Open the Amazon ECR console at [https://console\.aws\.amazon\.com/ecr/repositories](https://console.aws.amazon.com/ecr/repositories)\. 16 | 17 | 1. From the navigation bar, choose the Region that contains the repository containing your image\. 18 | 19 | 1. In the navigation pane, choose **Repositories**\. 20 | 21 | 1. On the **Repositories** page, choose the repository to view\. 22 | 23 | 1. On the **Repositories : *repository\_name*** page, choose the image to view the details of\. -------------------------------------------------------------------------------- /doc_source/usage-reports.md: -------------------------------------------------------------------------------- 1 | # Amazon ECR usage reports 2 | 3 | AWS provides a free reporting tool called Cost Explorer that enables you to analyze the cost and usage of your Amazon ECR resources\. 4 | 5 | Use Cost Explorer to view charts of your usage and costs\. You can view data from the previous 13 months and forecast how much you are likely to spend for the next three months\. You can use Cost Explorer to see patterns in how much you spend on AWS resources over time, identify areas that need further inquiry, and see trends that you can use to understand your costs\. You also can specify time ranges for the data and view time data by day or by month\. 6 | 7 | The metering data in your Cost and Usage Reports shows usage across all of your Amazon ECR repositories\. For more information, see [Tagging your resources for billing](ecr-using-tags.md#tag-resources-for-billing)\. 8 | 9 | For more information about creating an AWS Cost and Usage Report, see [AWS Cost and Usage Report](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/billing-reports-costusage.html) in the *AWS Billing and Cost Management User Guide*\. -------------------------------------------------------------------------------- /doc_source/repository-edit.md: -------------------------------------------------------------------------------- 1 | # Editing a repository 2 | 3 | Existing repositories can be edited to change its image tag mutability and image scanning settings\. 4 | 5 | **To edit a repository** 6 | 7 | 1. Open the Amazon ECR console at [https://console\.aws\.amazon\.com/ecr/repositories](https://console.aws.amazon.com/ecr/repositories)\. 8 | 9 | 1. From the navigation bar, choose the Region that contains the repository to edit\. 10 | 11 | 1. In the navigation pane, choose **Repositories**\. 12 | 13 | 1. On the **Repositories** page, select the repository to edit and choose **Edit**\. 14 | 15 | 1. For **Tag immutability**, choose the tag mutability setting for the repository\. Repositories configured with immutable tags prevent image tags from being overwritten\. For more information, see [Image tag mutability](image-tag-mutability.md)\. 16 | 17 | 1. For **Scan on push**, choose the image scanning setting for the repository\. Repositories configured to scan on push start an image scan whenever an image is pushed\. If you want image scans to start at a different time, you need to start them manually\.\. For more information, see [Image scanning](image-scanning.md)\. 18 | 19 | 1. Choose **Save** to update the repository settings\. -------------------------------------------------------------------------------- /doc_source/registry-permissions-delete.md: -------------------------------------------------------------------------------- 1 | # Deleting a private registry permission statement 2 | 3 | You can delete all permissions policy statements for your registry by using the following steps\. 4 | 5 | **To delete a permissions policy for a private registry \(AWS Management Console\)** 6 | 7 | 1. Open the Amazon ECR console at [https://console\.aws\.amazon\.com/ecr/](https://console.aws.amazon.com/ecr/)\. 8 | 9 | 1. From the navigation bar, choose the Region to configure your registry permissions policy in\. 10 | 11 | 1. In the navigation pane, choose **Registries**\. 12 | 13 | 1. On the **Registries** page, select your **Private** registry and choose **Permissions**\. 14 | 15 | 1. On the **Private registry permissions** page, choose **Delete**\. 16 | 17 | 1. On the **Delete registry policy** confirmation screen, choose **Delete policy**\. 18 | 19 | **To delete a permissions policy for a private registry \(AWS CLI\)** 20 | 21 | 1. Delete the registry policy\. 22 | 23 | ``` 24 | aws ecr delete-registry-policy \ 25 | --region us-west-2 26 | ``` 27 | 28 | 1. Retrieve the policy for your registry to confirm\. 29 | 30 | ``` 31 | aws ecr get-registry-policy \ 32 | --region us-west-2 33 | ``` -------------------------------------------------------------------------------- /doc_source/registry-permissions.md: -------------------------------------------------------------------------------- 1 | # Private registry permissions 2 | 3 | Amazon ECR uses a **registry policy** to grant permissions to an AWS principal, allowing the replication of the repositories from a source registry to your registry\. By default, you have permission to configure cross\-Region replication within your own registry\. You only need to configure the registry policy if you're granting another account permission to replicate contents to your registry\. 4 | 5 | A registry policy must grant permission for the `ecr:ReplicateImage` API action\. This API is an internal Amazon ECR API that can replicate images between Regions or accounts\. You can also grant permission for the `ecr:CreateRepository` permission, which allows Amazon ECR to create repositories in your registry if they don't exist already\. If the `ecr:CreateRepository` permission isn't provided, a repository with the same name as the source repository must be created manually in your registry\. If neither is done, replication fails\. Any failed CreateRepository or ReplicateImage API actions show up in CloudTrail\. 6 | 7 | **Topics** 8 | + [Setting a private registry permission statement](registry-permissions-create.md) 9 | + [Deleting a private registry permission statement](registry-permissions-delete.md) 10 | + [Private registry policy examples](registry-permissions-examples.md) -------------------------------------------------------------------------------- /doc_source/image-scanning-troubleshooting.md: -------------------------------------------------------------------------------- 1 | # Troubleshooting image scanning issues 2 | 3 | The following are common image scan failures\. You can view errors like this in the Amazon ECR console by displaying the image details or through the API or AWS CLI by using the `DescribeImageScanFindings` API\. 4 | 5 | UnsupportedImageError 6 | You may get an `UnsupportedImageError` error when attempting to scan an image that was built using an operating system that Amazon ECR doesn't support image scanning for\. Amazon ECR supports package vulnerability scanning for major versions of Amazon Linux, Amazon Linux 2, Debian, Ubuntu, CentOS, Oracle Linux, Alpine, and RHEL Linux distributions\. Once a distribution loses support from its vendor, Amazon ECR may no longer support scanning it for vulnerabilities\. Amazon ECR does not support scanning images built from the [Docker scratch](https://hub.docker.com/_/scratch) image\. 7 | 8 | An `UNDEFINED` severity level is returned 9 | You may receive a scan finding that has a severity level of `UNDEFINED`\. The following are the common causes for this: 10 | + The vulnerability was not assigned a priority by the CVE source\. 11 | + The vulnerability was assigned a priority that Amazon ECR did not recognize\. 12 | To determine the severity and description of a vulnerability, you can view the CVE directly from the source\. -------------------------------------------------------------------------------- /doc_source/images.md: -------------------------------------------------------------------------------- 1 | # Private images 2 | 3 | Amazon Elastic Container Registry \(Amazon ECR\) stores Docker images, Open Container Initiative \(OCI\) images, and OCI compatible artifacts in repositories\. You can use the Docker CLI or your preferred client to push and pull images to and from your repositories\. 4 | 5 | **Important** 6 | Amazon ECR requires that users have permission to make calls to the `ecr:GetAuthorizationToken` API through an IAM policy before they can authenticate to a registry and push or pull any images from any Amazon ECR repository\. Amazon ECR provides several managed IAM policies to control user access at varying levels; for more information, see [Amazon Elastic Container Registry Identity\-Based Policy Examples](security_iam_id-based-policy-examples.md)\. 7 | 8 | **Topics** 9 | + [Pushing an image](image-push.md) 10 | + [Viewing image details](image-info.md) 11 | + [Pulling an image](docker-pull-ecr-image.md) 12 | + [Deleting an image](delete_image.md) 13 | + [Retagging an image](image-retag.md) 14 | + [Private image replication](replication.md) 15 | + [Lifecycle policies](LifecyclePolicies.md) 16 | + [Image tag mutability](image-tag-mutability.md) 17 | + [Image scanning](image-scanning.md) 18 | + [Container image manifest formats](image-manifest-formats.md) 19 | + [Using Amazon ECR images with Amazon ECS](ECR_on_ECS.md) 20 | + [Using Amazon ECR Images with Amazon EKS](ECR_on_EKS.md) 21 | + [Amazon Linux container image](amazon_linux_container_image.md) -------------------------------------------------------------------------------- /doc_source/infrastructure-security.md: -------------------------------------------------------------------------------- 1 | # Infrastructure Security in Amazon Elastic Container Registry 2 | 3 | As a managed service, Amazon Elastic Container Registry is protected by the AWS global network security procedures that are described in the [Amazon Web Services: Overview of Security Processes](https://d0.awsstatic.com/whitepapers/Security/AWS_Security_Whitepaper.pdf) whitepaper\. 4 | 5 | You use AWS published API calls to access Amazon ECR through the network\. Clients must support Transport Layer Security \(TLS\) 1\.0 or later\. We recommend TLS 1\.2 or later\. Clients must also support cipher suites with perfect forward secrecy \(PFS\) such as Ephemeral Diffie\-Hellman \(DHE\) or Elliptic Curve Ephemeral Diffie\-Hellman \(ECDHE\)\. Most modern systems such as Java 7 and later support these modes\. 6 | 7 | Additionally, requests must be signed by using an access key ID and a secret access key that is associated with an IAM principal\. Or you can use the [AWS Security Token Service](https://docs.aws.amazon.com/STS/latest/APIReference/Welcome.html) \(AWS STS\) to generate temporary security credentials to sign requests\. 8 | 9 | You can call these API operations from any network location, but Amazon ECR does support resource\-based access policies, which can include restrictions based on the source IP address\. You can also use Amazon ECR policies to control access from specific Amazon Virtual Private Cloud \(Amazon VPC\) endpoints or specific VPCs\. Effectively, this isolates network access to a given Amazon ECR resource from only the specific VPC within the AWS network\. For more information, see [Amazon ECR interface VPC endpoints \(AWS PrivateLink\)](vpc-endpoints.md)\. -------------------------------------------------------------------------------- /doc_source/monitoring-usage.md: -------------------------------------------------------------------------------- 1 | # Amazon ECR usage metrics 2 | 3 | You can use CloudWatch usage metrics to provide visibility into your account's usage of resources\. Use these metrics to visualize your current service usage on CloudWatch graphs and dashboards\. 4 | 5 | Amazon ECR usage metrics correspond to AWS service quotas\. You can configure alarms that alert you when your usage approaches a service quota\. For more information about Amazon ECR service quotas, see [Amazon ECR service quotas](service-quotas.md)\. 6 | 7 | Amazon ECR publishes the following metrics in the `AWS/Usage` namespace\. 8 | 9 | 10 | | Metric | Description | 11 | | --- | --- | 12 | | `CallCount` | The number of API action calls from your account\. The resources are defined by the dimensions associated with the metric\. The most useful statistic for this metric is `SUM`, which represents the sum of the values from all contributors during the period defined\. | 13 | 14 | The following dimensions are used to refine the usage metrics that are published by Amazon ECR\. 15 | 16 | 17 | | Dimension | Description | 18 | | --- | --- | 19 | | `Service` | The name of the AWS service containing the resource\. For Amazon ECR usage metrics, the value for this dimension is `ECR`\. | 20 | | `Type` | The type of entity that is being reported\. Currently, the only valid value for Amazon ECR usage metrics is `API`\. | 21 | | `Resource` | The type of resource that is running\. Currently, Amazon ECR returns information on your API usage for the following API actions\. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonECR/latest/userguide/monitoring-usage.html) | 22 | | Class | The class of resource being tracked\. Currently, Amazon ECR does not use the class dimension\. | -------------------------------------------------------------------------------- /doc_source/Registries.md: -------------------------------------------------------------------------------- 1 | # Amazon ECR private registries 2 | 3 | Amazon ECR private registries host your container images in a highly available and scalable architecture\. You can use your private registry to manage private image repositories consisting of Docker and Open Container Initiative \(OCI\) images and artifacts\. Each AWS account is provided with a default private Amazon ECR registry\. For more information about Amazon ECR public registries, see [Public registries](https://docs.aws.amazon.com/AmazonECR/latest/public/public-registries.html) in the *Amazon Elastic Container Registry Public User Guide*\. 4 | 5 | ## Private registry concepts 6 | + The URL for your default private registry is \. 7 | + By default, your account has read and write access to the repositories in your private registry\. However, IAM users require permissions to make calls to the Amazon ECR APIs and to push or pull images to and from your private repositories\. Amazon ECR provides several managed policies to control user access at varying levels\. For more information, see [Amazon Elastic Container Registry Identity\-Based Policy Examples](security_iam_id-based-policy-examples.md)\. 8 | + You must authenticate your Docker client to your private registry so that you can use the docker push and docker pull commands to push and pull images to and from the repositories in that registry\. For more information, see [Private registry authentication](registry_auth.md)\. 9 | + Private repositories can be controlled with both IAM user access policies and repository policies\. For more information about repository policies, see [Repository policies](repository-policies.md)\. 10 | + The repositories in your private registry can be replicated across Regions in your own private registry and across separate accounts by configuring replication for your private registry\. For more information, see [Private image replication](replication.md)\. -------------------------------------------------------------------------------- /doc_source/security.md: -------------------------------------------------------------------------------- 1 | # Security in Amazon Elastic Container Registry 2 | 3 | Cloud security at AWS is the highest priority\. As an AWS customer, you benefit from a data center and network architecture that is built to meet the requirements of the most security\-sensitive organizations\. 4 | 5 | Security is a shared responsibility between AWS and you\. The [shared responsibility model](http://aws.amazon.com/compliance/shared-responsibility-model/) describes this as security *of* the cloud and security *in* the cloud: 6 | + **Security of the cloud** – AWS is responsible for protecting the infrastructure that runs AWS services in the AWS Cloud\. AWS also provides you with services that you can use securely\. Third\-party auditors regularly test and verify the effectiveness of our security as part of the [AWS compliance programs](http://aws.amazon.com/compliance/programs/)\. To learn about the compliance programs that apply to Amazon ECR, see [AWS Services in Scope by Compliance Program](http://aws.amazon.com/compliance/services-in-scope/)\. 7 | + **Security in the cloud** – Your responsibility is determined by the AWS service that you use\. You are also responsible for other factors including the sensitivity of your data, your company’s requirements, and applicable laws and regulations\. 8 | 9 | This documentation helps you understand how to apply the shared responsibility model when using Amazon ECR\. The following topics show you how to configure Amazon ECR to meet your security and compliance objectives\. You also learn how to use other AWS services that help you to monitor and secure your Amazon ECR resources\. 10 | 11 | **Topics** 12 | + [Identity and Access Management for Amazon Elastic Container Registry](security-iam.md) 13 | + [Data protection in Amazon ECR](data-protection.md) 14 | + [Compliance validation for Amazon Elastic Container Registry](ecr-compliance.md) 15 | + [Infrastructure Security in Amazon Elastic Container Registry](infrastructure-security.md) -------------------------------------------------------------------------------- /doc_source/delete_image.md: -------------------------------------------------------------------------------- 1 | # Deleting an image 2 | 3 | If you're finished using an image, you can delete it from your repository\. You can delete an image using the AWS Management Console or the AWS CLI\. 4 | 5 | **Note** 6 | If you're finished with a repository, you can delete the entire repository and all of the images within it\. For more information, see [Deleting a repository](repository-delete.md)\. 7 | 8 | **To delete an image with the AWS Management Console** 9 | 10 | 1. Open the Amazon ECR console at [https://console\.aws\.amazon\.com/ecr/repositories](https://console.aws.amazon.com/ecr/repositories)\. 11 | 12 | 1. From the navigation bar, choose the Region that contains the image to delete\. 13 | 14 | 1. In the navigation pane, choose **Repositories**\. 15 | 16 | 1. On the **Repositories** page, choose the repository that contains the image to delete\. 17 | 18 | 1. On the **Repositories: *repository\_name*** page, select the box to the left of the image to delete and choose **Delete**\. 19 | 20 | 1. In the **Delete image\(s\)** dialog box, verify that the selected images should be deleted and choose **Delete**\. 21 | 22 | **To delete an image with the AWS CLI** 23 | 24 | 1. List the images in your repository so that you can identify them by image tag or digest\. 25 | 26 | ``` 27 | aws ecr list-images --repository-name my-repo 28 | ``` 29 | 30 | 1. \(Optional\) Delete any unwanted tags for the image by specifying the tag of the image you want to delete\. 31 | **Note** 32 | When you delete the last tag for an image, the image is deleted\. 33 | 34 | ``` 35 | aws ecr batch-delete-image --repository-name my-repo --image-ids imageTag=latest 36 | ``` 37 | 38 | 1. Delete the image by specifying the digest of the image to delete\. 39 | **Note** 40 | When you delete an image by referencing its digest, the image and all of its tags are deleted\. 41 | 42 | ``` 43 | aws ecr batch-delete-image --repository-name my-repo --image-ids imageDigest=sha256:4f70ef7a4d29e8c0c302b13e25962d8f7a0bd304c7c2c1a9d6fa3e9de6bf552d 44 | ``` -------------------------------------------------------------------------------- /doc_source/image-tag-mutability.md: -------------------------------------------------------------------------------- 1 | # Image tag mutability 2 | 3 | You can configure a repository to be immutable to prevent image tags from being overwritten\. After the repository is configured for immutable tags, an `ImageTagAlreadyExistsException` error is returned if you attempt to push an image with a tag that is already in the repository\. 4 | 5 | You can use the AWS Management Console and AWS CLI tools to set image tag mutability for either a new repository during creation or for an existing repository at any time\. For console steps, see [Creating a repository](repository-create.md) and [Editing a repository](repository-edit.md)\. 6 | 7 | **To create a repository with immutable tags configured** 8 | 9 | Use one of the following commands to create a new image repository with immutable tags configured\. 10 | + [create\-repository](https://docs.aws.amazon.com/cli/latest/reference/ecr/create-repository.html) \(AWS CLI\) 11 | 12 | ``` 13 | aws ecr create-repository --repository-name name --image-tag-mutability IMMUTABLE --region us-east-2 14 | ``` 15 | + [New\-ECRRepository](https://docs.aws.amazon.com/powershell/latest/reference/items/New-ECRRepository.html) \(AWS Tools for Windows PowerShell\) 16 | 17 | ``` 18 | New-ECRRepository -RepositoryName name -ImageTagMutability IMMUTABLE -Region us-east-2 -Force 19 | ``` 20 | 21 | **To update the image tag mutability settings for an existing repository** 22 | 23 | Use one of the following commands to update the image tag mutability settings for an existing repository\. 24 | + [put\-image\-tag\-mutability](https://docs.aws.amazon.com/cli/latest/reference/ecr/put-image-tag-mutability.html) \(AWS CLI\) 25 | 26 | ``` 27 | aws ecr put-image-tag-mutability --repository-name name --image-tag-mutability IMMUTABLE --region us-east-2 28 | ``` 29 | + [Write\-ECRImageTagMutability](https://docs.aws.amazon.com/powershell/latest/reference/items/Write-ECRImageTagMutability.html) \(AWS Tools for Windows PowerShell\) 30 | 31 | ``` 32 | Write-ECRImageTagMutability -RepositoryName name -ImageTagMutability IMMUTABLE -Region us-east-2 -Force 33 | ``` -------------------------------------------------------------------------------- /doc_source/monitoring.md: -------------------------------------------------------------------------------- 1 | # Amazon ECR monitoring 2 | 3 | You can monitor your Amazon ECR API usage with Amazon CloudWatch, which collects and processes raw data from Amazon ECR into readable, near real\-time metrics\. These statistics are recorded for a period of two weeks, so that you can access historical information and gain perspective on your API usage\. Amazon ECR metric data is automatically sent to CloudWatch in one\-minute periods\. For more information about CloudWatch, see the [Amazon CloudWatch User Guide](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/)\. 4 | 5 | Amazon ECR provides metrics based on your API usage for authorization, image push, and image pull actions\. 6 | 7 | Monitoring is an important part of maintaining the reliability, availability, and performance of Amazon ECR and your AWS solutions\. We recommend that you collect monitoring data from the resources that make up your AWS solution so that you can more easily debug a multi\-point failure if one occurs\. Before you start monitoring Amazon ECR, however, you should create a monitoring plan that includes answers to the following questions: 8 | + What are your monitoring goals? 9 | + What resources will you monitor? 10 | + How often will you monitor these resources? 11 | + What monitoring tools will you use? 12 | + Who will perform the monitoring tasks? 13 | + Who should be notified when something goes wrong? 14 | 15 | The next step is to establish a baseline for normal Amazon ECR performance in your environment by measuring performance at various times and under different load conditions\. As you monitor Amazon ECR, store historical monitoring data so that you can compare it with new performance data, identify normal performance patterns and performance anomalies, and devise methods to address issues\. 16 | 17 | **Topics** 18 | + [Visualizing your service quotas and setting alarms](monitoring-quotas-alarms.md) 19 | + [Amazon ECR usage metrics](monitoring-usage.md) 20 | + [Amazon ECR usage reports](usage-reports.md) 21 | + [Amazon ECR events and EventBridge](ecr-eventbridge.md) 22 | + [Logging Amazon ECR actions with AWS CloudTrail](logging-using-cloudtrail.md) -------------------------------------------------------------------------------- /doc_source/repository-info.md: -------------------------------------------------------------------------------- 1 | # Viewing repository information 2 | 3 | After you created a repository, you can view its information in the AWS Management Console: 4 | + Which images are stored in a repository 5 | + Whether an image is tagged 6 | + The tags for the image 7 | + The SHA digest for the images 8 | + The size of the images in MiB 9 | + When the image was pushed to the repository 10 | 11 | **Note** 12 | Starting with Docker version 1\.9, the Docker client compresses image layers before pushing them to a V2 Docker registry\. The output of the docker images command shows the uncompressed image size\. Therefore, keep in mind that Docker might return a larger image than the image shown in the AWS Management Console\. 13 | 14 | **To view repository information \(AWS Management Console\)** 15 | 16 | 1. Open the Amazon ECR console at [https://console\.aws\.amazon\.com/ecr/repositories](https://console.aws.amazon.com/ecr/repositories)\. 17 | 18 | 1. From the navigation bar, choose the Region that contains the repository to view\. 19 | 20 | 1. In the navigation pane, choose **Repositories**\. 21 | 22 | 1. On the **Repositories** page, choose the repository to view\. 23 | 24 | 1. On the **Repositories : *repository\_name*** page, use the navigation bar to view information about an image\. 25 | + Choose **Images** to view information about the images in the repository\. To view more information about the image, select the image\. For more information, see [Viewing image details](image-info.md)\. 26 | 27 | If there are untagged images that you want to delete, you can select the box to the left of the repositories to delete and choose **Delete**\. For more information, see [Deleting an image](delete_image.md)\. 28 | + Choose **Permissions** to view the repository policies that are applied to the repository\. For more information, see [Repository policies](repository-policies.md)\. 29 | + Choose **Lifecycle Policy** to view the lifecycle policy rules that are applied to the repository\. The lifecycle events history is also viewed here\. For more information, see [Lifecycle policies](LifecyclePolicies.md)\. 30 | + Choose **Tags** to view the metadata tags that are applied to the repository\. -------------------------------------------------------------------------------- /doc_source/lpp_creation.md: -------------------------------------------------------------------------------- 1 | # Creating a lifecycle policy preview 2 | 3 | A lifecycle policy preview allows you to see the impact of a lifecycle policy on an image repository before you execute it\. The following procedure shows you how to create a lifecycle policy preview\. 4 | 5 | **To create a lifecycle policy preview using the console** 6 | 7 | 1. Open the Amazon ECR console at [https://console\.aws\.amazon\.com/ecr/repositories](https://console.aws.amazon.com/ecr/repositories)\. 8 | 9 | 1. From the navigation bar, choose the Region that contains the repository on which to perform a lifecycle policy preview\. 10 | 11 | 1. In the navigation pane, choose **Repositories** and select a repository\. 12 | 13 | 1. On the **Repositories: *repository\_name*** page, in the navigation pane choose **Lifecycle Policy**\. 14 | 15 | 1. On the **Repositories: *repository\_name*: Lifecycle policy** page, choose **Edit test rules**, **Create rule**\. 16 | 17 | 1. Enter the following details for your lifecycle policy rule: 18 | 19 | 1. For **Rule priority**, type a number for the rule priority\. 20 | 21 | 1. For **Rule description**, type a description for the lifecycle policy rule\. 22 | 23 | 1. For **Image status**, choose **Tagged**, **Untagged**, or **Any**\. 24 | 25 | 1. If you specified `Tagged` for **Image status**, then for **Tag prefixes**, you can optionally specify a list of image tags on which to take action with your lifecycle policy\. If you specified `Untagged`, this field must be empty\. 26 | 27 | 1. For **Match criteria**, choose values for **Since image pushed** or **Image count more than** \(if applicable\)\. 28 | 29 | 1. Choose **Save**\. 30 | 31 | 1. Create additional lifecycle policy rules by repeating steps 5–7\. 32 | 33 | 1. To run the lifecycle policy preview, choose **Save and run test**\. 34 | 35 | 1. Under **Image matches for test lifecycle rules**, review the impact of your lifecycle policy preview\. 36 | 37 | 1. If you are satisfied with the preview results, choose **Apply as lifecycle policy** to create a lifecycle policy with the specified rules\. 38 | 39 | **Note** 40 | You should expect that after creating a lifecycle policy, the affected images are expired within 24 hours\. -------------------------------------------------------------------------------- /doc_source/lp_creation.md: -------------------------------------------------------------------------------- 1 | # Creating a lifecycle policy 2 | 3 | A lifecycle policy allows you to create a set of rules that expire unused repository images\. The following procedure shows you how to create a lifecycle policy\. You should expect that after creating a lifecycle policy, the affected images are expired within 24 hours\. 4 | 5 | ## To create a lifecycle policy \(AWS CLI\) 6 | 7 | **To create a lifecycle policy using the AWS CLI** 8 | 9 | 1. Obtain the ID of the repository for which to create the lifecycle policy: 10 | 11 | ``` 12 | aws ecr describe-repositories 13 | ``` 14 | 15 | 1. Create a lifecycle policy: 16 | 17 | ``` 18 | aws ecr put-lifecycle-policy [--registry-id ] --repository-name --lifecycle-policy-text 19 | ``` 20 | 21 | ## To create a lifecycle policy \(AWS Management Console\) 22 | 23 | **To create a lifecycle policy using the console** 24 | 25 | 1. Open the Amazon ECR console at [https://console\.aws\.amazon\.com/ecr/repositories](https://console.aws.amazon.com/ecr/repositories)\. 26 | 27 | 1. From the navigation bar, choose the Region that contains the repository for which to create a lifecycle policy\. 28 | 29 | 1. In the navigation pane, choose **Repositories** and select a repository\. 30 | 31 | 1. On the **Repositories: *repository\_name*** page, in the navigation pane choose **Lifecycle Policy**\. 32 | 33 | 1. On the **Repositories: *repository\_name*: Lifecycle policy** page, choose **Create rule**\. 34 | 35 | 1. Enter the following details for your lifecycle policy rule: 36 | 37 | 1. For **Rule priority**, type a number for the rule priority\. 38 | 39 | 1. For **Rule description**, type a description for the lifecycle policy rule\. 40 | 41 | 1. For **Image status**, choose **Tagged**, **Untagged**, or **Any**\. 42 | 43 | 1. If you specified `Tagged` for **Image status**, then for **Tag prefixes**, you can optionally specify a list of image tags on which to take action with your lifecycle policy\. If you specified `Untagged`, this field must be empty\. 44 | 45 | 1. For **Match criteria**, choose values for **Since image pushed** or **Image count more than** \(if applicable\)\. 46 | 47 | 1. Choose **Save**\. -------------------------------------------------------------------------------- /doc_source/ecr-compliance.md: -------------------------------------------------------------------------------- 1 | # Compliance validation for Amazon Elastic Container Registry 2 | 3 | Third\-party auditors assess the security and compliance of Amazon Elastic Container Registry as part of multiple AWS compliance programs\. These include SOC, PCI, HIPAA, and others\. 4 | 5 | For a list of AWS services in scope of specific compliance programs, see [AWS Services in Scope by Compliance Program](http://aws.amazon.com/compliance/services-in-scope/)\. For general information, see [AWS Compliance Programs](http://aws.amazon.com/compliance/programs/)\. 6 | 7 | You can download third\-party audit reports using AWS Artifact\. For more information, see [Downloading Reports in AWS Artifact](https://docs.aws.amazon.com/artifact/latest/ug/downloading-documents.html)\. 8 | 9 | Your compliance responsibility when using Amazon ECR is determined by the sensitivity of your data, your company's compliance objectives, and applicable laws and regulations\. AWS provides the following resources to help with compliance: 10 | + [Security and Compliance Quick Start Guides](http://aws.amazon.com/quickstart/?awsf.quickstart-homepage-filter=categories%23security-identity-compliance) – These deployment guides discuss architectural considerations and provide steps for deploying security\- and compliance\-focused baseline environments on AWS\. 11 | + [Architecting for HIPAA Security and Compliance Whitepaper ](https://d0.awsstatic.com/whitepapers/compliance/AWS_HIPAA_Compliance_Whitepaper.pdf) – This whitepaper describes how companies can use AWS to create HIPAA\-compliant applications\. 12 | + [AWS Compliance Resources](http://aws.amazon.com/compliance/resources/) – This collection of workbooks and guides might apply to your industry and location\. 13 | + [Evaluating Resources with Rules](https://docs.aws.amazon.com/config/latest/developerguide/evaluate-config.html) in the *AWS Config Developer Guide* – The AWS Config service assesses how well your resource configurations comply with internal practices, industry guidelines, and regulations\. 14 | + [AWS Security Hub](https://docs.aws.amazon.com/securityhub/latest/userguide/what-is-securityhub.html) – This AWS service provides a comprehensive view of your security state within AWS that helps you check your compliance with security industry standards and best practices\. -------------------------------------------------------------------------------- /doc_source/monitoring-quotas-alarms.md: -------------------------------------------------------------------------------- 1 | # Visualizing your service quotas and setting alarms 2 | 3 | You can use the CloudWatch console to visualize your service quotas and see how your current usage compares to service quotas\. You can also set alarms so that you will be notified when you approach a quota\. 4 | 5 | **To visualize a service quota and optionally set an alarm** 6 | 7 | 1. Open the CloudWatch console at [https://console\.aws\.amazon\.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)\. 8 | 9 | 1. In the navigation pane, choose **Metrics**\. 10 | 11 | 1. On the **All metrics** tab, choose **Usage**, then choose **By AWS Resource**\. 12 | 13 | The list of service quota usage metrics appears\. 14 | 15 | 1. Select the check box next to one of the metrics\. 16 | 17 | The graph displays your current usage of that AWS resource\. 18 | 19 | 1. To add your service quota to the graph, do the following: 20 | 21 | 1. Choose the **Graphed metrics** tab\. 22 | 23 | 1. Choose **Math expression**, **Start with an empty expression**\. Then in the new row, under **Details**, enter **SERVICE\_QUOTA\(m1\)**\. 24 | 25 | A new line is added to the graph, displaying the service quota for the resource represented in the metric\. 26 | 27 | 1. To see your current usage as a percentage of the quota, add a new expression or change the current **SERVICE\_QUOTA** expression\. For the new expression, use **m1/60/SERVICE\_QUOTA\(m1\)\*100**\. 28 | 29 | 1. \(Optional\) To set an alarm that notifies you if you approach the service quota, do the following: 30 | 31 | 1. On the **m1/60/SERVICE\_QUOTA\(m1\)\*100** row, under **Actions**, choose the alarm icon\. It looks like a bell\. 32 | 33 | The alarm creation page appears\. 34 | 35 | 1. Under **Conditions**, ensure that **Threshold type** is **Static** and **Whenever Expression1 is** is set to **Greater**\. Under **than**, enter **80**\. This creates an alarm that goes into ALARM state when your usage exceeds 80 percent of the quota\. 36 | 37 | 1. Choose **Next**\. 38 | 39 | 1. On the next page, select an Amazon SNS topic or create a new one\. This topic is notified when the alarm goes to ALARM state\. Then choose **Next**\. 40 | 41 | 1. On the next page, enter a name and description for the alarm, and then choose **Next**\. 42 | 43 | 1. Choose **Create alarm**\. -------------------------------------------------------------------------------- /doc_source/Repositories.md: -------------------------------------------------------------------------------- 1 | # Amazon ECR private repositories 2 | 3 | Amazon Elastic Container Registry \(Amazon ECR\) provides API operations to create, monitor, and delete image repositories and set permissions that control who can access them\. You can perform the same actions in the **Repositories** section of the Amazon ECR console\. Amazon ECR also integrates with the Docker CLI, so that you push and pull images from your development environments to your repositories\. 4 | 5 | **Topics** 6 | + [Repository concepts](#repository-concepts) 7 | + [Creating a repository](repository-create.md) 8 | + [Viewing repository information](repository-info.md) 9 | + [Editing a repository](repository-edit.md) 10 | + [Deleting a repository](repository-delete.md) 11 | + [Repository policies](repository-policies.md) 12 | + [Tagging an Amazon ECR repository](ecr-using-tags.md) 13 | 14 | ## Repository concepts 15 | + By default, your account has read and write access to the repositories in your default registry \(`aws_account_id.dkr.ecr.region.amazonaws.com`\)\. However, IAM users require permissions to make calls to the Amazon ECR APIs and to push or pull images to and from your repositories\. Amazon ECR provides several managed policies to control user access at varying levels\. For more information, see [Amazon Elastic Container Registry Identity\-Based Policy Examples](security_iam_id-based-policy-examples.md)\. 16 | + Repositories can be controlled with both IAM user access policies and individual repository policies\. For more information, see [Repository policies](repository-policies.md)\. 17 | + Repository names can support namespaces, which you can use to group similar repositories\. For example, if there are several teams using the same registry, Team A can use the `team-a` namespace, and Team B can use the `team-b` namespace\. By doing this, each team has their own image called `web-app` with each image prefaced with the team namespace\. This configuration allows these images on each team to be used simultaneously without interference\. Team A's image is `team-a/web-app`, and Team B's image is `team-b/web-app`\. 18 | + Your images can be replicated to other repositories across Regions in your own registry and across accounts\. You can do this by specifying a replication configuration in your registry settings\. For more information, see [Private registry settings](registry-settings.md)\. -------------------------------------------------------------------------------- /doc_source/ecr-supported-iam-actions-tagging.md: -------------------------------------------------------------------------------- 1 | # Using Tag\-Based Access Control 2 | 3 | The Amazon ECR CreateRepository API action enables you to specify tags when you create the repository\. For more information, see [Tagging an Amazon ECR repository](ecr-using-tags.md)\. 4 | 5 | To enable users to tag repositories on creation, they must have permissions to use the action that creates the resource \(for example, `ecr:CreateRepository`\)\. If tags are specified in the resource\-creating action, Amazon performs additional authorization on the `ecr:CreateRepository` action to verify if users have permissions to create tags\. 6 | 7 | You can used tag\-based access control through IAM policies\. The following are examples\. 8 | 9 | The following policy would only allow an IAM user to create or tag a repository as `key=environment,value=dev`\. 10 | 11 | ``` 12 | { 13 | "Version": "2012-10-17", 14 | "Statement": [ 15 | { 16 | "Sid": "AllowCreateTaggedRepository", 17 | "Effect": "Allow", 18 | "Action": [ 19 | "ecr:CreateRepository" 20 | ], 21 | "Resource": "*", 22 | "Condition": { 23 | "StringEquals": { 24 | "aws:RequestTag/environment": "dev" 25 | } 26 | } 27 | }, 28 | { 29 | "Sid": "AllowTagRepository", 30 | "Effect": "Allow", 31 | "Action": [ 32 | "ecr:TagResource" 33 | ], 34 | "Resource": "*", 35 | "Condition": { 36 | "StringEquals": { 37 | "aws:RequestTag/environment": "dev" 38 | } 39 | } 40 | } 41 | ] 42 | } 43 | ``` 44 | 45 | The following policy would allow an IAM user access to all repositories unless they were tagged as `key=environment,value=prod`\. 46 | 47 | ``` 48 | { 49 | "Version": "2012-10-17", 50 | "Statement": [ 51 | { 52 | "Effect": "Allow", 53 | "Action": "ecr:*", 54 | "Resource": "*" 55 | }, 56 | { 57 | "Effect": "Deny", 58 | "Action": "ecr:*", 59 | "Resource": "*", 60 | "Condition": { 61 | "StringEquals": { 62 | "ecr:ResourceTag/environment": "prod" 63 | } 64 | } 65 | } 66 | ] 67 | } 68 | ``` -------------------------------------------------------------------------------- /doc_source/ECR_on_ECS.md: -------------------------------------------------------------------------------- 1 | # Using Amazon ECR images with Amazon ECS 2 | 3 | You can use your container images hosted in Amazon ECR in your Amazon ECS task definitions, but you need to satisfy the following prerequisites\. 4 | + When using the EC2 launch type for your Amazon ECS tasks, your container instances must be using at least version 1\.7\.0 of the Amazon ECS container agent\. The latest version of the Amazon ECS–optimized AMI supports Amazon ECR images in task definitions\. For more information, including the latest Amazon ECS–optimized AMI IDs, see [Amazon ECS\-optimized AMI versions](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-ami-versions.html) in the *Amazon Elastic Container Service Developer Guide*\. 5 | + The Amazon ECS container instance IAM role \(`ecsInstanceRole`\) that you use must contain the following IAM policy permissions for Amazon ECR\. 6 | 7 | ``` 8 | { 9 | "Version": "2012-10-17", 10 | "Statement": [ 11 | { 12 | "Effect": "Allow", 13 | "Action": [ 14 | "ecr:BatchCheckLayerAvailability", 15 | "ecr:BatchGetImage", 16 | "ecr:GetDownloadUrlForLayer", 17 | "ecr:GetAuthorizationToken" 18 | ], 19 | "Resource": "*" 20 | } 21 | ] 22 | } 23 | ``` 24 | 25 | If you use the **AmazonEC2ContainerServiceforEC2Role** managed policy, then your container instance IAM role has the proper permissions\. To check that your role supports Amazon ECR, see [Amazon ECS container instance IAM role](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/instance_IAM_role.html) in the *Amazon Elastic Container Service Developer Guide*\. 26 | + In your Amazon ECS task definitions, make sure that you are using the full `registry/repository:tag` naming for your Amazon ECR images\. For example, `aws_account_id.dkr.ecr.region.amazonaws.com``/my-web-app:latest`\. 27 | 28 | The following task definition snippet shows the syntax you would use to specify a container image hosted in Amazon ECR in your Amazon ECS task definition\. 29 | 30 | ``` 31 | { 32 | "family": "task-definition-name", 33 | ... 34 | "containerDefinitions": [ 35 | { 36 | "name": "container-name", 37 | "image": "aws_account_id.dkr.ecr.region.amazonaws.com/my-web-app:latest", 38 | ... 39 | } 40 | ], 41 | ... 42 | } 43 | ``` -------------------------------------------------------------------------------- /doc_source/docker-pull-ecr-image.md: -------------------------------------------------------------------------------- 1 | # Pulling an image 2 | 3 | If you want to run a Docker image that is available in Amazon ECR, you can pull it to your local environment with the docker pull command\. You can do this from either your default registry or from a registry associated with another AWS account\. To use an Amazon ECR image in an Amazon ECS task definition, see [Using Amazon ECR images with Amazon ECS](ECR_on_ECS.md)\. 4 | 5 | **Important** 6 | Amazon ECR requires that users have permission to make calls to the `ecr:GetAuthorizationToken` API through an IAM policy before they can authenticate to a registry and push or pull any images from any Amazon ECR repository\. Amazon ECR provides several managed IAM policies to control user access at varying levels; for more information, see [Amazon Elastic Container Registry Identity\-Based Policy Examples](security_iam_id-based-policy-examples.md)\. 7 | 8 | **To pull a Docker image from an Amazon ECR repository** 9 | 10 | 1. Authenticate your Docker client to the Amazon ECR registry that you intend to pull your image from\. Authentication tokens must be obtained for each registry used, and the tokens are valid for 12 hours\. For more information, see [Private registry authentication](registry_auth.md)\. 11 | 12 | 1. \(Optional\) Identify the image to pull\. 13 | + You can list the repositories in a registry with the aws ecr describe\-repositories command: 14 | 15 | ``` 16 | aws ecr describe-repositories 17 | ``` 18 | 19 | The example registry above has a repository called `amazonlinux`\. 20 | + You can describe the images within a repository with the aws ecr describe\-images command: 21 | 22 | ``` 23 | aws ecr describe-images --repository-name amazonlinux 24 | ``` 25 | 26 | The example repository above has an image tagged as `latest` and `2016.09`, with the image digest `sha256:f1d4ae3f7261a72e98c6ebefe9985cf10a0ea5bd762585a43e0700ed99863807`\. 27 | 28 | 1. Pull the image using the docker pull command\. The image name format should be `registry/repository[:tag]` to pull by tag, or `registry/repository[@digest]` to pull by digest\. 29 | 30 | ``` 31 | docker pull aws_account_id.dkr.ecr.us-west-2.amazonaws.com/amazonlinux:latest 32 | ``` 33 | **Important** 34 | If you receive a `repository-url not found: does not exist or no pull access` error, you might need to authenticate your Docker client with Amazon ECR\. For more information, see [Private registry authentication](registry_auth.md)\. -------------------------------------------------------------------------------- /doc_source/registry-settings-examples.md: -------------------------------------------------------------------------------- 1 | # Private image replication examples 2 | 3 | The following examples show how private image replication can be used\. 4 | 5 | ## Example: Configuring cross\-Region replication to a single destination Region 6 | 7 | The following shows an example for configuring cross\-Region replication within a single registry\. This example assumes that your account ID is `111122223333` and that you're specifying this replication configuration in a Region other than `us-west-2`\. 8 | 9 | ``` 10 | { 11 | "rules": [ 12 | { 13 | "destinations": [ 14 | { 15 | "region": "us-west-2", 16 | "registryId": "111122223333" 17 | } 18 | ] 19 | } 20 | ] 21 | } 22 | ``` 23 | 24 | ## Example: Configuring cross\-Region replication to multiple destination Regions 25 | 26 | The following shows an example for configuring cross\-Region replication within a single registry\. This example assumes your account ID is `111122223333` and that you're specifying this replication configuration in a Region other than `us-west-1` or `us-west-2`\. 27 | 28 | ``` 29 | { 30 | "rules": [ 31 | { 32 | "destinations": [ 33 | { 34 | "region": "us-west-1", 35 | "registryId": "111122223333" 36 | }, 37 | { 38 | "region": "us-west-2", 39 | "registryId": "111122223333" 40 | } 41 | ] 42 | } 43 | ] 44 | } 45 | ``` 46 | 47 | ## Example: Configuring cross\-account replication 48 | 49 | The following shows an example for configuring cross\-account replication for your registry\. This example configures replication to the `444455556666` account and to the `us-west-2` Region\. 50 | 51 | **Important** 52 | For cross\-account replication to occur, the destination account must configure a registry permissions policy to allow replication to occur\. For more information, see [Private registry permissions](registry-permissions.md)\. 53 | 54 | ``` 55 | { 56 | "rules": [ 57 | { 58 | "destinations": [ 59 | { 60 | "region": "us-west-2", 61 | "registryId": "444455556666" 62 | } 63 | ] 64 | } 65 | ] 66 | } 67 | ``` -------------------------------------------------------------------------------- /doc_source/data-protection.md: -------------------------------------------------------------------------------- 1 | # Data protection in Amazon ECR 2 | 3 | The AWS [shared responsibility model](http://aws.amazon.com/compliance/shared-responsibility-model/) applies to data protection in Amazon Elastic Container Service\. As described in this model, AWS is responsible for protecting the global infrastructure that runs all of the AWS Cloud\. You are responsible for maintaining control over your content that is hosted on this infrastructure\. This content includes the security configuration and management tasks for the AWS services that you use\. For more information about data privacy, see the [Data Privacy FAQ](http://aws.amazon.com/compliance/data-privacy-faq)\. For information about data protection in Europe, see the [AWS Shared Responsibility Model and GDPR](http://aws.amazon.com/blogs/security/the-aws-shared-responsibility-model-and-gdpr/) blog post on the *AWS Security Blog*\. 4 | 5 | For data protection purposes, we recommend that you protect AWS account credentials and set up individual user accounts with AWS Identity and Access Management \(IAM\)\. That way each user is given only the permissions necessary to fulfill their job duties\. We also recommend that you secure your data in the following ways: 6 | + Use multi\-factor authentication \(MFA\) with each account\. 7 | + Use SSL/TLS to communicate with AWS resources\. We recommend TLS 1\.2 or later\. 8 | + Set up API and user activity logging with AWS CloudTrail\. 9 | + Use AWS encryption solutions, along with all default security controls within AWS services\. 10 | + Use advanced managed security services such as Amazon Macie, which assists in discovering and securing personal data that is stored in Amazon S3\. 11 | + If you require FIPS 140\-2 validated cryptographic modules when accessing AWS through a command line interface or an API, use a FIPS endpoint\. For more information about the available FIPS endpoints, see [Federal Information Processing Standard \(FIPS\) 140\-2](http://aws.amazon.com/compliance/fips/)\. 12 | 13 | We strongly recommend that you never put sensitive identifying information, such as your customers' account numbers, into free\-form fields such as a **Name** field\. This includes when you work with Amazon ECS or other AWS services using the console, API, AWS CLI, or AWS SDKs\. Any data that you enter into Amazon ECS or other services might get picked up for inclusion in diagnostic logs\. When you provide a URL to an external server, don't include credentials information in the URL to validate your request to that server\. 14 | 15 | **Topics** 16 | + [Encryption at rest](encryption-at-rest.md) -------------------------------------------------------------------------------- /doc_source/docker-push-multi-architecture-image.md: -------------------------------------------------------------------------------- 1 | # Pushing a multi\-architecture image 2 | 3 | Amazon ECR supports creating and pushing Docker manifest lists, which are used for multi\-architecture images\. A *manifest list* is a list of images that is created by specifying one or more image names\. In most cases, the manifest list is created from images that serve the same function but for different operating systems or architectures\. The manifest list isn't required\. For more information, see [docker manifest](https://docs.docker.com/engine/reference/commandline/manifest/)\. 4 | 5 | **Important** 6 | Your Docker CLI must have experimental features enabled to use this feature\. For more information, see [Experimental features](https://docs.docker.com/engine/reference/commandline/cli/#experimental-features)\. 7 | 8 | A manifest list can be pulled or referenced in an Amazon ECS task definition or Amazon EKS pod spec like other Amazon ECR images\. 9 | 10 | The following steps can be used to create and push a Docker manifest list to an Amazon ECR repository\. You must already have the images pushed to your repository to reference in the Docker manifest\. For information about how to push an image, see [Pushing a Docker image](docker-push-ecr-image.md)\. 11 | 12 | **To push a multi\-architecture Docker image to an Amazon ECR repository** 13 | 14 | 1. Authenticate your Docker client to the Amazon ECR registry where you intend to push your image\. Authentication tokens must be obtained for each registry used, and the tokens are valid for 12 hours\. For more information, see [Private registry authentication](registry_auth.md)\. 15 | 16 | 1. List the images in your repository, confirming the image tags\. 17 | 18 | ``` 19 | aws ecr describe-images --repository-name my-web-app 20 | ``` 21 | 22 | 1. Create the Docker manifest list\. The `manifest create` command verifies that the referenced images are already in your repository and creates the manifest locally\. 23 | 24 | ``` 25 | docker manifest create aws_account_id.dkr.ecr.region.amazonaws.com/my-web-app aws_account_id.dkr.ecr.region.amazonaws.com/my-web-app:image_one_tag aws_account_id.dkr.ecr.region.amazonaws.com/my-web-app:image_two 26 | ``` 27 | 28 | 1. \(Optional\) Inspect the Docker manifest list\. This enables you to confirm the size and digest for each image manifest referenced in the manifest list\. 29 | 30 | ``` 31 | docker manifest inspect aws_account_id.dkr.ecr.region.amazonaws.com/my-web-app 32 | ``` 33 | 34 | 1. Push the Docker manifest list to your Amazon ECR repository\. 35 | 36 | ``` 37 | docker manifest push aws_account_id.dkr.ecr.region.amazonaws.com/my-web-app 38 | ``` -------------------------------------------------------------------------------- /doc_source/registry-settings-configure.md: -------------------------------------------------------------------------------- 1 | # Configuring private image replication 2 | 3 | Replication settings are configured separately for each Region\. Use the following steps to configure replication for your private registry\. 4 | 5 | **To configure registry replication settings \(AWS Management Console\)** 6 | 7 | 1. Open the Amazon ECR console at [https://console\.aws\.amazon\.com/ecr/repositories](https://console.aws.amazon.com/ecr/repositories)\. 8 | 9 | 1. From the navigation bar, choose the Region to configure your registry replication settings for\. 10 | 11 | 1. In the navigation pane, choose **Registries**\. 12 | 13 | 1. On the **Registries** page, select your **Private** registry and choose **Edit**\. 14 | 15 | 1. On the **Edit registry** page, do the following\. 16 | 17 | 1. For **Cross\-Region replication**, choose the cross\-Region replication setting for the registry\. If set to **Enabled**, choose one or more **Destination regions**\. 18 | 19 | 1. For **Cross\-account replication**, choose the cross\-account replication setting for the registry\. If set to **Enabled**, enter the account ID for the destination account and one or more **Destination regions** to replicate to\. 20 | **Important** 21 | For cross\-account replication to occur, the destination account must configure a registry permissions policy to allow replication to occur\. For more information, see [Private registry permissions](registry-permissions.md)\. 22 | 23 | 1. Choose **Save**\. 24 | 25 | **To configure registry replication settings \(AWS CLI\)** 26 | 27 | 1. Create a JSON file containing the replication configuration settings to define for your registry\. This might contain one or more rules, with each rule containing a destination Region and account\. If you want to replicate the images in your own registry between Regions, then specify your own account ID\. For more examples, see [Private image replication examples](registry-settings-examples.md)\. 28 | 29 | ``` 30 | { 31 | "rules": [ 32 | { 33 | "destinations": [ 34 | { 35 | "region": "destination_region", 36 | "registryId": "destination_accountId" 37 | } 38 | ] 39 | } 40 | ] 41 | } 42 | ``` 43 | 44 | 1. Create a replication configuration for your registry\. 45 | 46 | ``` 47 | aws ecr put-replication-configuration \ 48 | --replication-configuration file://crr-setup.json \ 49 | --region us-west-2 50 | ``` 51 | 52 | 1. Confirm your registry settings\. 53 | 54 | ``` 55 | aws ecr describe-registry \ 56 | --region us-west-2 57 | ``` -------------------------------------------------------------------------------- /doc_source/docker-push-ecr-image.md: -------------------------------------------------------------------------------- 1 | # Pushing a Docker image 2 | 3 | You can push your Docker images to an Amazon ECR repository with the docker push command\. 4 | 5 | **Important** 6 | Amazon ECR requires that users have permission to make calls to the `ecr:GetAuthorizationToken` API through an IAM policy before they can authenticate to a registry and push or pull any images from any Amazon ECR repository\. Amazon ECR provides several managed IAM policies to control user access at varying levels; for more information, see [Amazon Elastic Container Registry Identity\-Based Policy Examples](security_iam_id-based-policy-examples.md)\. 7 | 8 | Amazon ECR also supports creating and pushing Docker manifest lists, which are used for multi\-architecture images\. Each image referenced in a manifest list must already be pushed to your repository\. For more information, see [Pushing a multi\-architecture image](docker-push-multi-architecture-image.md)\. 9 | 10 | **To push a Docker image to an Amazon ECR repository** 11 | 12 | 1. Authenticate your Docker client to the Amazon ECR registry to which you intend to push your image\. Authentication tokens must be obtained for each registry used, and the tokens are valid for 12 hours\. For more information, see [Private registry authentication](registry_auth.md)\. 13 | 14 | 1. If your image repository doesn't exist in the registry you intend to push to yet, create it\. For more information, see [Creating a repository](repository-create.md)\. 15 | 16 | 1. Identify the image to push\. Run the docker images command to list the images on your system\. 17 | 18 | ``` 19 | docker images 20 | ``` 21 | 22 | You can identify an image with the *repository:tag* value or the image ID in the resulting command output\. 23 | 24 | 1. Tag your image with the Amazon ECR registry, repository, and optional image tag name combination to use\. The registry format is `aws_account_id.dkr.ecr.region.amazonaws.com`\. The repository name should match the repository that you created for your image\. If you omit the image tag, we assume that the tag is `latest`\. 25 | 26 | The following example tags an image with the ID *e9ae3c220b23* as `aws_account_id.dkr.ecr.region.amazonaws.com``/my-web-app`\. 27 | 28 | ``` 29 | docker tag e9ae3c220b23 aws_account_id.dkr.ecr.region.amazonaws.com/my-web-app 30 | ``` 31 | 32 | 1. Push the image using the docker push command: 33 | 34 | ``` 35 | docker push aws_account_id.dkr.ecr.region.amazonaws.com/my-web-app 36 | ``` 37 | 38 | 1. \(Optional\) Apply any additional tags to your image and push those tags to Amazon ECR by repeating [Step 4](#image-tag-step) and [Step 5](#image-push-step)\. -------------------------------------------------------------------------------- /doc_source/registry-permissions-create.md: -------------------------------------------------------------------------------- 1 | # Setting a private registry permission statement 2 | 3 | You can add or update the permissions policy for your registry by using the following steps\. You can add multiple policy statements per registry\. For example policies, see [Private registry policy examples](registry-permissions-examples.md)\. 4 | 5 | **To configure a permissions policy for a private registry \(AWS Management Console\)** 6 | 7 | 1. Open the Amazon ECR console at [https://console\.aws\.amazon\.com/ecr/](https://console.aws.amazon.com/ecr/)\. 8 | 9 | 1. From the navigation bar, choose the Region to configure your registry policy in\. 10 | 11 | 1. In the navigation pane, choose **Registries**\. 12 | 13 | 1. On the **Registries** page, select your **Private** registry and choose **Permissions**\. 14 | 15 | 1. On the **Private registry permissions** page, choose **Generate statement**\. 16 | 17 | 1. Complete the following steps to define your policy statement using the policy generator\. 18 | 19 | 1. For **Policy type**, choose **Cross\-account policy**\. 20 | 21 | 1. For **Statement ID**, enter a unique statement ID\. This field is used as the `Sid` on the registry policy\. 22 | 23 | 1. For **Accounts**, enter the account IDs for each account you want to grant permissions to\. When specifying multiple account IDs, separate them with a comma\. 24 | 25 | 1. Expand the **Preview policy statement** section to review the registry permissions policy statement\. 26 | 27 | 1. After the policy statement is confirmed, choose **Add to policy** to save the policy to your registry\. 28 | 29 | **To configure a permissions policy for a private registry \(AWS CLI\)** 30 | 31 | 1. Create a file named `registry_policy.json` and populate it with a registry policy\. 32 | 33 | ``` 34 | { 35 | "Version":"2012-10-17", 36 | "Statement":[ 37 | { 38 | "Sid":"ReplicationAccessCrossAccount", 39 | "Effect":"Allow", 40 | "Principal":{ 41 | "AWS":"arn:aws:iam::source_account_id:root" 42 | }, 43 | "Action":[ 44 | "ecr:CreateRepository", 45 | "ecr:ReplicateImage" 46 | ], 47 | "Resource": [ 48 | "arn:aws:ecr:us-west-2:your_account_id:repository/*" 49 | ] 50 | } 51 | ] 52 | } 53 | ``` 54 | 55 | 1. Create the registry policy using the policy file\. 56 | 57 | ``` 58 | aws ecr put-registry-policy \ 59 | --policy-text file://registry_policy.json \ 60 | --region us-west-2 61 | ``` 62 | 63 | 1. Retrieve the policy for your registry to confirm\. 64 | 65 | ``` 66 | aws ecr get-registry-policy \ 67 | --region us-west-2 68 | ``` -------------------------------------------------------------------------------- /doc_source/getting-started-console.md: -------------------------------------------------------------------------------- 1 | # Getting started with Amazon ECR using the AWS Management Console 2 | 3 | Get started with Amazon ECR by creating a repository in the Amazon ECR console\. The Amazon ECR console guides you through the process to get started creating your first repository\. 4 | 5 | Before you begin, be sure that you've completed the steps in [Setting up with Amazon ECR](get-set-up-for-amazon-ecr.md)\. 6 | 7 | **To create an image repository** 8 | 9 | A repository is where you store your Docker or Open Container Initiative \(OCI\) images in Amazon ECR\. Each time you push or pull an image from Amazon ECR, you specify the repository and the registry location which informs where to push the image to or where to pull it from\. 10 | 11 | 1. Open the Amazon ECR console at [https://console\.aws\.amazon\.com/ecr/](https://console.aws.amazon.com/ecr/)\. 12 | 13 | 1. Choose **Get Started**\. 14 | 15 | 1. For **Tag immutability**, choose the tag mutability setting for the repository\. Repositories configured with immutable tags will prevent image tags from being overwritten\. For more information, see [Image tag mutability](image-tag-mutability.md)\. 16 | 17 | 1. For **Scan on push**, choose the image scanning setting for the repository\. Repositories configured to scan on push will start an image scan whenever an image is pushed, otherwise image scans need to be started manually\. For more information, see [Image scanning](image-scanning.md)\. 18 | 19 | 1. Choose **Create repository**\. 20 | 21 | **Build, tag, and push a Docker image** 22 | 23 | In this section of the wizard, you use the Docker CLI to tag an existing local image \(that you have built from a Dockerfile or pulled from another registry, such as Docker Hub\) and then push the tagged image to your Amazon ECR registry\. For more detailed steps on using the Docker CLI, see [Using Amazon ECR with the AWS CLI](getting-started-cli.md)\. 24 | 25 | 1. Select the repository you created and choose **View push commands** to view the steps to push an image to your new repository\. 26 | 27 | 1. Run the login command that authenticates your Docker client to your registry by pasting the command from the console into a terminal window\. This command provides an authorization token that is valid for 12 hours\. 28 | 29 | 1. \(Optional\) If you have a Dockerfile for the image to push, build the image and tag it for your new repository\. Pasting the docker build command from the console into a terminal window\. Make sure that you are in the same directory as your Dockerfile\. 30 | 31 | 1. Tag the image with your Amazon ECR registry URI and your new repository by pasting the docker tag command from the console into a terminal window\. The console command assumes that your image was built from a Dockerfile in the previous step\. If you did not build your image from a Dockerfile, replace the first instance of `repository:latest` with the image ID or image name of your local image to push\. 32 | 33 | 1. Push the newly tagged image to your repository by pasting the docker push command into a terminal window\. 34 | 35 | 1. Choose **Close**\. -------------------------------------------------------------------------------- /doc_source/amazon_linux_container_image.md: -------------------------------------------------------------------------------- 1 | # Amazon Linux container image 2 | 3 | The Amazon Linux container image is built from the same software components that are included in the Amazon Linux AMI\. It's available for use in any environment as a base image for Docker workloads\. If you're using the Amazon Linux AMI for applications in Amazon EC2, you can containerize your applications with the Amazon Linux container image\. 4 | 5 | You can use the Amazon Linux container image in your local development environment and then push your application to the AWS Cloud using Amazon ECS\. For more information, see [Using Amazon ECR images with Amazon ECS](ECR_on_ECS.md)\. 6 | 7 | The Amazon Linux container image is available in Amazon ECR and on [Docker Hub](https://hub.docker.com/_/amazonlinux/)\. Support for the Amazon Linux container image can be found by visiting the [AWS developer forums](https://forums.aws.amazon.com/forum.jspa?forumID=228)\. 8 | 9 | **To pull the Amazon Linux container image from Amazon ECR** 10 | 11 | 1. Authenticate your Docker client to the Amazon Linux container image Amazon ECR registry\. Authentication tokens are valid for 12 hours\. For more information, see [Private registry authentication](registry_auth.md)\. 12 | **Note** 13 | The get\-login\-password command is available in the AWS CLI starting with version `1.17.10`\. For more information, see [Installing the AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) in the *AWS Command Line Interface User Guide*\. 14 | 15 | ``` 16 | aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 137112412989.dkr.ecr.us-east-1.amazonaws.com 17 | ``` 18 | 19 | The output is as follows: 20 | 21 | ``` 22 | Login succeeded 23 | ``` 24 | **Important** 25 | If you receive an error, install, or upgrade to the latest version of the AWS CLI\. For more information, see [Installing the AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) in the *AWS Command Line Interface User Guide*\. 26 | 27 | 1. \(Optional\) You can list the images within the Amazon Linux repository with the aws ecr list\-images command\. The `latest` tag always corresponds with the latest Amazon Linux container image that is available\. 28 | 29 | ``` 30 | aws ecr list-images --region us-east-1 --registry-id 137112412989 --repository-name amazonlinux 31 | ``` 32 | 33 | 1. Pull the Amazon Linux container image using the docker pull command\. 34 | 35 | ``` 36 | docker pull 137112412989.dkr.ecr.us-east-1.amazonaws.com/amazonlinux:latest 37 | ``` 38 | 39 | 1. \(Optional\) Run the container locally\. 40 | 41 | ``` 42 | docker run -it 137112412989.dkr.ecr.us-east-1.amazonaws.com/amazonlinux:latest /bin/bash 43 | ``` 44 | 45 | **To pull the Amazon Linux container image from Docker Hub** 46 | 47 | 1. Pull the Amazon Linux container image using the docker pull command\. 48 | 49 | ``` 50 | docker pull amazonlinux 51 | ``` 52 | 53 | 1. \(Optional\) Run the container locally\. 54 | 55 | ``` 56 | docker run -it amazonlinux:latest /bin/bash 57 | ``` -------------------------------------------------------------------------------- /doc_source/image-manifest-formats.md: -------------------------------------------------------------------------------- 1 | # Container image manifest formats 2 | 3 | Amazon ECR supports the following container image manifest formats: 4 | + Docker Image Manifest V2 Schema 1 \(used with Docker version 1\.9 and older\) 5 | + Docker Image Manifest V2 Schema 2 \(used with Docker version 1\.10 and newer\) 6 | + Open Container Initiative \(OCI\) Specifications \(v1\.0 and up\) 7 | 8 | Support for Docker Image Manifest V2 Schema 2 provides the following functionality: 9 | + The ability to use multiple tags for a singular image\. 10 | + Support for storing Windows container images\. For more information, see [Pushing Windows Images to Amazon ECR](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/windows_ecr.html) in the *Amazon Elastic Container Service Developer Guide*\. 11 | 12 | ## Amazon ECR image manifest conversion 13 | 14 | When you push and pull images to and from Amazon ECR, your container engine client \(for example, Docker\) communicates with the registry to agree on a manifest format that is understood by the client and the registry to use for the image\. 15 | 16 | When you push an image to Amazon ECR with Docker version 1\.9 or earlier, the image manifest format is stored as Docker Image Manifest V2 Schema 1\. When you push an image to Amazon ECR with Docker version 1\.10 or later, the image manifest format is stored as Docker Image Manifest V2 Schema 2\. 17 | 18 | When you pull an image from Amazon ECR *by tag*, Amazon ECR returns the image manifest format that is stored in the repository\. The format is returned only if that format is understood by the client\. If the stored image manifest format isn't understood by the client, Amazon ECR converts the image manifest into a format that is understood\. For example, if a Docker 1\.9 client requests an image manifest that is stored as Docker Image Manifest V2 Schema 2, Amazon ECR returns the manifest in the Docker Image Manifest V2 Schema 1 format\. The following table describes the available conversions supported by Amazon ECR when an image is pulled *by tag*: 19 | 20 | 21 | | Schema requested by client | Pushed to ECR as V2, schema 1 | Pushed to ECR as V2, schema 2 | Pushed to ECR as OCI | 22 | | --- | --- | --- | --- | 23 | | V2, schema 1 | No translation required | Translated to V2, schema 1 | Translated to V2, schema 1 | 24 | | V2, schema 2 | No translation available, client falls back to V2, schema 1 | No translation required | Translated to V2, schema 2 | 25 | | OCI | No translation available | Translated to OCI | No translation required | 26 | 27 | **Important** 28 | If you pull an image *by digest*, there is no translation available\. Your client must understand the image manifest format that is stored in Amazon ECR\. If you request a Docker Image Manifest V2 Schema 2 image by digest on a Docker 1\.9 or older client, the image pull fails\. For more information, see [Registry compatibility](https://docs.docker.com/registry/compatibility/) in the Docker documentation\. 29 | In this example, if you request the same image *by tag*, Amazon ECR translates the image manifest into a format that the client can understand\. The image pull succeeds\. -------------------------------------------------------------------------------- /doc_source/set-repository-policy.md: -------------------------------------------------------------------------------- 1 | # Setting a repository policy statement 2 | 3 | You can add an access policy statement to a repository in the AWS Management Console by following the steps below\. You can add multiple policy statements per repository\. For example policies, see [Repository policy examples](repository-policy-examples.md)\. 4 | 5 | **Important** 6 | Amazon ECR requires that users have permission to make calls to the `ecr:GetAuthorizationToken` API through an IAM policy before they can authenticate to a registry and push or pull any images from any Amazon ECR repository\. Amazon ECR provides several managed IAM policies to control user access at varying levels; for more information, see [Amazon Elastic Container Registry Identity\-Based Policy Examples](security_iam_id-based-policy-examples.md)\. 7 | 8 | **To set a repository policy statement** 9 | 10 | 1. Open the Amazon ECR console at [https://console\.aws\.amazon\.com/ecr/repositories](https://console.aws.amazon.com/ecr/repositories)\. 11 | 12 | 1. From the navigation bar, choose the Region that contains the repository to set a policy statement on\. 13 | 14 | 1. In the navigation pane, choose **Repositories**\. 15 | 16 | 1. On the **Repositories** page, choose the repository to set a policy statement on to view the contents of the repository\. 17 | 18 | 1. From the repository image list view, in the navigation pane, choose **Permissions**, **Edit**\. 19 | **Note** 20 | If you don't see the **Permissions** option in the navigation pane, ensure that you are in the repository image list view\. 21 | 22 | 1. On the **Edit permissions** page, choose **Add statement**\. 23 | 24 | 1. For **Statement name**, enter a name for the statement\. 25 | 26 | 1. For **Effect**, choose whether the policy statement will result in an allow or an explicit deny\. 27 | 28 | 1. For **Principal**, choose the scope to apply the policy statement to\. For more information, see [AWS JSON Policy Elements: Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html) in the *IAM User Guide*\. 29 | + You can apply the statement to all authenticated AWS users by selecting the **Everyone \(\*\)** check box\. 30 | + For **Service principal**, specify the service principal name \(for example, `ecs.amazonaws.com`\) to apply the statement to a specific service\. 31 | + For **AWS Account IDs**, specify an AWS account number \(for example, `111122223333`\) to apply the statement to all users under a specific AWS account\. Multiple accounts can be specified by using a comma delimited list\. 32 | + For **IAM Entities**, select the roles or users under your AWS account to apply the statement to\. 33 | **Note** 34 | For more complicated repository policies that are not currently supported in the AWS Management Console, you can apply the policy with the [https://docs.aws.amazon.com/cli/latest/reference/ecr/set-repository-policy.html](https://docs.aws.amazon.com/cli/latest/reference/ecr/set-repository-policy.html) AWS CLI command\. 35 | 36 | 1. For **Actions**, choose the scope of the Amazon ECR API operations that the policy statement should apply to from the list of individual API operations\. 37 | 38 | 1. When you are finished, choose **Save** to set the policy\. 39 | 40 | 1. Repeat the previous step for each repository policy to add\. -------------------------------------------------------------------------------- /doc_source/repository-policies.md: -------------------------------------------------------------------------------- 1 | # Repository policies 2 | 3 | Amazon ECR uses resource\-based permissions to control access to repositories\. Resource\-based permissions let you specify which IAM users or roles have access to a repository and what actions they can perform on it\. By default, only the repository owner has access to a repository\. You can apply a policy document that allow additional permissions to your repository\. 4 | 5 | ## Repository policies vs IAM policies 6 | 7 | Amazon ECR repository policies are a subset of IAM policies that are scoped for, and specifically used for, controlling access to individual Amazon ECR repositories\. IAM policies are generally used to apply permissions for the entire Amazon ECR service but can also be used to control access to specific resources as well\. 8 | 9 | Both Amazon ECR repository policies and IAM policies are used when determining which actions a specific IAM user or role may perform on a repository\. If a user or role is allowed to perform an action through a repository policy but is denied permission through an IAM policy \(or vice versa\) then the action will be denied\. A user or role only needs to be allowed permission for an action through either a repository policy or an IAM policy but not both for the action to be allowed\. 10 | 11 | **Important** 12 | Amazon ECR requires that users have permission to make calls to the `ecr:GetAuthorizationToken` API through an IAM policy before they can authenticate to a registry and push or pull any images from any Amazon ECR repository\. Amazon ECR provides several managed IAM policies to control user access at varying levels; for more information, see [Amazon Elastic Container Registry Identity\-Based Policy Examples](security_iam_id-based-policy-examples.md)\. 13 | 14 | You can use either of these policy types to control access to your repositories, as shown in the following examples\. 15 | 16 | This example shows an Amazon ECR repository policy, which allows for a specific IAM user to describe the repository and the images within the repository\. 17 | 18 | ``` 19 | { 20 | "Version": "2008-10-17", 21 | "Statement": [{ 22 | "Sid": "ECR Repository Policy", 23 | "Effect": "Allow", 24 | "Principal": { 25 | "AWS": "arn:aws:iam::account-id:user/username" 26 | }, 27 | "Action": [ 28 | "ecr:DescribeImages", 29 | "ecr:DescribeRepositories" 30 | ] 31 | }] 32 | } 33 | ``` 34 | 35 | This example shows an IAM policy that achieves the same goal as above, by scoping the policy to a repository \(specified by the full ARN of the repository\) using the resource parameter\. For more information about Amazon Resource Name \(ARN\) format, see [Resources](security_iam_service-with-iam.md#security_iam_service-with-iam-id-based-policies-resources)\. 36 | 37 | ``` 38 | { 39 | "Version": "2012-10-17", 40 | "Statement": [{ 41 | "Sid": "ECR Repository Policy", 42 | "Effect": "Allow", 43 | "Principal": { 44 | "AWS": "arn:aws:iam::account-id:user/username" 45 | }, 46 | "Action": [ 47 | "ecr:DescribeImages", 48 | "ecr:DescribeRepositories" 49 | ], 50 | "Resource": [ 51 | "arn:aws:ecr:region:account-id:repository/repository-name" 52 | ] 53 | }] 54 | } 55 | ``` 56 | 57 | **Topics** 58 | + [Repository policies vs IAM policies](#repository-policy-vs-iam-policy) 59 | + [Setting a repository policy statement](set-repository-policy.md) 60 | + [Deleting a repository policy statement](delete-repository-policy.md) 61 | + [Repository policy examples](repository-policy-examples.md) -------------------------------------------------------------------------------- /doc_source/repository-create.md: -------------------------------------------------------------------------------- 1 | # Creating a repository 2 | 3 | Before you can push your Docker images to Amazon ECR, you must create a repository to store them in\. You can create Amazon ECR repositories with the AWS Management Console, or with the AWS CLI and AWS SDKs\. 4 | 5 | **To create a repository** 6 | 7 | 1. Open the Amazon ECR console at [https://console\.aws\.amazon\.com/ecr/repositories](https://console.aws.amazon.com/ecr/repositories)\. 8 | 9 | 1. From the navigation bar, choose the Region to create your repository in\. 10 | 11 | 1. In the navigation pane, choose **Repositories**\. 12 | 13 | 1. On the **Repositories** page, choose **Create repository**\. 14 | 15 | 1. For **Repository name**, enter a unique name for your repository\. The repository name can be specified on its own \(for example `nginx-web-app`\)\. Alternatively, it can be prepended with a namespace to group the repository into a category \(for example `project-a/nginx-web-app`\)\. 16 | **Note** 17 | The name must start with a letter and can only contain lowercase letters, numbers, hyphens \(\-\), underscores \(\_\), and forward slashes \(/\)\. 18 | 19 | 1. For **Tag immutability**, choose the tag mutability setting for the repository\. Repositories configured with immutable tags prevent image tags from being overwritten\. For more information, see [Image tag mutability](image-tag-mutability.md)\. 20 | 21 | 1. For **Scan on push**, choose the image scanning setting for the repository\. Repositories that are configured to scan on push start an image scan whenever an image is pushed\. If you want to start an image scan at a different time, you need to manually start the image scans\. For more information, see [Image scanning](image-scanning.md)\. 22 | 23 | 1. For **KMS encryption**, choose whether to enable encryption of the images in the repository using AWS Key Management Service\. By default, when KMS encryption is enabled, Amazon ECR uses an AWS managed customer master key \(CMK\) with the alias `aws/ecr`\. This master key is created in your account the first time that you create a repository with KMS encryption enabled\. For more information, see [Encryption at rest](encryption-at-rest.md)\. 24 | 25 | 1. When KMS encryption is enabled, select **Customer encryption settings \(advanced\)** to choose your own CMK\. The CMK must be in the same Region as the cluster\. Choose **Create an AWS KMS key** to navigate to the AWS KMS console to create your own key\. 26 | 27 | 1. Choose **Create repository**\. 28 | 29 | 1. \(Optional\) Select the repository that you created and choose **View push commands** to view the steps to push an image to your new repository\. 30 | 31 | 1. Run the login command that authenticates your Docker client to your registry by pasting the command from the console into a terminal window\. This command provides an authorization token that is valid for 12 hours\. 32 | 33 | 1. \(Optional\) If you have a Dockerfile for the image to push, build the image and tag it for your new repository\. Pasting the docker build command from the console into a terminal window\. Make sure that you are in the same directory as your Dockerfile\. 34 | 35 | 1. Tag the image with your Amazon ECR registry URI and your new repository by pasting the docker tag command from the console into a terminal window\. The console command assumes that your image was built from a Dockerfile in the previous step\. If you did not build your image from a Dockerfile, replace the first instance of `repository:latest` with the image ID or image name of your local image to push\. 36 | 37 | 1. Push the newly tagged image to your repository by pasting the docker push command into a terminal window\. 38 | 39 | 1. Choose **Close**\. -------------------------------------------------------------------------------- /doc_source/replication.md: -------------------------------------------------------------------------------- 1 | # Private image replication 2 | 3 | Amazon ECR uses **registry settings** to configure private image replication at the registry level\. An Amazon ECR private registry can be configured for either cross\-Region or cross\-account replication\. Replication is configured for a private registry separately for each Region\. The following describes the supported replication methods in more detail\. 4 | 5 | **Cross\-Region replication** 6 | Enabling cross\-Region replication for your registry makes copies of the repositories in one or more destination Regions\. Only images pushed to a repository after cross\-Region replication is configured are copied\. 7 | 8 | **Cross\-account replication** 9 | Enabling cross\-account replication for your registry makes copies of the repositories in the destination account and Regions you specify\. For cross\-account replication to occur, the destination account must configure a registry permissions policy to allow replication from your registry to occur\. For more information, see [Private registry permissions](registry-permissions.md)\. 10 | 11 | **Topics** 12 | + [Considerations for private image replication](#replication-considerations) 13 | + [Configuring private image replication](registry-settings-configure.md) 14 | + [Private image replication examples](registry-settings-examples.md) 15 | 16 | ## Considerations for private image replication 17 | 18 | The following should be considered when using private image replication\. 19 | + The first time you configure your private registry for replication, Amazon ECR creates a service\-linked role on your behalf\. The service\-linked role grants the Amazon ECR replication service the permission it needs to create repositories and replicate images in your registry\. For more information, see [Using service\-linked roles for Amazon ECR](using-service-linked-roles.md)\. 20 | + For cross\-account replication to occur, the destination private registry must grant permission to allow the source registry to replicate its images\. For more information, see [Private registry permissions](registry-permissions.md)\. 21 | + If the permissions for a registry are changed to remove a permission, any in\-progress replications previously granted may complete\. 22 | + A replication action only occurs once per image push\. For example, if you configured cross\-Region replication from `us-west-2` to `us-east-1` and from `us-east-1` to `us-east-2`, an image pushed to `us-west-2` replicates to only `us-east-1`, it doesn't replicate again to `us-east-2`\. This behavior applies to both cross\-Region and cross\-account replication\. 23 | + A Region must be enabled for an account prior to any replication actions occurring within or to that Region\. For more information, see [Managing AWS Regions](https://docs.aws.amazon.com/general/latest/gr/rande-manage.html) in the *Amazon Web Services General Reference*\. 24 | + Registry replication doesn't perform any delete actions\. Replicated images and repositories can be manually deleted when they are no longer being used\. 25 | + Lifecycle policies aren't replicated and don't have any effect other than the repository they are defined for\. 26 | + Repository settings aren't replicated\. The tag immutability, image scanning, and KMS encryption settings are disabled by default on all repositories created because of a replication action\. The tag immutability and image scanning setting can be changed after the repository is created\. However, the setting only applies to images pushed after the setting has changed\. 27 | + If tag immutability is enabled on a repository and an image is replicated that uses the same tag as an existing image, the image is replicated but won't contain the duplicated tag\. This might result in the image being untagged\. -------------------------------------------------------------------------------- /doc_source/ecr-eventbridge.md: -------------------------------------------------------------------------------- 1 | # Amazon ECR events and EventBridge 2 | 3 | Amazon EventBridge enables you to automate your AWS services and to respond automatically to system events such as application availability issues or resource changes\. Events from AWS services are delivered to EventBridge in near real time\. You can write simple rules to indicate which events are of interest to you and include automated actions to take when an event matches a rule\. The actions that can be automatically triggered include the following: 4 | + Adding events to log groups in CloudWatch Logs 5 | + Invoking an AWS Lambda function 6 | + Invoking Amazon EC2 Run Command 7 | + Relaying the event to Amazon Kinesis Data Streams 8 | + Activating an AWS Step Functions state machine 9 | + Notifying an Amazon SNS topic or an Amazon SQS queue 10 | 11 | For more information, see [Getting Started with Amazon EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-getting-set-up.html) in the *Amazon EventBridge User Guide*\. 12 | 13 | ## Sample events from Amazon ECR 14 | 15 | The following are example events from Amazon ECR\. Events are emitted on a best effort basis\. 16 | 17 | **Event for a completed image push** 18 | 19 | The following event is sent when each image push is completed\. For more information, see [Pushing a Docker image](docker-push-ecr-image.md)\. 20 | 21 | ``` 22 | { 23 | "version": "0", 24 | "id": "13cde686-328b-6117-af20-0e5566167482", 25 | "detail-type": "ECR Image Action", 26 | "source": "aws.ecr", 27 | "account": "123456789012", 28 | "time": "2019-11-16T01:54:34Z", 29 | "region": "us-west-2", 30 | "resources": [], 31 | "detail": { 32 | "result": "SUCCESS", 33 | "repository-name": "my-repo", 34 | "image-digest": "sha256:7f5b2640fe6fb4f46592dfd3410c4a79dac4f89e4782432e0378abcd1234", 35 | "action-type": "PUSH", 36 | "image-tag": "latest" 37 | } 38 | } 39 | ``` 40 | 41 | **Event for a completed image scan** 42 | 43 | The following event is sent when each image scan is completed\. The `finding-severity-counts` parameter will only return a value for a severity level if one exists\. For example, if the image contains no findings at `CRITICAL` level, then no critical count is returned\. For more information, see [Image scanning](image-scanning.md)\. 44 | 45 | ``` 46 | { 47 | "version": "0", 48 | "id": "85fc3613-e913-7fc4-a80c-a3753e4aa9ae", 49 | "detail-type": "ECR Image Scan", 50 | "source": "aws.ecr", 51 | "account": "123456789012", 52 | "time": "2019-10-29T02:36:48Z", 53 | "region": "us-east-1", 54 | "resources": [ 55 | "arn:aws:ecr:us-east-1:123456789012:repository/my-repo" 56 | ], 57 | "detail": { 58 | "scan-status": "COMPLETE", 59 | "repository-name": "my-repo", 60 | "finding-severity-counts": { 61 | "CRITICAL": 10, 62 | "MEDIUM": 9 63 | }, 64 | "image-digest": "sha256:7f5b2640fe6fb4f46592dfd3410c4a79dac4f89e4782432e0378abcd1234", 65 | "image-tags": [] 66 | } 67 | } 68 | ``` 69 | 70 | **Event for an image deletion** 71 | 72 | The following event is sent when an image is deleted\. For more information, see [Deleting an image](delete_image.md)\. 73 | 74 | ``` 75 | { 76 | "version": "0", 77 | "id": "dd3b46cb-2c74-f49e-393b-28286b67279d", 78 | "detail-type": "ECR Image Action", 79 | "source": "aws.ecr", 80 | "account": "123456789012", 81 | "time": "2019-11-16T02:01:05Z", 82 | "region": "us-west-2", 83 | "resources": [], 84 | "detail": { 85 | "result": "SUCCESS", 86 | "repository-name": "my-repo", 87 | "image-digest": "sha256:7f5b2640fe6fb4f46592dfd3410c4a79dac4f89e4782432e0378abcd1234", 88 | "action-type": "DELETE", 89 | "image-tag": "latest" 90 | } 91 | } 92 | ``` -------------------------------------------------------------------------------- /doc_source/registry-permissions-examples.md: -------------------------------------------------------------------------------- 1 | # Private registry policy examples 2 | 3 | The following examples show registry permissions policy statements that you could use to control the permissions that users have to your Amazon ECR registry\. 4 | 5 | ## Example: Allow the root user of a source account to replicate all repositories 6 | 7 | ``` 8 | { 9 | "Version":"2012-10-17", 10 | "Statement":[ 11 | { 12 | "Sid":"ReplicationAccessCrossAccount", 13 | "Effect":"Allow", 14 | "Principal":{ 15 | "AWS":"arn:aws:iam::source_account_id:root" 16 | }, 17 | "Action":[ 18 | "ecr:CreateRepository", 19 | "ecr:ReplicateImage" 20 | ], 21 | "Resource": [ 22 | "arn:aws:ecr:us-west-2:your_account_id:repository/*" 23 | ] 24 | } 25 | ] 26 | } 27 | ``` 28 | 29 | ## Example: Allow multiple accounts 30 | 31 | ``` 32 | { 33 | "Version":"2012-10-17", 34 | "Statement":[ 35 | { 36 | "Sid":"ReplicationAccessCrossAccount", 37 | "Effect":"Allow", 38 | "Principal":{ 39 | "AWS":"arn:aws:iam::source_account_id:root" 40 | }, 41 | "Action":[ 42 | "ecr:CreateRepository", 43 | "ecr:ReplicateImage" 44 | ], 45 | "Resource": [ 46 | "arn:aws:ecr:us-west-2:your_account_id:repository/*" 47 | ] 48 | }, 49 | { 50 | "Sid":"ReplicationAccessCrossAccount", 51 | "Effect":"Allow", 52 | "Principal":{ 53 | "AWS":"arn:aws:iam::source_account_id:root" 54 | }, 55 | "Action":[ 56 | "ecr:CreateRepository", 57 | "ecr:ReplicateImage" 58 | ], 59 | "Resource": [ 60 | "arn:aws:ecr:us-west-2:your_account_id:repository/*" 61 | ] 62 | } 63 | ] 64 | } 65 | ``` 66 | 67 | ## Example: Allow the root user of a source account to replicate all repositories starting with `prod-` 68 | 69 | ``` 70 | { 71 | "Version":"2012-10-17", 72 | "Statement":[ 73 | { 74 | "Sid":"ReplicationAccessCrossAccount", 75 | "Effect":"Allow", 76 | "Principal":{ 77 | "AWS":"arn:aws:iam::source_account_id:root" 78 | }, 79 | "Action":[ 80 | "ecr:CreateRepository", 81 | "ecr:ReplicateImage" 82 | ], 83 | "Resource": [ 84 | "arn:aws:ecr:us-west-2:your_account_id:repository/prod-*" 85 | ] 86 | } 87 | ] 88 | } 89 | ``` 90 | 91 | ## Example: Allow the root user of a source account to replicate all repositories starting with `prod-` 92 | 93 | If the `ecr:CreateRepository` action is removed from your registry permission statement, you can replicate your repositories\. However, for successful replication, you need to create repositories with the same name within your account\. 94 | 95 | ``` 96 | { 97 | "Version":"2012-10-17", 98 | "Statement":[ 99 | { 100 | "Sid":"ReplicationAccessCrossAccount", 101 | "Effect":"Allow", 102 | "Principal":{ 103 | "AWS":"arn:aws:iam::source_account_id:root" 104 | }, 105 | "Action":[ 106 | "ecr:ReplicateImage" 107 | ], 108 | "Resource": [ 109 | "arn:aws:ecr:us-west-2:your_account_id:repository/*" 110 | ] 111 | } 112 | ] 113 | } 114 | ``` -------------------------------------------------------------------------------- /doc_source/what-is-ecr.md: -------------------------------------------------------------------------------- 1 | # What is Amazon Elastic Container Registry? 2 | 3 | Amazon Elastic Container Registry \(Amazon ECR\) is an AWS managed container image registry service that is secure, scalable, and reliable\. Amazon ECR supports private container image repositories with resource\-based permissions using AWS IAM\. This is so that specified users or Amazon EC2 instances can access your container repositories and images\. You can use your preferred CLI to push, pull, and manage Docker images, Open Container Initiative \(OCI\) images, and OCI compatible artifacts\. 4 | 5 | **Note** 6 | Amazon ECR supports public container image repositories as well\. For more information, see [What is Amazon ECR Public](https://docs.aws.amazon.com/AmazonECR/latest/public/what-is-ecr.html) in the *Amazon ECR Public User Guide*\. 7 | 8 | The AWS container services team maintains a public roadmap on GitHub\. It contains information about what the teams are working on and allows all AWS customers the ability to give direct feedback\. For more information, see [AWS Containers Roadmap](https://github.com/aws/containers-roadmap)\. 9 | 10 | ## Components of Amazon ECR 11 | 12 | Amazon ECR contains the following components: 13 | 14 | Registry 15 | An Amazon ECR registry is provided to each AWS account; you can create image repositories in your registry and store images in them\. For more information, see [Amazon ECR private registries](Registries.md)\. 16 | 17 | Authorization token 18 | Your client must authenticate to Amazon ECR registries as an AWS user before it can push and pull images\. For more information, see [Private registry authentication](registry_auth.md)\. 19 | 20 | Repository 21 | An Amazon ECR image repository contains your Docker images, Open Container Initiative \(OCI\) images, and OCI compatible artifacts\. For more information, see [Amazon ECR private repositories](Repositories.md)\. 22 | 23 | Repository policy 24 | You can control access to your repositories and the images within them with repository policies\. For more information, see [Repository policies](repository-policies.md)\. 25 | 26 | Image 27 | You can push and pull container images to your repositories\. You can use these images locally on your development system, or you can use them in Amazon ECS task definitions and Amazon EKS pod specifications\. For more information, see [Using Amazon ECR images with Amazon ECS](ECR_on_ECS.md) and [Using Amazon ECR Images with Amazon EKS](ECR_on_EKS.md)\. 28 | 29 | ## Features of Amazon ECR 30 | 31 | Amazon ECR provides the following features: 32 | + Lifecycle policies help with managing the lifecycle of the images in your repositories\. You define rules that result in the cleaning up of unused images\. You can test rules before applying them to your repository\. For more information, see [Lifecycle policies](LifecyclePolicies.md)\. 33 | + Image scanning helps in identifying software vulnerabilities in your container images\. Each repository can be configured to **scan on push**\. This ensures that each new image pushed to the repository is scanned\. You can then retrieve the results of the image scan\. For more information, see [Image scanning](image-scanning.md)\. 34 | + Cross\-Region and cross\-account replication makes it easier for you to have your images where you need them\. This is configured as a registry setting and is on a per\-Region basis\. For more information, see [Private registry settings](registry-settings.md)\. 35 | 36 | ## How to get started with Amazon ECR 37 | 38 | To use Amazon ECR, you must be set up to install the AWS Command Line Interface and Docker\. For more information, see [Setting up with Amazon ECR](get-set-up-for-amazon-ecr.md) and [Using Amazon ECR with the AWS CLI](getting-started-cli.md)\. 39 | 40 | ## Pricing for Amazon ECR 41 | 42 | With Amazon ECR, you only pay for the amount of data you store in your repositories and for the data transfer from your image pushes and pulls\. For more information, see [Amazon ECR pricing](http://aws.amazon.com/ecr/pricing/)\. -------------------------------------------------------------------------------- /doc_source/image-retag.md: -------------------------------------------------------------------------------- 1 | # Retagging an image 2 | 3 | With Docker Image Manifest V2 Schema 2 images, you can use the `--image-tag` option of the put\-image command to retag an existing image\. You can retag without pulling or pushing the image with Docker\. For larger images, this process saves a considerable amount of network bandwidth and time required to retag an image\. 4 | 5 | ## To retag an image \(AWS CLI\) 6 | 7 | **To retag an image with the AWS CLI** 8 | 9 | 1. Use the batch\-get\-image command to get the image manifest for the image to retag and write it to an environment variable\. In this example, the manifest for an image with the tag, *latest*, in the repository, *amazonlinux*, is written to the environment variable, *MANIFEST*\. 10 | 11 | ``` 12 | MANIFEST=$(aws ecr batch-get-image --repository-name amazonlinux --image-ids imageTag=latest --query 'images[].imageManifest' --output text) 13 | ``` 14 | 15 | 1. Use the `--image-tag` option of the put\-image command to put the image manifest to Amazon ECR with a new tag\. In this example, the image is tagged as *2017\.03*\. 16 | **Note** 17 | If the `--image-tag` option isn't available in your version of the AWS CLI, upgrade to the latest version\. For more information, see [Installing the AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) in the *AWS Command Line Interface User Guide*\. 18 | 19 | ``` 20 | aws ecr put-image --repository-name amazonlinux --image-tag 2017.03 --image-manifest "$MANIFEST" 21 | ``` 22 | 23 | 1. Verify that your new image tag is attached to your image\. In the following output, the image has the tags `latest` and `2017.03`\. 24 | 25 | ``` 26 | aws ecr describe-images --repository-name amazonlinux 27 | ``` 28 | 29 | The output is as follows: 30 | 31 | ``` 32 | { 33 | "imageDetails": [ 34 | { 35 | "imageSizeInBytes": 98755613, 36 | "imageDigest": "sha256:8d00af8f076eb15a33019c2a3e7f1f655375681c4e5be157a2685dfe6f247227", 37 | "imageTags": [ 38 | "latest", 39 | "2017.03" 40 | ], 41 | "registryId": "aws_account_id", 42 | "repositoryName": "amazonlinux", 43 | "imagePushedAt": 1499287667.0 44 | } 45 | ] 46 | } 47 | ``` 48 | 49 | ## To retag an image \(AWS Tools for Windows PowerShell\) 50 | 51 | **To retag an image with the AWS Tools for Windows PowerShell** 52 | 53 | 1. Use the Get\-ECRImageBatch cmdlet to obtain the description of the image to retag and write it to an environment variable\. In this example, an image with the tag, *latest*, in the repository, *amazonlinux*, is written to the environment variable, *$Image*\. 54 | **Note** 55 | If you don't have the Get\-ECRImageBatch cmdlet available on your system, see [Setting up the AWS Tools for Windows PowerShell](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-getting-set-up.html) in the *AWS Tools for Windows PowerShell User Guide*\. 56 | 57 | ``` 58 | $Image = Get-ECRImageBatch -ImageId @{ imageTag="latest" } -RepositoryName amazonlinux 59 | ``` 60 | 61 | 1. Write the manifest of the image to the *$Manifest* environment variable\. 62 | 63 | ``` 64 | $Manifest = $Image.Images[0].ImageManifest 65 | ``` 66 | 67 | 1. Use the `-ImageTag` option of the Write\-ECRImage cmdlet to put the image manifest to Amazon ECR with a new tag\. In this example, the image is tagged as *2017\.09*\. 68 | 69 | ``` 70 | Write-ECRImage -RepositoryName amazonlinux -ImageManifest $Manifest -ImageTag 2017.09 71 | ``` 72 | 73 | 1. Verify that your new image tag is attached to your image\. In the following output, the image has the tags `latest` and `2017.09`\. 74 | 75 | ``` 76 | Get-ECRImage -RepositoryName amazonlinux 77 | ``` 78 | 79 | The output is as follows: 80 | 81 | ``` 82 | ImageDigest ImageTag 83 | ----------- -------- 84 | sha256:359b948ea8866817e94765822787cd482279eed0c17bc674a7707f4256d5d497 latest 85 | sha256:359b948ea8866817e94765822787cd482279eed0c17bc674a7707f4256d5d497 2017.09 86 | ``` -------------------------------------------------------------------------------- /doc_source/ECR_on_EKS.md: -------------------------------------------------------------------------------- 1 | # Using Amazon ECR Images with Amazon EKS 2 | 3 | You can use your Amazon ECR images with Amazon EKS, but you need to satisfy the following prerequisites\. 4 | + The Amazon EKS worker node IAM role \(`NodeInstanceRole`\) that you use with your worker nodes must possess the following IAM policy permissions for Amazon ECR\. 5 | 6 | ``` 7 | { 8 | "Version": "2012-10-17", 9 | "Statement": [ 10 | { 11 | "Effect": "Allow", 12 | "Action": [ 13 | "ecr:BatchCheckLayerAvailability", 14 | "ecr:BatchGetImage", 15 | "ecr:GetDownloadUrlForLayer", 16 | "ecr:GetAuthorizationToken" 17 | ], 18 | "Resource": "*" 19 | } 20 | ] 21 | } 22 | ``` 23 | **Note** 24 | If you used `eksctl` or the AWS CloudFormation templates in [Getting Started with Amazon EKS](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html) to create your cluster and worker node groups, these IAM permissions are applied to your worker node IAM role by default\. 25 | + When referencing an image from Amazon ECR, you must use the full `registry/repository:tag` naming for the image\. For example, `aws_account_id.dkr.ecr.region.amazonaws.com``/my-web-app:latest`\. 26 | 27 | ## Installing a Helm chart hosted on Amazon ECR with Amazon EKS 28 | 29 | Your Helm charts hosted in Amazon ECR can be installed on your Amazon EKS clusters\. The following steps demonstrate this\. 30 | 31 | **Prerequisites** 32 | Before you begin, ensure the following steps have been completed\. 33 | + Install the Helm client version 3\. For more information, see [Installing Helm](https://helm.sh/docs/intro/install/)\. 34 | + You have pushed a Helm chart to your Amazon ECR repository\. For more information, see [Pushing a Helm chart](push-oci-artifact.md)\. 35 | + You have configured `kubectl` to work with Amazon EKS\. For more information, see [Create a `kubeconfig` for Amazon EKS](https://docs.aws.amazon.com/eks/latest/userguide/create-kubeconfig.html) in the **Amazon EKS User Guide**\. If the following commands succeeds for your cluster, you're properly configured\. 36 | 37 | ``` 38 | kubectl get svc 39 | ``` 40 | 41 | **Install an Amazon ECR hosted Helm chart to an Amazon EKS cluster** 42 | 43 | 1. Enable OCI support in the Helm 3 client\. 44 | 45 | ``` 46 | export HELM_EXPERIMENTAL_OCI=1 47 | ``` 48 | 49 | 1. Authenticate your Helm client to the Amazon ECR registry that your Helm chart is hosted\. Authentication tokens must be obtained for each registry used, and the tokens are valid for 12 hours\. For more information, see [Private registry authentication](registry_auth.md)\. 50 | 51 | ``` 52 | aws ecr get-login-password \ 53 | --region us-west-2 | helm registry login \ 54 | --username AWS \ 55 | --password-stdin aws_account_id.dkr.ecr.region.amazonaws.com 56 | ``` 57 | 58 | 1. Pull your Helm chart to your local cache\. 59 | 60 | ``` 61 | helm chart pull aws_account_id.dkr.ecr.region.amazonaws.com/repository-name:mychart 62 | ``` 63 | 64 | 1. Export the chart to a local directory\. In this example, we use a directory named `charts`\. 65 | 66 | ``` 67 | helm chart export aws_account_id.dkr.ecr.region.amazonaws.com/repository-name:mychart --destination ./charts 68 | ``` 69 | 70 | 1. Install the chart\. 71 | 72 | ``` 73 | helm install ecr-chart-demo ./mychart 74 | ``` 75 | 76 | The output should look similar to this: 77 | 78 | ``` 79 | NAME: ecr-chart-demo 80 | LAST DEPLOYED: Wed Sep 2 14:32:07 2020 81 | NAMESPACE: default 82 | STATUS: deployed 83 | REVISION: 1 84 | NOTES: 85 | ``` 86 | 87 | 1. Verify the chart installation\. The output will be a YAML representation of the Kubernetes resources deployed by the chart\. 88 | 89 | ``` 90 | helm get manifest ecr-chart-demo 91 | ``` 92 | 93 | 1. \(Optional\) See your Helm chart running in your Amazon EKS pod\. 94 | 95 | ``` 96 | kubectl get pods --all-namespaces 97 | ``` 98 | 99 | 1. When you are finished, you can remove the chart release from your cluster\. 100 | 101 | ``` 102 | helm uninstall ecr-chart-demo 103 | ``` -------------------------------------------------------------------------------- /doc_source/ecr_managed_policies.md: -------------------------------------------------------------------------------- 1 | # Amazon ECR Managed Policies 2 | 3 | Amazon ECR provides several managed policies that you can attach to IAM users or EC2 instances that allow differing levels of control over Amazon ECR resources and API operations\. You can apply these policies directly, or you can use them as starting points for creating your own policies\. For more information about each API operation mentioned in these policies, see [Actions](https://docs.aws.amazon.com/AmazonECR/latest/APIReference/API_Operations.html) in the *Amazon Elastic Container Registry API Reference*\. 4 | 5 | **Topics** 6 | + [`AmazonEC2ContainerRegistryFullAccess`](#AmazonEC2ContainerRegistryFullAccess) 7 | + [`AmazonEC2ContainerRegistryPowerUser`](#AmazonEC2ContainerRegistryPowerUser) 8 | + [`AmazonEC2ContainerRegistryReadOnly`](#AmazonEC2ContainerRegistryReadOnly) 9 | 10 | ## `AmazonEC2ContainerRegistryFullAccess` 11 | 12 | This managed policy is a starting point for customers who are looking to provide an IAM user or role with full administrator access to manage their use of Amazon ECR\. The [Amazon ECR Lifecycle Policies](https://docs.aws.amazon.com/AmazonECR/latest/userguide/LifecyclePolicies.html) feature enables customers to specify the lifecycle management of images in a repository\. Lifecycle policy events are reported as CloudTrail events, and Amazon ECR is integrated with AWS CloudTrail to display a customer's lifecycle policy events directly in the Amazon ECR console\. The `AmazonEC2ContainerRegistryFullAccess` managed IAM policy includes the `cloudtrail:LookupEvents` permission to facilitate this behavior\. 13 | 14 | ``` 15 | { 16 | "Version": "2012-10-17", 17 | "Statement": [ 18 | { 19 | "Effect": "Allow", 20 | "Action": [ 21 | "ecr:*", 22 | "cloudtrail:LookupEvents" 23 | ], 24 | "Resource": "*" 25 | } 26 | ] 27 | } 28 | ``` 29 | 30 | ## `AmazonEC2ContainerRegistryPowerUser` 31 | 32 | This managed policy allows power user access to Amazon ECR, which allows read and write access to repositories, but does not allow users to delete repositories or change the policy documents applied to them\. 33 | 34 | ``` 35 | { 36 | "Version": "2012-10-17", 37 | "Statement": [ 38 | { 39 | "Effect": "Allow", 40 | "Action": [ 41 | "ecr:GetAuthorizationToken", 42 | "ecr:BatchCheckLayerAvailability", 43 | "ecr:GetDownloadUrlForLayer", 44 | "ecr:GetRepositoryPolicy", 45 | "ecr:DescribeRepositories", 46 | "ecr:ListImages", 47 | "ecr:DescribeImages", 48 | "ecr:BatchGetImage", 49 | "ecr:GetLifecyclePolicy", 50 | "ecr:GetLifecyclePolicyPreview", 51 | "ecr:ListTagsForResource", 52 | "ecr:DescribeImageScanFindings", 53 | "ecr:InitiateLayerUpload", 54 | "ecr:UploadLayerPart", 55 | "ecr:CompleteLayerUpload", 56 | "ecr:PutImage" 57 | ], 58 | "Resource": "*" 59 | } 60 | ] 61 | } 62 | ``` 63 | 64 | ## `AmazonEC2ContainerRegistryReadOnly` 65 | 66 | This managed policy allows read\-only access to Amazon ECR, such as the ability to list repositories and the images within the repositories, and also to pull images from Amazon ECR with the Docker CLI\. 67 | 68 | ``` 69 | { 70 | "Version": "2012-10-17", 71 | "Statement": [ 72 | { 73 | "Effect": "Allow", 74 | "Action": [ 75 | "ecr:GetAuthorizationToken", 76 | "ecr:BatchCheckLayerAvailability", 77 | "ecr:GetDownloadUrlForLayer", 78 | "ecr:GetRepositoryPolicy", 79 | "ecr:DescribeRepositories", 80 | "ecr:ListImages", 81 | "ecr:DescribeImages", 82 | "ecr:BatchGetImage", 83 | "ecr:GetLifecyclePolicy", 84 | "ecr:GetLifecyclePolicyPreview", 85 | "ecr:ListTagsForResource", 86 | "ecr:DescribeImageScanFindings" 87 | ], 88 | "Resource": "*" 89 | } 90 | ] 91 | } 92 | ``` -------------------------------------------------------------------------------- /doc_source/push-oci-artifact.md: -------------------------------------------------------------------------------- 1 | # Pushing a Helm chart 2 | 3 | Amazon ECR supports pushing Open Container Initiative \(OCI\) artifacts to your repositories\. To display this functionality, use the following steps to push a Helm chart to Amazon ECR\. 4 | 5 | For more information about using your Amazon ECR hosted Helm charts with Amazon EKS, see [Installing a Helm chart hosted on Amazon ECR with Amazon EKS](ECR_on_EKS.md#using-helm-charts-eks)\. 6 | 7 | **To push a Helm chart to an Amazon ECR repository** 8 | 9 | 1. Install the Helm client version 3\. For more information, see [Installing Helm](https://helm.sh/docs/intro/install/)\. 10 | 11 | 1. Enable OCI support in the Helm 3 client\. 12 | 13 | ``` 14 | export HELM_EXPERIMENTAL_OCI=1 15 | ``` 16 | 17 | 1. Create a repository to store your Helm chart\. For more information, see [Creating a repository](repository-create.md)\. 18 | 19 | ``` 20 | aws ecr create-repository \ 21 | --repository-name artifact-test \ 22 | --region us-west-2 23 | ``` 24 | 25 | 1. Authenticate your Helm client to the Amazon ECR registry to which you intend to push your Helm chart\. Authentication tokens must be obtained for each registry used, and the tokens are valid for 12 hours\. For more information, see [Private registry authentication](registry_auth.md)\. 26 | 27 | ``` 28 | aws ecr get-login-password \ 29 | --region us-west-2 | helm registry login \ 30 | --username AWS \ 31 | --password-stdin aws_account_id.dkr.ecr.region.amazonaws.com 32 | ``` 33 | 34 | 1. Use the following steps to create a test Helm chart\. For more information, see [Helm Docs \- Getting Started](https://helm.sh/docs/chart_template_guide/getting_started/)\. 35 | 36 | 1. Create a directory named `helm-tutorial` to work in\. 37 | 38 | ``` 39 | mkdir helm-tutorial 40 | cd helm-tutorial 41 | ``` 42 | 43 | 1. Create a Helm chart named `mychart` and clear the contents of the `templates` directory\. 44 | 45 | ``` 46 | helm create mychart 47 | rm -rf ./mychart/templates/* 48 | ``` 49 | 50 | 1. Create a ConfigMap in the `templates` folder\. 51 | 52 | ``` 53 | cd mychart/templates 54 | cat < configmap.yaml 55 | apiVersion: v1 56 | kind: ConfigMap 57 | metadata: 58 | name: mychart-configmap 59 | data: 60 | myvalue: "Hello World" 61 | EOF 62 | ``` 63 | 64 | 1. Save the chart locally and create an alias for the chart with your registry URI\. 65 | 66 | ``` 67 | cd .. 68 | helm chart save . mychart 69 | helm chart save . aws_account_id.dkr.ecr.us-west-2.amazonaws.com/artifact-test:mychart 70 | ``` 71 | 72 | 1. Identify the Helm chart to push\. Run the helm chart list command to list the Helm charts on your system\. 73 | 74 | ``` 75 | helm chart list 76 | ``` 77 | 78 | The output should look similar to this: 79 | 80 | ``` 81 | REF NAME VERSION DIGEST SIZE CREATED 82 | aws_account_id.dkr.ecr.us-west-2.amazonaws.com/artifact-tes.. mychart 0.1.0 30e0a03 3.6 KiB 14 seconds 83 | mychart mychart 0.1.0 ba3e62a 3.6 KiB About a minute 84 | ``` 85 | 86 | 1. Push the Helm chart using the helm chart push command: 87 | 88 | ``` 89 | helm chart push aws_account_id.dkr.ecr.region.amazonaws.com/artifact-test:mychart 90 | ``` 91 | 92 | 1. Describe your Helm chart\. 93 | 94 | ``` 95 | aws ecr describe-images \ 96 | --repository-name artifact-test \ 97 | --region us-west-2 98 | ``` 99 | 100 | In the output, verify that the `artifactMediaType` parameter indicates the proper artifact type\. 101 | 102 | ``` 103 | { 104 | "imageDetails": [ 105 | { 106 | "registryId": "aws_account_id", 107 | "repositoryName": "artifact-test", 108 | "imageDigest": "sha256:f23ab9dc0fda33175e465bd694a5f4cade93eaf62715fa9390d9fEXAMPLE", 109 | "imageTags": [ 110 | "mychart" 111 | ], 112 | "imageSizeInBytes": 3714, 113 | "imagePushedAt": 1597433021.0, 114 | "imageManifestMediaType": "application/vnd.oci.image.manifest.v1+json", 115 | "artifactMediaType": "application/vnd.cncf.helm.config.v1+json" 116 | } 117 | ] 118 | } 119 | ``` -------------------------------------------------------------------------------- /doc_source/doc-history.md: -------------------------------------------------------------------------------- 1 | # Document history 2 | 3 | The following table describes the important changes to the documentation since the last release of Amazon ECR\. We also update the documentation frequently to address the feedback that you send us\. 4 | 5 | 6 | | Change | Description | Date | 7 | | --- | --- | --- | 8 | | Cross\-Region and cross\-account replication | Amazon ECR added support for configuring replication settings for your private registry\. For more information, see [Private registry settings](registry-settings.md)\. | 8 December 2020 | 9 | | OCI artifact support | Amazon ECR added support for pushing and pulling Open Container Initiative \(OCI\) artifacts\. A new parameter `artifactMediaType` was added to the `DescribeImages` API response to indicate the type of artifact\. For more information, see [Pushing a Helm chart](push-oci-artifact.md)\. | 24 August 2020 | 10 | | Encryption at rest | Amazon ECR added support for configuring encryption for your repositories using server\-side encryption with customer master keys \(CMKs\) stored in AWS Key Management Service \(AWS KMS\)\. For more information, see [Encryption at rest](encryption-at-rest.md)\. | 29 July 2020 | 11 | | Multi\-architecture images | Amazon ECR added support for creating and pushing Docker manifest lists which are used for multi\-architecture images\. For more information, see [Pushing a multi\-architecture image](docker-push-multi-architecture-image.md)\. | 28 April 2020 | 12 | | Amazon ECR Usage Metrics | Amazon ECR added CloudWatch usage metrics which provides visiblity into your account's resource usage\. You also have the ability to create CloudWatch alarms from both the CloudWatch and Service Quotas consoles to get alerts when your usage approaches your applied service quota\. For more information, see [Amazon ECR usage metrics](monitoring-usage.md)\. | 28 Feb 2020 | 13 | | Updated Amazon ECR service quotas | Updated the Amazon ECR service quotas to include per\-API quotas\. For more information, see [Amazon ECR service quotas](service-quotas.md)\. | 19 Feb 2020 | 14 | | Added `get-login-password` command | Added support for get\-login\-password, which provides a simple and secure method for retrieving an authorization token\. For more information, see [Using an authorization token](registry_auth.md#registry-auth-token)\. | 4 Feb 2020 | 15 | | Image Scanning | Added support for image scanning, which helps in identifying software vulnerabilities in your container images\. Amazon ECR uses the Common Vulnerabilities and Exposures \(CVEs\) database from the open source CoreOS Clair project and provides you with a list of scan findings\. For more information, see [Image scanning](image-scanning.md)\. | 24 Oct 2019 | 16 | | VPC Endpoint Policy | Added support for setting an IAM policy on the Amazon ECR interface VPC endpoints\. For more information, see [Create an endpoint policy for your Amazon ECR VPC endpoints](vpc-endpoints.md#ecr-vpc-endpoint-policy)\. | 26 Sept 2019 | 17 | | Image Tag Mutability | Added support for configuring a repository to be immutable to prevent image tags from being overwritten\. For more information, see [Image tag mutability](image-tag-mutability.md)\. | 25 July 2019 | 18 | | Interface VPC Endpoints \(AWS PrivateLink\) | Added support for configuring interface VPC endpoints powered by AWS PrivateLink\. This allows you to create a private connection between your VPC and Amazon ECR without requiring access over the internet, through a NAT instance, a VPN connection, or AWS Direct Connect\. For more information, see [Amazon ECR interface VPC endpoints \(AWS PrivateLink\)](vpc-endpoints.md)\. | 25 Jan 2019 | 19 | | Resource tagging | Amazon ECR added support for adding metadata tags to your repositories\. For more information, see [Tagging an Amazon ECR repository](ecr-using-tags.md)\. | 18 Dec 2018 | 20 | | Amazon ECR Name Change | Amazon Elastic Container Registry is renamed \(previously Amazon EC2 Container Registry\)\. | 21 Nov 2017 | 21 | | Lifecycle Policies | Amazon ECR lifecycle policies enable you to specify the lifecycle management of images in a repository\. For more information, see [Lifecycle policies](LifecyclePolicies.md)\. | 11 Oct 2017 | 22 | | Amazon ECR support for Docker image manifest 2, schema 2 | Amazon ECR now supports Docker Image Manifest V2 Schema 2 \(used with Docker version 1\.10 and newer\)\. For more information, see [Container image manifest formats](image-manifest-formats.md)\. | 27 Jan 2017 | 23 | | Amazon ECR General Availability | Amazon Elastic Container Registry \(Amazon ECR\) is a managed AWS Docker registry service that is secure, scalable, and reliable\. | 21 Dec 2015 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Guidelines for contributing 2 | 3 | Thank you for your interest in contributing to AWS documentation! We greatly value feedback and contributions from our community. 4 | 5 | Please read through this document before you submit any pull requests or issues. It will help us work together more effectively. 6 | 7 | ## What to expect when you contribute 8 | 9 | When you submit a pull request, our team is notified and will respond as quickly as we can. We'll do our best to work with you to ensure that your pull request adheres to our style and standards. If we merge your pull request, we might make additional edits later for style or clarity. 10 | 11 | The AWS documentation source files on GitHub aren't published directly to the official documentation website. If we merge your pull request, we'll publish your changes to the documentation website as soon as we can, but they won't appear immediately or automatically. 12 | 13 | We look forward to receiving your pull requests for: 14 | 15 | * New content you'd like to contribute (such as new code samples or tutorials) 16 | * Inaccuracies in the content 17 | * Information gaps in the content that need more detail to be complete 18 | * Typos or grammatical errors 19 | * Suggested rewrites that improve clarity and reduce confusion 20 | 21 | **Note:** We all write differently, and you might not like how we've written or organized something currently. We want that feedback. But please be sure that your request for a rewrite is supported by the previous criteria. If it isn't, we might decline to merge it. 22 | 23 | ## How to contribute 24 | 25 | To contribute, send us a pull request. For small changes, such as fixing a typo or adding a link, you can use the [GitHub Edit Button](https://blog.github.com/2011-04-26-forking-with-the-edit-button/). For larger changes: 26 | 27 | 1. [Fork the repository](https://help.github.com/articles/fork-a-repo/). 28 | 2. In your fork, make your change in a branch that's based on this repo's **master** branch. 29 | 3. Commit the change to your fork, using a clear and descriptive commit message. 30 | 4. [Create a pull request](https://help.github.com/articles/creating-a-pull-request-from-a-fork/), answering any questions in the pull request form. 31 | 32 | Before you send us a pull request, please be sure that: 33 | 34 | 1. You're working from the latest source on the **master** branch. 35 | 2. You check [existing open](https://github.com/awsdocs/amazon-ecr-user-guide/pulls), and [recently closed](https://github.com/awsdocs/amazon-ecr-user-guide/pulls?q=is%3Apr+is%3Aclosed), pull requests to be sure that someone else hasn't already addressed the problem. 36 | 3. You [create an issue](https://github.com/awsdocs/amazon-ecr-user-guide/issues/new) before working on a contribution that will take a significant amount of your time. 37 | 38 | For contributions that will take a significant amount of time, [open a new issue](https://github.com/awsdocs/amazon-ecr-user-guide/issues/new) to pitch your idea before you get started. Explain the problem and describe the content you want to see added to the documentation. Let us know if you'll write it yourself or if you'd like us to help. We'll discuss your proposal with you and let you know whether we're likely to accept it. We don't want you to spend a lot of time on a contribution that might be outside the scope of the documentation or that's already in the works. 39 | 40 | ## Finding contributions to work on 41 | 42 | If you'd like to contribute, but don't have a project in mind, look at the [open issues](https://github.com/awsdocs/amazon-ecr-user-guide/issues) in this repository for some ideas. Any issues with the [help wanted](https://github.com/awsdocs/amazon-ecr-user-guide/labels/help%20wanted) or [enhancement](https://github.com/awsdocs/amazon-ecr-user-guide/labels/enhancement) labels are a great place to start. 43 | 44 | In addition to written content, we really appreciate new examples and code samples for our documentation, such as examples for different platforms or environments, and code samples in additional languages. 45 | 46 | ## Code of conduct 47 | 48 | This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct). For more information, see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact [opensource-codeofconduct@amazon.com](mailto:opensource-codeofconduct@amazon.com) with any additional questions or comments. 49 | 50 | ## Security issue notifications 51 | 52 | If you discover a potential security issue, please notify AWS Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public issue on GitHub. 53 | 54 | ## Licensing 55 | 56 | See the [LICENSE](https://github.com/awsdocs/amazon-ecr-user-guide/blob/master/LICENSE) file for this project's licensing. We will ask you to confirm the licensing of your contribution. We may ask you to sign a [Contributor License Agreement (CLA)](http://en.wikipedia.org/wiki/Contributor_License_Agreement) for larger changes. 57 | -------------------------------------------------------------------------------- /doc_source/common-errors.md: -------------------------------------------------------------------------------- 1 | # Troubleshooting Amazon ECR error messages 2 | 3 | In some cases, an API call that you have triggered through the Amazon ECS console or the AWS CLI exits with an error message\. Some common error messages and potential solutions are explained below\. 4 | 5 | ## Error: "Error Response from Daemon: Invalid Registry Endpoint" 6 | 7 | You may see the following error when running the `aws ecr get-login` command to obtain the login credentials for your Amazon ECR repository: 8 | 9 | ``` 10 | Error response from daemon: invalid registry endpoint 11 | https://xxxxxxxxxxxx.dkr.ecr.us-east-1.amazonaws.com/v0/: unable to ping registry endpoint 12 | https://xxxxxxxxxxxx.dkr.ecr.us-east-1.amazonaws.com/v0/ 13 | v2 ping attempt failed with error: Get https://xxxxxxxxxxxx.dkr.ecr.us-east-1.amazonaws.com/v2/: 14 | dial tcp: lookup xxxxxxxxxxxx.dkr.ecr.us-east-1.amazonaws.com on 172.20.10.1:53: 15 | read udp 172.20.10.1:53: i/o timeout 16 | ``` 17 | 18 | This error can occur on macOS and Windows systems that are running Docker Toolbox, Docker for Windows, or Docker for Mac\. It is often caused when other applications alter the routes through the local gateway \(192\.168\.0\.1\) through which the virtual machine must call to access the Amazon ECR service\. If this error occurs when using Docker Toolbox, then it can often be resolved by restarting the Docker Machine environment, or rebooting the local client operating system\. If this does not resolve the issue, use the docker\-machine ssh command to log in to your container instance\. Perform a DNS lookup on an external host to verify that you see the same results as you see on your local host\. If the results differ, consult the documentation for Docker Toolbox to ensure that your Docker Machine environment is configured properly\. 19 | 20 | ## HTTP 429: Too Many Requests or ThrottleException 21 | 22 | You may receive a `429: Too Many Requests` error or a `ThrottleException` error from one or more Amazon ECR commands or API calls\. If you are using Docker tools with Amazon ECR, then for Docker versions 1\.12\.0 and greater, you may see the error message `TOOMANYREQUESTS: Rate exceeded`\. For versions of Docker below 1\.12\.0, you may see the error `Unknown: Rate exceeded`\. 23 | 24 | This indicates that you are calling a single endpoint in Amazon ECR repeatedly over a short interval, and that your requests are getting throttled\. Throttling occurs when calls to a single endpoint from a single user exceed a certain threshold over a period of time\. 25 | 26 | Various API operations in Amazon ECR have different throttles\. 27 | 28 | For example, the throttle for the [https://docs.aws.amazon.com/AmazonECR/latest/APIReference/API_GetAuthorizationToken.html](https://docs.aws.amazon.com/AmazonECR/latest/APIReference/API_GetAuthorizationToken.html) action is 20 transaction per second \(TPS\), with up to a 200 TPS burst allowed\. In each region, each account receives a bucket that can store up to 200 `GetAuthorizationToken` credits\. These credits are replenished at a rate of 20 per second\. If your bucket has 200 credits, you could achieve 200 `GetAuthorizationToken` API transactions per second for one second, and then sustain 20 transactions per second indefinitely\. 29 | 30 | To handle throttling errors, implement a retry function with incremental backoff into your code\. For more information, see [Error Retries and Exponential Backoff in AWS](https://docs.aws.amazon.com/general/latest/gr/api-retries.html) in the [Amazon Web Services General Reference](https://docs.aws.amazon.com/general/latest/gr/)\. 31 | 32 | ## HTTP 403: "User \[arn\] is not authorized to perform \[operation\]" 33 | 34 | You may receive the following error when attempting to perform an action with Amazon ECR: 35 | 36 | ``` 37 | $ aws ecr get-login 38 | A client error (AccessDeniedException) occurred when calling the GetAuthorizationToken operation: 39 | User: arn:aws:iam::account-number:user/username is not authorized to perform: 40 | ecr:GetAuthorizationToken on resource: * 41 | ``` 42 | 43 | This indicates that your user does not have permissions granted to use Amazon ECR, or that those permissions are not set up correctly\. In particular, if you are performing actions against an Amazon ECR repository, verify that the user has been granted permissions to access that repository\. For more information about creating and verifying permissions for Amazon ECR, see [Identity and Access Management for Amazon Elastic Container Registry](security-iam.md)\. 44 | 45 | ## HTTP 404: "Repository Does Not Exist" error 46 | 47 | If you specify a Docker Hub repository that does not currently exist, Docker Hub creates it automatically\. With Amazon ECR, new repositories must be explicitly created before they can be used\. This prevents new repositories from being created accidentally \(for example, due to typos\), and it also ensures that an appropriate security access policy is explicitly assigned to any new repositories\. For more information about creating repositories, see [Amazon ECR private repositories](Repositories.md)\. -------------------------------------------------------------------------------- /doc_source/index.md: -------------------------------------------------------------------------------- 1 | # Amazon ECR User Guide 2 | 3 | ----- 4 | *****Copyright © Amazon Web Services, Inc. and/or its affiliates. All rights reserved.***** 5 | 6 | ----- 7 | Amazon's trademarks and trade dress may not be used in 8 | connection with any product or service that is not Amazon's, 9 | in any manner that is likely to cause confusion among customers, 10 | or in any manner that disparages or discredits Amazon. All other 11 | trademarks not owned by Amazon are the property of their respective 12 | owners, who may or may not be affiliated with, connected to, or 13 | sponsored by Amazon. 14 | 15 | ----- 16 | ## Contents 17 | + [What is Amazon Elastic Container Registry?](what-is-ecr.md) 18 | + [Setting up with Amazon ECR](get-set-up-for-amazon-ecr.md) 19 | + [Getting started with Amazon ECR using the AWS Management Console](getting-started-console.md) 20 | + [Using Amazon ECR with the AWS CLI](getting-started-cli.md) 21 | + [Amazon ECR private registries](Registries.md) 22 | + [Private registry authentication](registry_auth.md) 23 | + [Private registry settings](registry-settings.md) 24 | + [Private registry permissions](registry-permissions.md) 25 | + [Setting a private registry permission statement](registry-permissions-create.md) 26 | + [Deleting a private registry permission statement](registry-permissions-delete.md) 27 | + [Private registry policy examples](registry-permissions-examples.md) 28 | + [Amazon ECR private repositories](Repositories.md) 29 | + [Creating a repository](repository-create.md) 30 | + [Viewing repository information](repository-info.md) 31 | + [Editing a repository](repository-edit.md) 32 | + [Deleting a repository](repository-delete.md) 33 | + [Repository policies](repository-policies.md) 34 | + [Setting a repository policy statement](set-repository-policy.md) 35 | + [Deleting a repository policy statement](delete-repository-policy.md) 36 | + [Repository policy examples](repository-policy-examples.md) 37 | + [Tagging an Amazon ECR repository](ecr-using-tags.md) 38 | + [Private images](images.md) 39 | + [Pushing an image](image-push.md) 40 | + [Pushing a Docker image](docker-push-ecr-image.md) 41 | + [Pushing a multi-architecture image](docker-push-multi-architecture-image.md) 42 | + [Pushing a Helm chart](push-oci-artifact.md) 43 | + [Viewing image details](image-info.md) 44 | + [Pulling an image](docker-pull-ecr-image.md) 45 | + [Deleting an image](delete_image.md) 46 | + [Retagging an image](image-retag.md) 47 | + [Private image replication](replication.md) 48 | + [Configuring private image replication](registry-settings-configure.md) 49 | + [Private image replication examples](registry-settings-examples.md) 50 | + [Lifecycle policies](LifecyclePolicies.md) 51 | + [Creating a lifecycle policy preview](lpp_creation.md) 52 | + [Creating a lifecycle policy](lp_creation.md) 53 | + [Examples of lifecycle policies](lifecycle_policy_examples.md) 54 | + [Image tag mutability](image-tag-mutability.md) 55 | + [Image scanning](image-scanning.md) 56 | + [Container image manifest formats](image-manifest-formats.md) 57 | + [Using Amazon ECR images with Amazon ECS](ECR_on_ECS.md) 58 | + [Using Amazon ECR Images with Amazon EKS](ECR_on_EKS.md) 59 | + [Amazon Linux container image](amazon_linux_container_image.md) 60 | + [Security in Amazon Elastic Container Registry](security.md) 61 | + [Identity and Access Management for Amazon Elastic Container Registry](security-iam.md) 62 | + [How Amazon Elastic Container Registry Works with IAM](security_iam_service-with-iam.md) 63 | + [Amazon ECR Managed Policies](ecr_managed_policies.md) 64 | + [Using service-linked roles for Amazon ECR](using-service-linked-roles.md) 65 | + [Amazon Elastic Container Registry Identity-Based Policy Examples](security_iam_id-based-policy-examples.md) 66 | + [Using Tag-Based Access Control](ecr-supported-iam-actions-tagging.md) 67 | + [Troubleshooting Amazon Elastic Container Registry Identity and Access](security_iam_troubleshoot.md) 68 | + [Data protection in Amazon ECR](data-protection.md) 69 | + [Encryption at rest](encryption-at-rest.md) 70 | + [Compliance validation for Amazon Elastic Container Registry](ecr-compliance.md) 71 | + [Infrastructure Security in Amazon Elastic Container Registry](infrastructure-security.md) 72 | + [Amazon ECR interface VPC endpoints (AWS PrivateLink)](vpc-endpoints.md) 73 | + [Amazon ECR monitoring](monitoring.md) 74 | + [Visualizing your service quotas and setting alarms](monitoring-quotas-alarms.md) 75 | + [Amazon ECR usage metrics](monitoring-usage.md) 76 | + [Amazon ECR usage reports](usage-reports.md) 77 | + [Amazon ECR events and EventBridge](ecr-eventbridge.md) 78 | + [Logging Amazon ECR actions with AWS CloudTrail](logging-using-cloudtrail.md) 79 | + [Amazon ECR service quotas](service-quotas.md) 80 | + [Amazon ECR troubleshooting](troubleshooting.md) 81 | + [Troubleshooting errors with Docker commands when using Amazon ECR](common-errors-docker.md) 82 | + [Troubleshooting Amazon ECR error messages](common-errors.md) 83 | + [Troubleshooting image scanning issues](image-scanning-troubleshooting.md) 84 | + [Document history](doc-history.md) 85 | + [AWS glossary](glossary.md) -------------------------------------------------------------------------------- /doc_source/service-quotas.md: -------------------------------------------------------------------------------- 1 | # Amazon ECR service quotas 2 | 3 | The following table provides the default service quotas for Amazon Elastic Container Registry \(Amazon ECR\)\. 4 | 5 | 6 | **** 7 | 8 | | Service quota | Description | Default quota value | Adjustable | 9 | | --- | --- | --- | --- | 10 | | Registered repositories | The maximum number of repositories that you can create per Region\. | 10,000 | Yes | 11 | | Image per repository | The maximum number of images per repository\. | 10,000 | Yes | 12 | 13 | The following table provides the default rate quotas for each of the Amazon ECR API actions involved with the image push and image pull actions\. 14 | 15 | 16 | **** 17 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonECR/latest/userguide/service-quotas.html) 18 | 19 | The following table provides other quotas for Amazon ECR and Docker images that cannot be changed\. 20 | 21 | **Note** 22 | The layer part information mentioned in the following table is only applicable if you are calling the Amazon ECR API actions directly to initiate multipart uploads for image push operations\. This is a rare action\. We recommend that you use the Docker CLI to pull, tag, and push images\. 23 | 24 | 25 | | Service quota | Description | Quota value | Adjustable | 26 | | --- | --- | --- | --- | 27 | | Layer parts | The maximum number of layer parts\. This is only applicable if you are using Amazon ECR API actions directly to initiate multipart uploads for image push operations\. | 4,200 | No | 28 | | Maximum layer size | The maximum size \(MiB\) of a layer\. \*\* | 42,000 | No | 29 | | Minimum layer part size | The minimum size \(MiB\) of a layer part\. This is only applicable if you are using Amazon ECR API actions directly to initiate multipart uploads for image push operations\. | 5 | No | 30 | | Maximum layer part size | The maximum size \(MiB\) of a layer part\. This is only applicable if you are using Amazon ECR API actions directly to initiate multipart uploads for image push operations\. | 10 | No | 31 | | Tags per image | The maximum number of tags per image\. | 1,000 | No | 32 | | Lifecycle policy length | The maximum number of characters in a lifecycle policy\. | 30,720 | No | 33 | | Rules per lifecycle policy | The maximum number of rules in a lifecycle policy\. | 50 | No | 34 | | Rate of image scans | The maximum number of image scans per image, per 24 hours\. | 1 | No | 35 | 36 | \*\* The maximum layer size listed here is calculated by multiplying the maximum layer part size \(10 MiB\) by the maximum number of layer parts \(4,200\)\. 37 | 38 | ## Managing your Amazon ECR service quotas in the AWS Management Console 39 | 40 | Amazon ECR has integrated with Service Quotas, an AWS service that enables you to view and manage your quotas from a central location\. For more information, see [What Is Service Quotas?](https://docs.aws.amazon.com/servicequotas/latest/userguide/intro.html) in the *Service Quotas User Guide*\. 41 | 42 | Service Quotas makes it easy to look up the value of all Amazon ECR service quotas\. 43 | 44 | **To view Amazon ECR service quotas \(AWS Management Console\)** 45 | 46 | 1. Open the Service Quotas console at [https://console\.aws\.amazon\.com/servicequotas/](https://console.aws.amazon.com/servicequotas/)\. 47 | 48 | 1. In the navigation pane, choose **AWS services**\. 49 | 50 | 1. From the **AWS services** list, search for and select **Amazon Elastic Container Registry \(Amazon ECR\)**\. 51 | 52 | In the **Service quotas** list, you can see the service quota name, applied value \(if it is available\), AWS default quota, and whether the quota value is adjustable\. 53 | 54 | 1. To view additional information about a service quota, such as the description, choose the quota name\. 55 | 56 | To request a quota increase, see [Requesting a quota increase](https://docs.aws.amazon.com/servicequotas/latest/userguide/request-increase.html) in the *Service Quotas User Guide*\. 57 | 58 | ### Creating a CloudWatch alarm to monitor API usage metrics 59 | 60 | Amazon ECR provides CloudWatch usage metrics that correspond to the AWS service quotas for each of the APIs involved with the registry authentication, image push, and image pull actions\. In the Service Quotas console, you can visualize your usage on a graph and configure alarms that alert you when your usage approaches a service quota\. For more information, see [Amazon ECR usage metrics](monitoring-usage.md)\. 61 | 62 | Use the following steps to create a CloudWatch alarm based on one of the Amazon ECR API usage metrics\. 63 | 64 | **To create an alarm based on your Amazon ECR usage quotas \(AWS Management Console\)** 65 | 66 | 1. Open the Service Quotas console at [https://console\.aws\.amazon\.com/servicequotas/](https://console.aws.amazon.com/servicequotas/)\. 67 | 68 | 1. In the navigation pane, choose **AWS services**\. 69 | 70 | 1. From the **AWS services** list, search for and select **Amazon Elastic Container Registry \(Amazon ECR\)**\. 71 | 72 | 1. In the **Service quotas** list, select the Amazon ECR usage quota you want to create an alarm for\. 73 | 74 | 1. In the Amazon CloudWatch Events alarms section, choose **Create**\. 75 | 76 | 1. For **Alarm threshold**, choose the percentage of your applied quota value that you want to set as the alarm value\. 77 | 78 | 1. For **Alarm name**, enter a name for the alarm and then choose **Create**\. -------------------------------------------------------------------------------- /doc_source/troubleshooting.md: -------------------------------------------------------------------------------- 1 | # Amazon ECR troubleshooting 2 | 3 | This chapter helps you find diagnostic information for Amazon Elastic Container Registry \(Amazon ECR\), and provides troubleshooting steps for common issues and error messages\. 4 | 5 | **Topics** 6 | + [Enabling Docker debug output](#debug) 7 | + [Enabling AWS CloudTrail](#cloudtrail) 8 | + [Optimizing performance for Amazon ECR](#performance) 9 | + [Troubleshooting errors with Docker commands when using Amazon ECR](common-errors-docker.md) 10 | + [Troubleshooting Amazon ECR error messages](common-errors.md) 11 | + [Troubleshooting image scanning issues](image-scanning-troubleshooting.md) 12 | 13 | ## Enabling Docker debug output 14 | 15 | To begin debugging any Docker\-related issue, you should start by enabling Docker debugging output on the Docker daemon running on your host instances\. For more information about enabling Docker debugging if you are using images pulled from Amazon ECR on Amazon ECS container instances, see [Enabling Docker Debug Output](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/troubleshooting.html#docker-debug-mode) in the *Amazon Elastic Container Service Developer Guide*\. 16 | 17 | ## Enabling AWS CloudTrail 18 | 19 | Additional information about errors returned by Amazon ECR can be discovered by enabling AWS CloudTrail, which is a service that records AWS calls for your AWS account\. CloudTrail delivers log files to an Amazon S3 bucket\. By using information collected by CloudTrail, you can determine what requests were successfully made to AWS services, who made the request, when it was made, and so on\. To learn more about CloudTrail, including how to turn it on and find your log files, see the [AWS CloudTrail User Guide](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/)\. For more information on using CloudTrail with Amazon ECR, see [Logging Amazon ECR actions with AWS CloudTrail](logging-using-cloudtrail.md)\. 20 | 21 | ## Optimizing performance for Amazon ECR 22 | 23 | The following section provides recommendations on settings and strategies that can be used to optimize performance when using Amazon ECR\. 24 | 25 | Use Docker 1\.10 and above to take advantage of simultaneous layer uploads 26 | Docker images are composed of layers, which are intermediate build stages of the image\. Each line in a Dockerfile results in the creation of a new layer\. When you use Docker 1\.10 and above, Docker defaults to pushing as many layers as possible as simultaneous uploads to Amazon ECR, resulting in faster upload times\. 27 | 28 | Use a smaller base image 29 | The default images available through Docker Hub may contain many dependencies that your application doesn't require\. Consider using a smaller image created and maintained by others in the Docker community, or build your own base image using Docker's minimal scratch image\. For more information, see [Create a base image](https://docs.docker.com/engine/userguide/eng-image/baseimages/) in the Docker documentation\. 30 | 31 | Place the dependencies that change the least earlier in your Dockerfile 32 | Docker caches layers, and that speeds up build times\. If nothing on a layer has changed since the last build, Docker uses the cached version instead of rebuilding the layer\. However, each layer is dependent on the layers that came before it\. If a layer changes, Docker recompiles not only that layer, but any layers that come after that layer as well\. 33 | To minimize the time required to rebuild a Dockerfile and to re\-upload layers, consider placing the dependencies that change the least frequently earlier in your Dockerfile\. Place rapidly changing dependencies \(such as your application's source code\) later in the stack\. 34 | 35 | Chain commands to avoid unnecessary file storage 36 | Intermediate files created on a layer remain a part of that layer even if they are deleted in a subsequent layer\. Consider the following example: 37 | 38 | ``` 39 | WORKDIR /tmp 40 | RUN wget http://example.com/software.tar.gz 41 | RUN wget tar -xvf software.tar.gz 42 | RUN mv software/binary /opt/bin/myapp 43 | RUN rm software.tar.gz 44 | ``` 45 | In this example, the layers created by the first and second RUN commands contain the original \.tar\.gz file and all of its unzipped contents\. This is even though the \.tar\.gz file is deleted by the fourth RUN command\. These commands can be chained together into a single RUN statement to ensure that these unnecessary files aren't part of the final Docker image: 46 | 47 | ``` 48 | WORKDIR /tmp 49 | RUN wget http://example.com/software.tar.gz &&\ 50 | wget tar -xvf software.tar.gz &&\ 51 | mv software/binary /opt/bin/myapp &&\ 52 | rm software.tar.gz 53 | ``` 54 | 55 | Use the closest regional endpoint 56 | You can reduce latency in pulling images from Amazon ECR by ensuring that you are using the regional endpoint closest to where your application is running\. If your application is running on an Amazon EC2 instance, you can use the following shell code to obtain the region from the Availability Zone of the instance: 57 | 58 | ``` 59 | REGION=$(curl -s http://169.254.169.254/latest/meta-data/placement/availability-zone |\ 60 | sed -n 's/\(\d*\)[a-zA-Z]*$/\1/p') 61 | ``` 62 | The region can be passed to AWS CLI commands using the \-\-region parameter, or set as the default region for a profile using the aws configure command\. You can also set the region when making calls using the AWS SDK\. For more information, see the documentation for the SDK for your specific programming language\. -------------------------------------------------------------------------------- /doc_source/common-errors-docker.md: -------------------------------------------------------------------------------- 1 | # Troubleshooting errors with Docker commands when using Amazon ECR 2 | 3 | **Topics** 4 | + [Error: "Filesystem Verification Failed" or "404: Image Not Found" when pulling an image from an Amazon ECR repository](#error-filesystem-verification-failed) 5 | + [Error: "Filesystem Layer Verification Failed" when pulling images from Amazon ECR](#error-filesystem-layer-verification) 6 | + [HTTP 403 Errors or "no basic auth credentials" error when pushing to repository](#error-403) 7 | 8 | In some cases, running a Docker command against Amazon ECR may result in an error message\. Some common error messages and potential solutions are explained below\. 9 | 10 | ## Error: "Filesystem Verification Failed" or "404: Image Not Found" when pulling an image from an Amazon ECR repository 11 | 12 | You may receive the error `Filesystem verification failed` when using the docker pull command to pull an image from an Amazon ECR repository with Docker 1\.9 or above\. You may receive the error `404: Image not found` when you are using Docker versions before 1\.9\. 13 | 14 | Some possible reasons and their explanations are given below\. 15 | 16 | The local disk is full 17 | If the local disk on which you're running docker pull is full, then the SHA\-1 hash calculated on the local file may be different than the one calculated by Amazon ECR\. Check that your local disk has enough remaining free space to store the Docker image you are pulling\. You can also delete old images to make room for new ones\. Use the docker images command to see a list of all locally downloaded Docker images, along with their sizes\. 18 | 19 | Client cannot connect to the remote repository due to network error 20 | Calls to an Amazon ECR repository require a functioning connection to the internet\. Verify your network settings, and verify that other tools and applications can access resources on the internet\. If you are running docker pull on an Amazon EC2 instance in a private subnet, verify that the subnet has a route to the internet\. Use a network address translation \(NAT\) server or a managed NAT gateway\. 21 | Currently, calls to an Amazon ECR repository also require network access through your corporate firewall to Amazon Simple Storage Service \(Amazon S3\)\. If your organization uses firewall software or a NAT device that allows service endpoints, ensure that the Amazon S3 service endpoints for your current Region are allowed\. 22 | If you are using Docker behind an HTTP proxy, you can configure Docker with the appropriate proxy settings\. For more information, see [HTTP proxy](https://docs.docker.com/engine/admin/systemd/#/http-proxy) in the Docker documentation\. 23 | 24 | ## Error: "Filesystem Layer Verification Failed" when pulling images from Amazon ECR 25 | 26 | You may receive the error `image image-name not found` when pulling images using the docker pull command\. If you inspect the Docker logs, you may see an error like the following: 27 | 28 | ``` 29 | filesystem layer verification failed for digest sha256:2b96f... 30 | ``` 31 | 32 | This error indicates that one or more of the layers for your image has failed to download\. Some possible reasons and their explanations are given below\. 33 | 34 | You are using an older version of Docker 35 | This error can occur in a small percentage of cases when using a Docker version less than 1\.10\. Upgrade your Docker client to 1\.10 or greater\. 36 | 37 | Your client has encountered a network or disk error 38 | A full disk or a network issue may prevent one or more layers from downloading, as discussed earlier about the `Filesystem verification failed` message\. Follow the recommendations above to ensure that your filesystem is not full, and that you have enabled access to Amazon S3 from within your network\. 39 | 40 | ## HTTP 403 Errors or "no basic auth credentials" error when pushing to repository 41 | 42 | There are times when you may receive an `HTTP 403 (Forbidden)` error, or the error message `no basic auth credentials` from the docker push or docker pull commands, even if you have successfully authenticated to Docker using the aws ecr get\-login\-password command\. The following are some known causes of this issue: 43 | 44 | You have authenticated to a different region 45 | Authentication requests are tied to specific regions, and cannot be used across regions\. For example, if you obtain an authorization token from US West \(Oregon\), you cannot use it to authenticate against your repositories in US East \(N\. Virginia\)\. To resolve the issue, ensure that you have retrieved an authentication token from the same Region your repository exists in\. 46 | 47 | You have authenticated to push to a repository you don't have permissions for 48 | You do not have the necessary permissions to push to the repository\. For more information, see [Repository policies](repository-policies.md)\. 49 | 50 | Your token has expired 51 | The default authorization token expiration period for tokens obtained using the `GetAuthorizationToken` operation is 12 hours\. 52 | 53 | Bug in `wincred` credential manager 54 | Some versions of Docker for Windows use a credential manager called `wincred`, which does not properly handle the Docker login command produced by aws ecr get\-login\-password \(for more information, see [https://github\.com/docker/docker/issues/22910](https://github.com/docker/docker/issues/22910)\)\. You can run the Docker login command that is output, but when you try to push or pull images, those commands fail\. You can work around this bug by removing the `https://` scheme from the registry argument in the Docker login command that is output from aws ecr get\-login\-password\. An example Docker login command without the HTTPS scheme is shown below\. 55 | 56 | ``` 57 | docker login -u AWS -p .dkr.ecr..amazonaws.com 58 | ``` -------------------------------------------------------------------------------- /doc_source/using-service-linked-roles.md: -------------------------------------------------------------------------------- 1 | # Using service\-linked roles for Amazon ECR 2 | 3 | Amazon Elastic Container Registry \(Amazon ECR\) uses AWS Identity and Access Management \(IAM\)[ service\-linked roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html#iam-term-service-linked-role) to provide access to replicate resources\. A service\-linked role is a unique type of IAM role that is linked directly to Amazon ECR\. The service\-linked role is predefined by Amazon ECR\. It includes all of the permissions that the service requires to support cross\-Region and cross\-account image replication for your registry\. After you configure replication for your registry, an service\-linked role is created automatically on your behalf\. For more information, see [Private registry settings](registry-settings.md)\. />\. 4 | 5 | A service\-linked role makes setting up replication with Amazon ECR easier\. This is because, by using it, you don’t have to manually add all the necessary permissions\. Amazon ECR defines the permissions of its service\-linked roles, and unless defined otherwise, only Amazon ECR can assume its roles\. The defined permissions include the trust policy and the permissions policy,\. The permissions policy can't be attached to any other IAM entity\. 6 | 7 | You can delete the service\-linked role only after disabling replication on your registry\. This ensures that you don't inadvertently remove permission for Amazon ECR to replicate your images\. 8 | 9 | For information about other services that support service\-linked roles, see [AWS services that work with IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-services-that-work-with-iam.html)\. On this linked\-to page, look for the services that have **Yes **in the **Service\-linked role** column\. Choose a **Yes** with a link to view the relevant service\-linked role documentation for that service\. 10 | 11 | ## Service\-linked role permissions for Amazon ECR 12 | 13 | Amazon ECR uses the service\-linked role named **AWSServiceRoleForECRReplication** – Allows Amazon ECR to replicate images across multiple accounts\.\. 14 | 15 | The AWSServiceRoleForECRReplication service\-linked role trusts the following services to assume the role: 16 | + `replication.ecr.amazonaws.com` 17 | 18 | The role permissions policy allows Amazon ECR to use the following actions on resources: 19 | 20 | ``` 21 | { 22 | "Version": "2012-10-17", 23 | "Statement": [ 24 | { 25 | "Effect": "Allow", 26 | "Action": [ 27 | "ecr:CreateRepository", 28 | "ecr:ReplicateImage" 29 | ], 30 | "Resource": "*" 31 | } 32 | ] 33 | } 34 | ``` 35 | 36 | **Note** 37 | The `ReplicateImage` is an internal API that Amazon ECR uses for replication and can't be called directly\. 38 | 39 | You must configure permissions to allow an IAM entity \(for example a user, group, or role\) to create, edit, or delete a service\-linked role\. For more information, see [Service\-Linked Role Permissions](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#service-linked-role-permissions) in the *IAM User Guide*\. 40 | 41 | ## Creating a service\-linked role for Amazon ECR 42 | 43 | You don't need to manually create the Amazon ECR service\-linked role\. When you configure replication settings for your registry in the AWS Management Console, the AWS CLI, or the AWS API, Amazon ECR creates the service\-linked role for you\. 44 | 45 | If you delete this service\-linked role and need to create it again, you can use the same process to recreate the role in your account\. When you configure replication settings for your registry, Amazon ECR creates the service\-linked role for you again\. 46 | 47 | ## Editing a service\-linked role for Amazon ECR 48 | 49 | Amazon ECR doesn't allow manually editing the AWSServiceRoleForECRReplication service\-linked role\. After you create a service\-linked role, you can't change the name of the role because various entities might reference the role\. However, you can edit the description of the role using IAM\. For more information, see [Editing a service\-linked role](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#edit-service-linked-role) in the *IAM User Guide*\. 50 | 51 | ## Deleting the service\-linked role for Amazon ECR 52 | 53 | If you no longer need to use a feature or service that requires a service\-linked role, we recommend that you delete that role\. That way, you don’t have an unused entity that isn't actively monitored or maintained\. However, you must remove the replication configuration for your registry in every Region before you can manually delete the service\-linked role\. 54 | 55 | **Note** 56 | If you try to delete resources while the Amazon ECR service is still using the roles, your delete action might fail\. If that happens, wait for a few minutes and try again\. 57 | 58 | **To delete Amazon ECR resources used by the AWSServiceRoleForECRReplication** 59 | 60 | 1. Open the Amazon ECR console at [https://console\.aws\.amazon\.com/ecr/](https://console.aws.amazon.com/ecr/)\. 61 | 62 | 1. From the navigation bar, choose the Region your replication configuration is set on\. 63 | 64 | 1. In the navigation pane, choose **Registry settings**\. 65 | 66 | 1. Select both the **Cross\-Region replication** and **Cross\-account replication** settings\. 67 | 68 | 1. Choose **Save**\. 69 | 70 | **To manually delete the service\-linked role using IAM** 71 | 72 | Use the IAM console, the AWS CLI, or the AWS API to delete the AWSServiceRoleForECRReplication service\-linked role\. For more information, see [Deleting a Service\-Linked Role](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#delete-service-linked-role) in the *IAM User Guide*\. 73 | 74 | ## Supported Regions for Amazon ECR service\-linked roles 75 | 76 | Amazon ECR supports using service\-linked roles in all of the Regions where the service is available\. For more information, see [AWS Regions and Endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html)\. -------------------------------------------------------------------------------- /doc_source/security_iam_troubleshoot.md: -------------------------------------------------------------------------------- 1 | # Troubleshooting Amazon Elastic Container Registry Identity and Access 2 | 3 | Use the following information to help you diagnose and fix common issues that you might encounter when working with Amazon ECR and IAM\. 4 | 5 | **Topics** 6 | + [I Am Not Authorized to Perform an Action in Amazon ECR](#security_iam_troubleshoot-no-permissions) 7 | + [I Am Not Authorized to Perform iam:PassRole](#security_iam_troubleshoot-passrole) 8 | + [I Want to View My Access Keys](#security_iam_troubleshoot-access-keys) 9 | + [I'm an Administrator and Want to Allow Others to Access Amazon ECR](#security_iam_troubleshoot-admin-delegate) 10 | + [I Want to Allow People Outside of My AWS Account to Access My Amazon ECR Resources](#security_iam_troubleshoot-cross-account-access) 11 | 12 | ## I Am Not Authorized to Perform an Action in Amazon ECR 13 | 14 | If the AWS Management Console tells you that you're not authorized to perform an action, then you must contact your administrator for assistance\. Your administrator is the person that provided you with your user name and password\. 15 | 16 | The following example error occurs when the `mateojackson` IAM user tries to use the console to view details about a repository but does not have `ecr:DescribeRepositories` permissions\. 17 | 18 | ``` 19 | User: arn:aws:iam::123456789012:user/mateojackson is not authorized to perform: ecr:DescribeRepositories on resource: my-repo 20 | ``` 21 | 22 | In this case, Mateo asks his administrator to update his policies to allow him to access the `my-repo` resource using the `ecr:DescribeRepositories` action\. 23 | 24 | ## I Am Not Authorized to Perform iam:PassRole 25 | 26 | If you receive an error that you're not authorized to perform the `iam:PassRole` action, then you must contact your administrator for assistance\. Your administrator is the person that provided you with your user name and password\. Ask that person to update your policies to allow you to pass a role to Amazon ECR\. 27 | 28 | Some AWS services allow you to pass an existing role to that service, instead of creating a new service role or service\-linked role\. To do this, you must have permissions to pass the role to the service\. 29 | 30 | The following example error occurs when an IAM user named `marymajor` tries to use the console to perform an action in Amazon ECR\. However, the action requires the service to have permissions granted by a service role\. Mary does not have permissions to pass the role to the service\. 31 | 32 | ``` 33 | User: arn:aws:iam::123456789012:user/marymajor is not authorized to perform: iam:PassRole 34 | ``` 35 | 36 | In this case, Mary asks her administrator to update her policies to allow her to perform the `iam:PassRole` action\. 37 | 38 | ## I Want to View My Access Keys 39 | 40 | After you create your IAM user access keys, you can view your access key ID at any time\. However, you can't view your secret access key again\. If you lose your secret key, you must create a new access key pair\. 41 | 42 | Access keys consist of two parts: an access key ID \(for example, `AKIAIOSFODNN7EXAMPLE`\) and a secret access key \(for example, `wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY`\)\. Like a user name and password, you must use both the access key ID and secret access key together to authenticate your requests\. Manage your access keys as securely as you do your user name and password\. 43 | 44 | **Important** 45 | Do not provide your access keys to a third party, even to help [find your canonical user ID](https://docs.aws.amazon.com/general/latest/gr/acct-identifiers.html#FindingCanonicalId)\. By doing this, you might give someone permanent access to your account\. 46 | 47 | When you create an access key pair, you are prompted to save the access key ID and secret access key in a secure location\. The secret access key is available only at the time you create it\. If you lose your secret access key, you must add new access keys to your IAM user\. You can have a maximum of two access keys\. If you already have two, you must delete one key pair before creating a new one\. To view instructions, see [Managing access keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_CreateAccessKey) in the *IAM User Guide*\. 48 | 49 | ## I'm an Administrator and Want to Allow Others to Access Amazon ECR 50 | 51 | To allow others to access Amazon ECR, you must create an IAM entity \(user or role\) for the person or application that needs access\. They will use the credentials for that entity to access AWS\. You must then attach a policy to the entity that grants them the correct permissions in Amazon ECR\. 52 | 53 | To get started right away, see [Creating your first IAM delegated user and group](https://docs.aws.amazon.com/IAM/latest/UserGuide/getting-started_create-delegated-user.html) in the *IAM User Guide*\. 54 | 55 | ## I Want to Allow People Outside of My AWS Account to Access My Amazon ECR Resources 56 | 57 | You can create a role that users in other accounts or people outside of your organization can use to access your resources\. You can specify who is trusted to assume the role\. For services that support resource\-based policies or access control lists \(ACLs\), you can use those policies to grant people access to your resources\. 58 | 59 | To learn more, consult the following: 60 | + To learn whether Amazon ECR supports these features, see [How Amazon Elastic Container Registry Works with IAM](security_iam_service-with-iam.md)\. 61 | + To learn how to provide access to your resources across AWS accounts that you own, see [Providing access to an IAM user in another AWS account that you own](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_aws-accounts.html) in the *IAM User Guide*\. 62 | + To learn how to provide access to your resources to third\-party AWS accounts, see [Providing access to AWS accounts owned by third parties](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_third-party.html) in the *IAM User Guide*\. 63 | + To learn how to provide access through identity federation, see [Providing access to externally authenticated users \(identity federation\)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_federated-users.html) in the *IAM User Guide*\. 64 | + To learn the difference between using roles and resource\-based policies for cross\-account access, see [How IAM roles differ from resource\-based policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_compare-resource-policies.html) in the *IAM User Guide*\. -------------------------------------------------------------------------------- /doc_source/get-set-up-for-amazon-ecr.md: -------------------------------------------------------------------------------- 1 | # Setting up with Amazon ECR 2 | 3 | If you've signed up for AWS and have been using Amazon Elastic Container Service \(Amazon ECS\) or Amazon Elastic Kubernetes Service \(Amazon EKS\), you are close to being able to use Amazon ECR\. The setup process for these two services is similar, as Amazon ECR is an extension to these services\. To use the AWS CLI with Amazon ECR, you must use a version of the AWS CLI that supports the latest Amazon ECR features\. If you do not see support for an Amazon ECR feature in the AWS CLI, you should upgrade to the latest version\. For more information, see [http://aws\.amazon\.com/cli/](http://aws.amazon.com/cli/)\. 4 | 5 | Complete the following tasks to get set up to push a container image to Amazon ECR for the first time\. If you have already completed any of these steps, you may skip them and move on to the next step\. 6 | 7 | ## Sign up for AWS 8 | 9 | When you sign up for AWS, your AWS account is automatically signed up for all services, including Amazon ECR\. You are charged only for the services that you use\. 10 | 11 | If you have an AWS account already, skip to the next task\. If you don't have an AWS account, use the following procedure to create one\. 12 | 13 | **To create an AWS account** 14 | 15 | 1. Open [https://portal\.aws\.amazon\.com/billing/signup](https://portal.aws.amazon.com/billing/signup)\. 16 | 17 | 1. Follow the online instructions\. 18 | 19 | Part of the sign\-up procedure involves receiving a phone call and entering a verification code on the phone keypad\. 20 | 21 | Note your AWS account number, because you'll need it for the next task\. 22 | 23 | ## Create an IAM user 24 | 25 | Services in AWS, such as Amazon ECR, require that you provide credentials when you access them, so that the service can determine whether you have permission to access its resources\. The console requires your password\. You can create access keys for your AWS account to access the command line interface or API\. However, we don't recommend that you access AWS using the credentials for your AWS account; we recommend that you use AWS Identity and Access Management \(IAM\) instead\. Create an IAM user, and then add the user to an IAM group with administrative permissions or grant this user administrative permissions\. You can then access AWS using a special URL and the credentials for the IAM user\. 26 | 27 | If you signed up for AWS but have not created an IAM user for yourself, you can create one using the IAM console\. 28 | 29 | **To create an administrator user for yourself and add the user to an administrators group \(console\)** 30 | 31 | 1. Sign in to the [IAM console](https://console.aws.amazon.com/iam/) as the account owner by choosing **Root user** and entering your AWS account email address\. On the next page, enter your password\. 32 | **Note** 33 | We strongly recommend that you adhere to the best practice of using the **Administrator** IAM user that follows and securely lock away the root user credentials\. Sign in as the root user only to perform a few [account and service management tasks](https://docs.aws.amazon.com/general/latest/gr/aws_tasks-that-require-root.html)\. 34 | 35 | 1. In the navigation pane, choose **Users** and then choose **Add user**\. 36 | 37 | 1. For **User name**, enter **Administrator**\. 38 | 39 | 1. Select the check box next to **AWS Management Console access**\. Then select **Custom password**, and then enter your new password in the text box\. 40 | 41 | 1. \(Optional\) By default, AWS requires the new user to create a new password when first signing in\. You can clear the check box next to **User must create a new password at next sign\-in** to allow the new user to reset their password after they sign in\. 42 | 43 | 1. Choose **Next: Permissions**\. 44 | 45 | 1. Under **Set permissions**, choose **Add user to group**\. 46 | 47 | 1. Choose **Create group**\. 48 | 49 | 1. In the **Create group** dialog box, for **Group name** enter **Administrators**\. 50 | 51 | 1. Choose **Filter policies**, and then select **AWS managed \- job function** to filter the table contents\. 52 | 53 | 1. In the policy list, select the check box for **AdministratorAccess**\. Then choose **Create group**\. 54 | **Note** 55 | You must activate IAM user and role access to Billing before you can use the `AdministratorAccess` permissions to access the AWS Billing and Cost Management console\. To do this, follow the instructions in [step 1 of the tutorial about delegating access to the billing console](https://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_billing.html)\. 56 | 57 | 1. Back in the list of groups, select the check box for your new group\. Choose **Refresh** if necessary to see the group in the list\. 58 | 59 | 1. Choose **Next: Tags**\. 60 | 61 | 1. \(Optional\) Add metadata to the user by attaching tags as key\-value pairs\. For more information about using tags in IAM, see [Tagging IAM entities](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_tags.html) in the *IAM User Guide*\. 62 | 63 | 1. Choose **Next: Review** to see the list of group memberships to be added to the new user\. When you are ready to proceed, choose **Create user**\. 64 | 65 | You can use this same process to create more groups and users and to give your users access to your AWS account resources\. To learn about using policies that restrict user permissions to specific AWS resources, see [Access management](https://docs.aws.amazon.com/IAM/latest/UserGuide/access.html) and [Example policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_examples.html)\. 66 | 67 | To sign in as this new IAM user, sign out of the AWS console, then use the following URL, where *your\_aws\_account\_id* is your AWS account number without the hyphens \(for example, if your AWS account number is `1234-5678-9012`, your AWS account ID is `123456789012`\): 68 | 69 | ``` 70 | https://your_aws_account_id.signin.aws.amazon.com/console/ 71 | ``` 72 | 73 | Enter the IAM user name and password that you just created\. When you're signed in, the navigation bar displays "*your\_user\_name* @ *your\_aws\_account\_id*"\. 74 | 75 | If you don't want the URL for your sign\-in page to contain your AWS account ID, you can create an account alias\. From the IAM dashboard, choose **Customize** and enter an **Account Alias**, such as your company name\. For more information, see [Your AWS account ID and its alias](https://docs.aws.amazon.com/IAM/latest/UserGuide/console_account-alias.html) in the *IAM User Guide*\. 76 | 77 | To sign in after you create an account alias, use the following URL: 78 | 79 | ``` 80 | https://your_account_alias.signin.aws.amazon.com/console/ 81 | ``` 82 | 83 | To verify the sign\-in link for IAM users for your account, open the IAM console and check under **IAM users sign\-in link** on the dashboard\. 84 | 85 | For more information about IAM, see the [AWS Identity and Access Management User Guide](https://docs.aws.amazon.com/IAM/latest/UserGuide/)\. -------------------------------------------------------------------------------- /doc_source/LifecyclePolicies.md: -------------------------------------------------------------------------------- 1 | # Lifecycle policies 2 | 3 | Amazon ECR lifecycle policies enable you to specify the lifecycle management of images in a repository\. A lifecycle policy is a set of one or more rules, where each rule defines an action for Amazon ECR\. The actions apply to images that contain tags prefixed with the given strings\. This allows the automation of cleaning up unused images, for example expiring images based on age or count\. You should expect that after creating a lifecycle policy the affected images are expired within 24 hours\. 4 | 5 | **Topics** 6 | + [Lifecycle policy template](#lifecycle_policy_syntax) 7 | + [Lifecycle policy parameters](#lifecycle_policy_parameters) 8 | + [Lifecycle policy evaluation rules](#lp_evaluation_rules) 9 | + [Creating a lifecycle policy preview](lpp_creation.md) 10 | + [Creating a lifecycle policy](lp_creation.md) 11 | + [Examples of lifecycle policies](lifecycle_policy_examples.md) 12 | 13 | ## Lifecycle policy template 14 | 15 | The contents of your lifecycle policy is evaluated before being associated with a repository\. The following is the JSON syntax template for the lifecycle policy\. For lifecycle policy examples, see [Examples of lifecycle policies](lifecycle_policy_examples.md)\. 16 | 17 | ``` 18 | { 19 | "rules": [ 20 | { 21 | "rulePriority": integer, 22 | "description": "string", 23 | "selection": { 24 | "tagStatus": "tagged"|"untagged"|"any", 25 | "tagPrefixList": list, 26 | "countType": "imageCountMoreThan"|"sinceImagePushed", 27 | "countUnit": "string", 28 | "countNumber": integer 29 | }, 30 | "action": { 31 | "type": "expire" 32 | } 33 | } 34 | ] 35 | } 36 | ``` 37 | 38 | **Note** 39 | The `tagPrefixList` parameter is only used if `tagStatus` is `tagged`\. The `countUnit` parameter is only used if `countType` is `sinceImagePushed`\. The `countNumber` parameter is only used if `countType` is set to `imageCountMoreThan`\. 40 | 41 | ## Lifecycle policy parameters 42 | 43 | Lifecycle policies are split into the following parts: 44 | 45 | **Topics** 46 | + [Rule priority](#lp_rule_priority) 47 | + [Description](#lp_description) 48 | + [Tag status](#lp_tag_status) 49 | + [Tag prefix list](#lp_tag_prefix_list) 50 | + [Count type](#lp_count_type) 51 | + [Count unit](#lp_count_unit) 52 | + [Count number](#lp_count_number) 53 | + [Action](#lp_action) 54 | 55 | ### Rule priority 56 | 57 | `rulePriority` 58 | Type: integer 59 | Required: yes 60 | Sets the order in which rules are evaluated, lowest to highest\. A lifecycle policy rule with a priority of `1` will be acted upon first, a rule with priority of `2` will be next, and so on\. When you add rules to a lifecycle policy, you must give them each a unique value for `rulePriority`\. Values do not need to be sequential across rules in a policy\. A rule with a `tagStatus` value of `any` must have the highest value for `rulePriority` and be evaluated last\. 61 | 62 | ### Description 63 | 64 | `description` 65 | Type: string 66 | Required: no 67 | \(Optional\) Describes the purpose of a rule within a lifecycle policy\. 68 | 69 | ### Tag status 70 | 71 | `tagStatus` 72 | Type: string 73 | Required: yes 74 | Determines whether the lifecycle policy rule that you are adding specifies a tag for an image\. Acceptable options are `tagged`, `untagged`, or `any`\. If you specify `any`, then all images have the rule applied to them\. If you specify `tagged`, then you must also specify a `tagPrefixList` value\. If you specify `untagged`, then you must omit `tagPrefixList`\. 75 | 76 | ### Tag prefix list 77 | 78 | `tagPrefixList` 79 | Type: list\[string\] 80 | Required: yes, only if `tagStatus` is set to tagged 81 | Only used if you specified `"tagStatus": "tagged"`\. You must specify a comma\-separated list of image tag prefixes on which to take action with your lifecycle policy\. For example, if your images are tagged as `prod`, `prod1`, `prod2`, and so on, you would use the tag prefix `prod` to specify all of them\. If you specify multiple tags, only the images with all specified tags are selected\. 82 | 83 | ### Count type 84 | 85 | `countType` 86 | Type: string 87 | Required: yes 88 | Specify a count type to apply to the images\. 89 | If `countType` is set to `imageCountMoreThan`, you also specify `countNumber` to create a rule that sets a limit on the number of images that exist in your repository\. If `countType` is set to `sinceImagePushed`, you also specify `countUnit` and `countNumber` to specify a time limit on the images that exist in your repository\. 90 | 91 | ### Count unit 92 | 93 | `countUnit` 94 | Type: string 95 | Required: yes, only if `countType` is set to `sinceImagePushed` 96 | Specify a count unit of `days` to indicate that as the unit of time, in addition to `countNumber`, which is the number of days\. 97 | This should only be specified when `countType` is `sinceImagePushed`; an error will occur if you specify a count unit when `countType` is any other value\. 98 | 99 | ### Count number 100 | 101 | `countNumber` 102 | Type: integer 103 | Required: yes 104 | Specify a count number\. Acceptable values are positive integers \(`0` is not an accepted value\)\. 105 | If the `countType` used is `imageCountMoreThan`, then the value is the maximum number of images that you want to retain in your repository\. If the `countType` used is `sinceImagePushed`, then the value is the maximum age limit for your images\. 106 | 107 | ### Action 108 | 109 | `type` 110 | Type: string 111 | Required: yes 112 | Specify an action type\. The supported value is `expire`\. 113 | 114 | ## Lifecycle policy evaluation rules 115 | 116 | The lifecycle policy evaluator is responsible for parsing the plaintext JSON and applying it to the images in the specified repository\. The following rules should be noted when creating a lifecycle policy: 117 | + An image is expired by exactly one or zero rules\. 118 | + An image that matches the tagging requirements of a rule cannot be expired by a rule with a lower priority\. 119 | + Rules can never mark images that are marked by higher priority rules, but can still identify them as if they haven't been expired\. 120 | + The set of rules must contain a unique set of tag prefixes\. 121 | + Only one rule is allowed to select untagged images\. 122 | + Expiration is always ordered by `pushed_at_time`, and always expires older images before newer ones\. 123 | + When using the `tagPrefixList`, an image is successfully matched if *all* of the tags in the `tagPrefixList` value are matched against any of the image's tags\. 124 | + With `countType = imageCountMoreThan`, images are sorted from youngest to oldest based on `pushed_at_time` and then all images greater than the specified count are expired\. 125 | + With `countType = sinceImagePushed`, all images whose `pushed_at_time` is older than the specified number of days based on `countNumber` are expired\. -------------------------------------------------------------------------------- /doc_source/repository-policy-examples.md: -------------------------------------------------------------------------------- 1 | # Repository policy examples 2 | 3 | The following examples show policy statements that you could use to control the permissions that users have to Amazon ECR repositories\. 4 | 5 | **Important** 6 | Amazon ECR requires that users have permission to make calls to the `ecr:GetAuthorizationToken` API through an IAM policy before they can authenticate to a registry and push or pull any images from any Amazon ECR repository\. Amazon ECR provides several managed IAM policies to control user access at varying levels; for more information, see [Amazon Elastic Container Registry Identity\-Based Policy Examples](security_iam_id-based-policy-examples.md)\. 7 | 8 | ## Example: Allow an IAM user within your account 9 | 10 | The following repository policy allows IAM users within your account to push and pull images\. 11 | 12 | ``` 13 | { 14 | "Version": "2008-10-17", 15 | "Statement": [ 16 | { 17 | "Sid": "AllowPushPull", 18 | "Effect": "Allow", 19 | "Principal": { 20 | "AWS": [ 21 | "arn:aws:iam::account-id:user/push-pull-user-1", 22 | "arn:aws:iam::account-id:user/push-pull-user-2" 23 | ] 24 | }, 25 | "Action": [ 26 | "ecr:BatchGetImage", 27 | "ecr:BatchCheckLayerAvailability", 28 | "ecr:CompleteLayerUpload", 29 | "ecr:GetDownloadUrlForLayer", 30 | "ecr:InitiateLayerUpload", 31 | "ecr:PutImage", 32 | "ecr:UploadLayerPart" 33 | ] 34 | } 35 | ] 36 | } 37 | ``` 38 | 39 | ## Example: Allow another account 40 | 41 | The following repository policy allows a specific account to push images\. 42 | 43 | ``` 44 | { 45 | "Version": "2008-10-17", 46 | "Statement": [ 47 | { 48 | "Sid": "AllowCrossAccountPush", 49 | "Effect": "Allow", 50 | "Principal": { 51 | "AWS": "arn:aws:iam::account-id:root" 52 | }, 53 | "Action": [ 54 | "ecr:BatchCheckLayerAvailability", 55 | "ecr:CompleteLayerUpload", 56 | "ecr:InitiateLayerUpload", 57 | "ecr:PutImage", 58 | "ecr:UploadLayerPart" 59 | ] 60 | } 61 | ] 62 | } 63 | ``` 64 | 65 | The following repository policy allows some IAM users to pull images \(*pull\-user\-1* and *pull\-user\-2*\) while providing full access to another \(*admin\-user*\)\. 66 | 67 | **Note** 68 | For more complicated repository policies that are not currently supported in the AWS Management Console, you can apply the policy with the [https://docs.aws.amazon.com/cli/latest/reference/ecr/set-repository-policy.html](https://docs.aws.amazon.com/cli/latest/reference/ecr/set-repository-policy.html) AWS CLI command\. 69 | 70 | ``` 71 | { 72 | "Version": "2008-10-17", 73 | "Statement": [ 74 | { 75 | "Sid": "AllowPull", 76 | "Effect": "Allow", 77 | "Principal": { 78 | "AWS": [ 79 | "arn:aws:iam::account-id:user/pull-user-1", 80 | "arn:aws:iam::account-id:user/pull-user-2" 81 | ] 82 | }, 83 | "Action": [ 84 | "ecr:BatchGetImage", 85 | "ecr:GetDownloadUrlForLayer" 86 | ] 87 | }, 88 | { 89 | "Sid": "AllowAll", 90 | "Effect": "Allow", 91 | "Principal": { 92 | "AWS": "arn:aws:iam::account-id:user/admin-user" 93 | }, 94 | "Action": [ 95 | "ecr:*" 96 | ] 97 | } 98 | ] 99 | } 100 | ``` 101 | 102 | ## Example: Allow all AWS accounts to pull images 103 | 104 | The following repository policy allows all AWS accounts to pull images\. 105 | 106 | ``` 107 | { 108 | "Version": "2008-10-17", 109 | "Statement": [ 110 | { 111 | "Sid": "AllowPull", 112 | "Effect": "Allow", 113 | "Principal": "*", 114 | "Action": [ 115 | "ecr:BatchGetImage", 116 | "ecr:GetDownloadUrlForLayer" 117 | ] 118 | } 119 | ] 120 | } 121 | ``` 122 | 123 | ## Example: Deny all 124 | 125 | The following repository policy denies all users the ability to pull images\. 126 | 127 | ``` 128 | { 129 | "Version": "2008-10-17", 130 | "Statement": [ 131 | { 132 | "Sid": "DenyPull", 133 | "Effect": "Deny", 134 | "Principal": "*", 135 | "Action": [ 136 | "ecr:BatchGetImage", 137 | "ecr:GetDownloadUrlForLayer" 138 | ] 139 | } 140 | ] 141 | } 142 | ``` 143 | 144 | ## Example: Restricting access to specific IP addresses 145 | 146 | The following example grants permissions to any user to perform any Amazon ECR operations when applied to a repository\. However, the request must originate from the range of IP addresses specified in the condition\. 147 | 148 | The condition in this statement identifies the `54.240.143.*` range of allowed Internet Protocol version 4 \(IPv4\) IP addresses, with one exception: `54.240.143.188`\. 149 | 150 | The `Condition` block uses the `IpAddress` and `NotIpAddress` conditions and the `aws:SourceIp` condition key, which is an AWS\-wide condition key\. For more information about these condition keys, see [AWS Global Condition Context Keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html)\. The`aws:sourceIp` IPv4 values use the standard CIDR notation\. For more information, see [IP Address Condition Operators](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html#Conditions_IPAddress) in the *IAM User Guide*\. 151 | 152 | ``` 153 | { 154 | "Version": "2012-10-17", 155 | "Id": "ECRPolicyId1", 156 | "Statement": [ 157 | { 158 | "Sid": "IPAllow", 159 | "Effect": "Allow", 160 | "Principal": "*", 161 | "Action": "ecr:*", 162 | "Condition": { 163 | "NotIpAddress": { 164 | "aws:SourceIp": "54.240.143.188/32" 165 | }, 166 | "IpAddress": { 167 | "aws:SourceIp": "54.240.143.0/24" 168 | } 169 | } 170 | } 171 | ] 172 | } 173 | ``` 174 | 175 | ## Example: Service\-linked role 176 | 177 | The following repository policy allows AWS CodeBuild access to the Amazon ECR API actions necessary for integration with that service\. For more information, see [Amazon ECR Sample for CodeBuild](https://docs.aws.amazon.com/codebuild/latest/userguide/sample-ecr.html) in the *AWS CodeBuild User Guide*\. 178 | 179 | ``` 180 | { 181 | "Version": "2012-10-17", 182 | "Statement": [ 183 | { 184 | "Sid": "CodeBuildAccess", 185 | "Effect": "Allow", 186 | "Principal": { 187 | "Service": "codebuild.amazonaws.com" 188 | }, 189 | "Action": [ 190 | "ecr:BatchGetImage", 191 | "ecr:GetDownloadUrlForLayer" 192 | ] 193 | } 194 | ] 195 | } 196 | ``` -------------------------------------------------------------------------------- /doc_source/registry_auth.md: -------------------------------------------------------------------------------- 1 | # Private registry authentication 2 | 3 | You can use the AWS Management Console, the AWS CLI, or the AWS SDKs to create and manage private repositories\. You can also use those methods to perform some actions on images, such as listing or deleting them\. These clients use standard AWS authentication methods\. Even though you can use the Amazon ECR API to push and pull images, you're more likely to use the Docker CLI or a language\-specific Docker library\. 4 | 5 | The Docker CLI doesn't support native IAM authentication methods\. Additional steps must be taken so that Amazon ECR can authenticate and authorize Docker push and pull requests\. 6 | 7 | The registry authentication methods that are detailed in the following sections are available\. 8 | 9 | ## Using the Amazon ECR credential helper 10 | 11 | Amazon ECR provides a Docker credential helper which makes it easier to store and use Docker credentials when pushing and pulling images to Amazon ECR\. For installation and configuration steps, see [Amazon ECR Docker Credential Helper](https://github.com/awslabs/amazon-ecr-credential-helper)\. 12 | 13 | ## Using an authorization token 14 | 15 | An authorization token's permission scope matches that of the IAM principal used to retrieve the authentication token\. An authentication token is used to access any Amazon ECR registry that your IAM principal has access to and is valid for 12 hours\. To obtain an authorization token, you must use the [GetAuthorizationToken](https://docs.aws.amazon.com/AmazonECR/latest/APIReference/API_GetAuthorizationToken.html) API operation to retrieve a base64\-encoded authorization token containing the username `AWS` and an encoded password\. The AWS CLI `get-login-password` command simplifies this by retrieving and decoding the authorization token which you can then pipe into a docker login command to authenticate\. 16 | 17 | ### To authenticate Docker to an Amazon ECR private registry with get\-login\-password 18 | 19 | The `get-login-password` is the preferred method for authenticating to an Amazon ECR private registry when using the AWS CLI\. Ensure that you have configured your AWS CLI to interact with AWS\. For more information, see [AWS CLI configuration basics](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) in the *AWS Command Line Interface User Guide*\. 20 | 21 | When passing the Amazon ECR authorization token to the docker login command, use the value `AWS` for the username and specify the Amazon ECR registry URI you want to authenticate to\. If authenticating to multiple registries, you must repeat the command for each registry\. 22 | **Important** 23 | If you receive an error, install or upgrade to the latest version of the AWS CLI\. For more information, see [Installing the AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) in the *AWS Command Line Interface User Guide*\. 24 | + [get\-login\-password](https://docs.aws.amazon.com/cli/latest/reference/ecr/get-login-password.html) \(AWS CLI\) 25 | 26 | ``` 27 | aws ecr get-login-password --region region | docker login --username AWS --password-stdin .dkr.ecr.region.amazonaws.com 28 | ``` 29 | + [Get\-ECRLoginCommand](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-ECRLoginCommand.html) \(AWS Tools for Windows PowerShell\) 30 | 31 | ``` 32 | (Get-ECRLoginCommand).Password | docker login --username AWS --password-stdin .dkr.ecr.region.amazonaws.com 33 | ``` 34 | 35 | ### To authenticate Docker to an Amazon ECR private registry with get\-login 36 | 37 | The `get-login` command is the legacy method for authenticating to an Amazon ECR private registry and is a less secure method\. This command was the only method available for AWS CLI versions prior to `1.17.10`\. We recommend you update your AWS CLI to the latest version and use the `get-login-password` command to authenticate\. You can check your AWS CLI version with the `aws --version` command\. 38 | 39 | For legacy purposes, the following are the steps to authenticate using `get-login`\. Ensure that you have configured your AWS CLI to interact with AWS\. For more information, see [AWS CLI configuration basics](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) in the *AWS Command Line Interface User Guide*\. 40 | 41 | **To authenticate using get\-login \(AWS CLI\)** 42 | 43 | 1. Run the `aws ecr get-login` command\. The example below is for the default registry associated with the account making the request\. To access other account registries, use the `--registry-ids ` option\. For more information, see [get\-login](https://docs.aws.amazon.com/cli/latest/reference/ecr/get-login.html) in the *AWS CLI Command Reference*\. 44 | 45 | ``` 46 | aws ecr get-login --region region --no-include-email 47 | ``` 48 | 49 | The resulting output is a `docker login` command that you use to authenticate your Docker client to your Amazon ECR registry\. 50 | 51 | ``` 52 | docker login -u AWS -p password https://.dkr.ecr.region.amazonaws.com 53 | ``` 54 | 55 | 1. Copy and paste the docker login command into a terminal to authenticate your Docker CLI to the registry\. This command provides an authorization token that is valid for the specified registry for 12 hours\. 56 | **Note** 57 | If you are using Windows PowerShell, copying and pasting long strings like this does not work\. Use the following command instead\. 58 | 59 | ``` 60 | Invoke-Expression -Command (Get-ECRLoginCommand -Region region).Command 61 | ``` 62 | **Important** 63 | When you execute this docker login command, the command string can be visible to other users on your system in a process list \(ps \-e\) display\. Because the docker login command contains authentication credentials, there is a risk that other users on your system could view them this way\. They could use the credentials to gain push and pull access to your repositories\. If you are not on a secure system, you should use the ecr get\-login\-password command as described above\. 64 | 65 | ## Using HTTP API authentication 66 | 67 | Amazon ECR supports the [Docker Registry HTTP API](https://docs.docker.com/registry/spec/api/)\. However, because Amazon ECR is a private registry, you must provide an authorization token with every HTTP request\. You can add an HTTP authorization header using the `-H` option for curl and pass the authorization token provided by the get\-authorization\-token AWS CLI command\. 68 | 69 | **To authenticate with the Amazon ECR HTTP API** 70 | 71 | 1. Retrieve an authorization token with the AWS CLI and set it to an environment variable\. 72 | 73 | ``` 74 | TOKEN=$(aws ecr get-authorization-token --output text --query 'authorizationData[].authorizationToken') 75 | ``` 76 | 77 | 1. To authenticate to the API, pass the `$TOKEN` variable to the `-H` option of curl\. For example, the following command lists the image tags in an Amazon ECR repository\. For more information, see the [Docker Registry HTTP API](https://docs.docker.com/registry/spec/api/) reference documentation\. 78 | 79 | ``` 80 | curl -i -H "Authorization: Basic $TOKEN" https://aws_account_id.dkr.ecr.region.amazonaws.com/v2/amazonlinux/tags/list 81 | ``` 82 | 83 | The output is as follows: 84 | 85 | ``` 86 | HTTP/1.1 200 OK 87 | Content-Type: text/plain; charset=utf-8 88 | Date: Thu, 04 Jan 2018 16:06:59 GMT 89 | Docker-Distribution-Api-Version: registry/2.0 90 | Content-Length: 50 91 | Connection: keep-alive 92 | 93 | {"name":"amazonlinux","tags":["2017.09","latest"]} 94 | ``` -------------------------------------------------------------------------------- /doc_source/security_iam_id-based-policy-examples.md: -------------------------------------------------------------------------------- 1 | # Amazon Elastic Container Registry Identity\-Based Policy Examples 2 | 3 | By default, IAM users and roles don't have permission to create or modify Amazon ECR resources\. They also can't perform tasks using the AWS Management Console, AWS CLI, or AWS API\. An IAM administrator must create IAM policies that grant users and roles permission to perform specific API operations on the specified resources they need\. The administrator must then attach those policies to the IAM users or groups that require those permissions\. 4 | 5 | To learn how to create an IAM identity\-based policy using these example JSON policy documents, see [Creating Policies on the JSON Tab](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-json-editor) in the *IAM User Guide*\. 6 | 7 | **Topics** 8 | + [Policy Best Practices](#security_iam_service-with-iam-policy-best-practices) 9 | + [Using the Amazon ECR Console](#security_iam_id-based-policy-examples-console) 10 | + [Allow Users to View Their Own Permissions](#security_iam_id-based-policy-examples-view-own-permissions) 11 | + [Accessing One Amazon ECR Repository](#security_iam_id-based-policy-examples-access-one-bucket) 12 | 13 | ## Policy Best Practices 14 | 15 | Identity\-based policies are very powerful\. They determine whether someone can create, access, or delete Amazon ECR resources in your account\. These actions can incur costs for your AWS account\. When you create or edit identity\-based policies, follow these guidelines and recommendations: 16 | + **Get started using AWS managed policies** – To start using Amazon ECR quickly, use AWS managed policies to give your employees the permissions they need\. These policies are already available in your account and are maintained and updated by AWS\. For more information, see [Get started using permissions with AWS managed policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#bp-use-aws-defined-policies) in the *IAM User Guide*\. 17 | + **Grant least privilege** – When you create custom policies, grant only the permissions required to perform a task\. Start with a minimum set of permissions and grant additional permissions as necessary\. Doing so is more secure than starting with permissions that are too lenient and then trying to tighten them later\. For more information, see [Grant least privilege](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege) in the *IAM User Guide*\. 18 | + **Enable MFA for sensitive operations** – For extra security, require IAM users to use multi\-factor authentication \(MFA\) to access sensitive resources or API operations\. For more information, see [Using multi\-factor authentication \(MFA\) in AWS](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_mfa.html) in the *IAM User Guide*\. 19 | + **Use policy conditions for extra security** – To the extent that it's practical, define the conditions under which your identity\-based policies allow access to a resource\. For example, you can write conditions to specify a range of allowable IP addresses that a request must come from\. You can also write conditions to allow requests only within a specified date or time range, or to require the use of SSL or MFA\. For more information, see [IAM JSON policy elements: Condition](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition.html) in the *IAM User Guide*\. 20 | 21 | ## Using the Amazon ECR Console 22 | 23 | To access the Amazon Elastic Container Registry console, you must have a minimum set of permissions\. These permissions must allow you to list and view details about the Amazon ECR resources in your AWS account\. If you create an identity\-based policy that is more restrictive than the minimum required permissions, the console won't function as intended for entities \(IAM users or roles\) with that policy\. 24 | 25 | To ensure that those entities can still use the Amazon ECR console, add the `AmazonEC2ContainerRegistryReadOnly` AWS managed policy to the entities\. For more information, see [Adding Permissions to a User](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console) in the *IAM User Guide*: 26 | 27 | ``` 28 | { 29 | "Version": "2012-10-17", 30 | "Statement": [ 31 | { 32 | "Effect": "Allow", 33 | "Action": [ 34 | "ecr:GetAuthorizationToken", 35 | "ecr:BatchCheckLayerAvailability", 36 | "ecr:GetDownloadUrlForLayer", 37 | "ecr:GetRepositoryPolicy", 38 | "ecr:DescribeRepositories", 39 | "ecr:ListImages", 40 | "ecr:DescribeImages", 41 | "ecr:BatchGetImage", 42 | "ecr:GetLifecyclePolicy", 43 | "ecr:GetLifecyclePolicyPreview", 44 | "ecr:ListTagsForResource", 45 | "ecr:DescribeImageScanFindings" 46 | ], 47 | "Resource": "*" 48 | } 49 | ] 50 | } 51 | ``` 52 | 53 | You don't need to allow minimum console permissions for users that are making calls only to the AWS CLI or the AWS API\. Instead, allow access to only the actions that match the API operation that you're trying to perform\. 54 | 55 | ## Allow Users to View Their Own Permissions 56 | 57 | This example shows how you might create a policy that allows IAM users to view the inline and managed policies that are attached to their user identity\. This policy includes permissions to complete this action on the console or programmatically using the AWS CLI or AWS API\. 58 | 59 | ``` 60 | { 61 | "Version": "2012-10-17", 62 | "Statement": [ 63 | { 64 | "Sid": "ViewOwnUserInfo", 65 | "Effect": "Allow", 66 | "Action": [ 67 | "iam:GetUserPolicy", 68 | "iam:ListGroupsForUser", 69 | "iam:ListAttachedUserPolicies", 70 | "iam:ListUserPolicies", 71 | "iam:GetUser" 72 | ], 73 | "Resource": ["arn:aws:iam::*:user/${aws:username}"] 74 | }, 75 | { 76 | "Sid": "NavigateInConsole", 77 | "Effect": "Allow", 78 | "Action": [ 79 | "iam:GetGroupPolicy", 80 | "iam:GetPolicyVersion", 81 | "iam:GetPolicy", 82 | "iam:ListAttachedGroupPolicies", 83 | "iam:ListGroupPolicies", 84 | "iam:ListPolicyVersions", 85 | "iam:ListPolicies", 86 | "iam:ListUsers" 87 | ], 88 | "Resource": "*" 89 | } 90 | ] 91 | } 92 | ``` 93 | 94 | ## Accessing One Amazon ECR Repository 95 | 96 | In this example, you want to grant an IAM user in your AWS account access to one of your Amazon ECR repositories, `my-repo`\. You also want to allow the user to push, pull, and list images\. 97 | 98 | ``` 99 | { 100 | "Version":"2012-10-17", 101 | "Statement":[ 102 | { 103 | "Sid":"ListImagesInRepository", 104 | "Effect":"Allow", 105 | "Action":[ 106 | "ecr:ListImages" 107 | ], 108 | "Resource":"arn:aws:ecr:us-east-1:123456789012:repository/my-repo" 109 | }, 110 | { 111 | "Sid":"GetAuthorizationToken", 112 | "Effect":"Allow", 113 | "Action":[ 114 | "ecr:GetAuthorizationToken" 115 | ], 116 | "Resource":"*" 117 | }, 118 | { 119 | "Sid":"ManageRepositoryContents", 120 | "Effect":"Allow", 121 | "Action":[ 122 | "ecr:BatchCheckLayerAvailability", 123 | "ecr:GetDownloadUrlForLayer", 124 | "ecr:GetRepositoryPolicy", 125 | "ecr:DescribeRepositories", 126 | "ecr:ListImages", 127 | "ecr:DescribeImages", 128 | "ecr:BatchGetImage", 129 | "ecr:InitiateLayerUpload", 130 | "ecr:UploadLayerPart", 131 | "ecr:CompleteLayerUpload", 132 | "ecr:PutImage" 133 | ], 134 | "Resource":"arn:aws:ecr:us-east-1:123456789012:repository/my-repo" 135 | } 136 | ] 137 | } 138 | ``` -------------------------------------------------------------------------------- /doc_source/ecr-using-tags.md: -------------------------------------------------------------------------------- 1 | # Tagging an Amazon ECR repository 2 | 3 | To help you manage your Amazon ECR repositories, you can optionally assign your own metadata to each repository in the form of *tags*\. This topic describes tags and shows you how to create them\. 4 | 5 | **Topics** 6 | + [Tag basics](#tag-basics) 7 | + [Tagging your resources](#tag-resources) 8 | + [Tag restrictions](#tag-restrictions) 9 | + [Tagging your resources for billing](#tag-resources-for-billing) 10 | + [Working with tags using the console](#tag-resources-console) 11 | + [Working with tags using the AWS CLI or API](#tag-resources-api-sdk) 12 | 13 | ## Tag basics 14 | 15 | A tag is a label that you assign to an AWS resource\. Each tag consists of a *key* and an optional *value*, both of which you define\. 16 | 17 | Tags enable you to categorize your AWS resources in different ways, for example, by purpose, owner, or environment\. This is useful when you have many resources of the same type—you can quickly identify a specific resource based on the tags you've assigned to it\. For example, you could define a set of tags for your account's Amazon ECR repositories that helps you track each repo's owner\. 18 | 19 | We recommend that you devise a set of tag keys that meets your needs\. Using a consistent set of tag keys makes it easier for you to manage your resources\. You can search and filter the resources based on the tags you add\. 20 | 21 | Tags don't have any semantic meaning to Amazon ECR and are interpreted strictly as a string of characters\. Also, tags are not automatically assigned to your resources\. You can edit tag keys and values, and you can remove tags from a resource at any time\. You can set the value of a tag to an empty string, but you can't set the value of a tag to null\. If you add a tag that has the same key as an existing tag on that resource, the new value overwrites the old value\. If you delete a resource, any tags for the resource are also deleted\. 22 | 23 | You can work with tags using the AWS Management Console, the AWS CLI, and the Amazon ECR API\. 24 | 25 | If you're using AWS Identity and Access Management \(IAM\), you can control which users in your AWS account have permission to create, edit, or delete tags\. 26 | 27 | ## Tagging your resources 28 | 29 | You can tag new or existing Amazon ECR repositories\. 30 | 31 | If you're using the Amazon ECR console, you can apply tags to new resources when they are created or existing resources by using the **Tags** option on the navigation pane at any time\. 32 | 33 | If you're using the Amazon ECR API, the AWS CLI, or an AWS SDK, you can apply tags to new repositories using the `tags` parameter on the CreateRepository API action or use the `TagResource` API action to apply tags to existing resources\. For more information, see [TagResource](https://docs.aws.amazon.com/AmazonECR/latest/APIReference/API_TagResource.html)\. 34 | 35 | Additionally, if tags cannot be applied during repository creation, we roll back the repository creation process\. This ensures that repositories are either created with tags or not created at all, and that no repositories are left untagged at any time\. By tagging repositories at the time of creation, you can eliminate the need to run custom tagging scripts after repository creation\. 36 | 37 | ## Tag restrictions 38 | 39 | The following basic restrictions apply to tags: 40 | + Maximum number of tags per repository – 50 41 | + For each repository, each tag key must be unique, and each tag key can have only one value\. 42 | + Maximum key length – 128 Unicode characters in UTF\-8 43 | + Maximum value length – 256 Unicode characters in UTF\-8 44 | + If your tagging schema is used across multiple services and resources, remember that other services may have restrictions on allowed characters\. Generally allowed characters are: letters, numbers, and spaces representable in UTF\-8, and the following characters: \+ \- = \. \_ : / @\. 45 | + Tag keys and values are case\-sensitive\. 46 | + Don't use the `aws:` prefix for either keys or values; it's reserved for AWS use\. You can't edit or delete tag keys or values with this prefix\. Tags with this prefix do not count against your tags per resource limit\. 47 | 48 | ## Tagging your resources for billing 49 | 50 | The tags you add to your Amazon ECR repositories are helpful when reviewing cost allocation after enabling them in your Cost & Usage Report\. For more information, see [Amazon ECR usage reports](usage-reports.md)\. 51 | 52 | To see the cost of your combined resources, you can organize your billing information based on resources that have the same tag key values\. For example, you can tag several resources with a specific application name, and then organize your billing information to see the total cost of that application across several services\. For more information about setting up a cost allocation report with tags, see [The Monthly Cost Allocation Report](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/configurecostallocreport.html) in the *AWS Billing and Cost Management User Guide*\. 53 | 54 | **Note** 55 | If you've just enabled reporting, data for the current month is available for viewing after 24 hours\. 56 | 57 | ## Working with tags using the console 58 | 59 | Using the Amazon ECR console, you can manage the tags associated with new or existing repositories\. 60 | 61 | When you select a specific repository in the Amazon ECR console, you can view the tags by selecting **Tags** in the navigation pane\. 62 | 63 | **To add a tag to a repository** 64 | 65 | 1. Open the Amazon ECR console at [https://console\.aws\.amazon\.com/ecr/](https://console.aws.amazon.com/ecr/)\. 66 | 67 | 1. From the navigation bar, select the region to use\. 68 | 69 | 1. In the navigation pane, choose **Repositories**\. 70 | 71 | 1. On the **Repositories** page, choose the repository to view\. 72 | 73 | 1. On the **Repositories : *repository\_name*** page, select **Tags** from the navigation pane\. 74 | 75 | 1. On the **Tags** page, select **Add tags**, **Add tag**\. 76 | 77 | 1. On the **Edit Tags** page, specify the key and value for each tag, and then choose **Save**\. 78 | 79 | **To delete a tag from an individual resource** 80 | 81 | 1. Open the Amazon ECR console at [https://console\.aws\.amazon\.com/ecr/](https://console.aws.amazon.com/ecr/)\. 82 | 83 | 1. From the navigation bar, select the region to use\. 84 | 85 | 1. On the **Repositories** page, choose the repository to view\. 86 | 87 | 1. On the **Repositories : *repository\_name*** page, select **Tags** from the navigation pane\. 88 | 89 | 1. On the **Tags** page, select **Edit**\. 90 | 91 | 1. On the **Edit Tags** page, select **Remove** for each tag you want to delete, and choose **Save**\. 92 | 93 | ## Working with tags using the AWS CLI or API 94 | 95 | Use the following to add, update, list, and delete the tags for your resources\. The corresponding documentation provides examples\. 96 | 97 | 98 | **Tagging Support for Amazon ECR Resources** 99 | 100 | | Task | AWS CLI | API action | 101 | | --- | --- | --- | 102 | | Add or overwrite one or more tags\. | [tag\-resource](https://docs.aws.amazon.com/cli/latest/reference/ecr/tag-resource.html) | [TagResource](https://docs.aws.amazon.com/AmazonECR/latest/APIReference/API_TagResource.html) | 103 | | Delete one or more tags\. | [untag\-resource](https://docs.aws.amazon.com/cli/latest/reference/ecr/untag-resource.html) | [UntagResource](https://docs.aws.amazon.com/AmazonECR/latest/APIReference/API_UntagResource.html) | 104 | 105 | The following examples show how to manage tags using the AWS CLI\. 106 | 107 | **Example 1: Tag an existing repository** 108 | The following command tags an existing repository\. 109 | 110 | ``` 111 | aws ecr tag-resource --resource-arn arn:aws:ecr:region:account_id:repository/repository_name --tags Key=stack,Value=dev 112 | ``` 113 | 114 | **Example 2: Tag an existing repository with multiple tags** 115 | The following command tags an existing repository\. 116 | 117 | ``` 118 | aws ecr tag-resource --resource-arn arn:aws:ecr:region:account_id:repository/repository_name --tags Key=key1,Value=value1 Key=key2,Value=value2 Key=key3,Value=value3 119 | ``` 120 | 121 | **Example 3: Untag an existing repository** 122 | The following command deletes a tag from an existing repository\. 123 | 124 | ``` 125 | aws ecr untag-resource --resource-arn arn:aws:ecr:region:account_id:repository/repository_name --tag-keys tag_key 126 | ``` 127 | 128 | **Example 4: List tags for a repository** 129 | The following command lists the tags associated with an existing repository\. 130 | 131 | ``` 132 | aws ecr list-tags-for-resource --resource-arn arn:aws:ecr:region:account_id:repository/repository_name 133 | ``` 134 | 135 | **Example 5: Create a repository and apply a tag** 136 | The following command creates a repository named `test-repo` and adds a tag with key `team` and value `devs`\. 137 | 138 | ``` 139 | aws ecr create-repository --repository-name test-repo --tags Key=team,Value=devs 140 | ``` -------------------------------------------------------------------------------- /doc_source/image-scanning.md: -------------------------------------------------------------------------------- 1 | # Image scanning 2 | 3 | Amazon ECR image scanning helps in identifying software vulnerabilities in your container images\. Each container image may be scanned once per 24 hours\. Amazon ECR uses the Common Vulnerabilities and Exposures \(CVEs\) database from the open\-source Clair project and provides a list of scan findings\. You can review the scan findings for information about the security of the container images that are being deployed\. For more information about Clair, see [Clair](https://github.com/quay/clair) on GitHub\. 4 | 5 | Amazon ECR uses the severity for a CVE from the upstream distribution source if available, otherwise we use the Common Vulnerability Scoring System \(CVSS\) score\. The CVSS score can be used to obtain the NVD vulnerability severity rating\. For more information, see [NVD Vulnerability Severity Ratings](https://nvd.nist.gov/vuln-metrics/cvss)\. 6 | 7 | You can manually scan container images stored in Amazon ECR\. Or, alternatively, you can configure your repositories to scan images when you push them to a repository\. The last completed image scan findings can be retrieved for each image\. Amazon ECR sends an event to Amazon EventBridge \(formerly called CloudWatch Events\) when an image scan is completed\. For more information, see [Amazon ECR events and EventBridge](ecr-eventbridge.md)\. 8 | 9 | For troubleshooting details for some common issues when scanning images, see [Troubleshooting image scanning issues](image-scanning-troubleshooting.md)\. 10 | 11 | **Topics** 12 | + [Configuring a repository to scan on push](#scanning-repository) 13 | + [Manually scanning an image](#manual-scan) 14 | + [Retrieving image scan findings](#describe-scan-findings) 15 | 16 | ## Configuring a repository to scan on push 17 | 18 | You can configure the image scan settings either for a new repository during creation or for an existing repository\. When **scan on push** is enabled, images are scanned after being pushed to a repository\. If **scan on push** is disabled on a repository, then you must manually start each image scan to get the scan results\. 19 | 20 | **Topics** 21 | + [Creating a new repository to scan on push](#scanning-new-repository) 22 | + [Configure an existing repository to scan on push](#scanning-existing-repository) 23 | 24 | ### Creating a new repository to scan on push 25 | 26 | When a new repository is configured to **scan on push**, all new images pushed to the repository will be scanned\. Results from the last completed image scan can then be retrieved\. For more information, see [Retrieving image scan findings](#describe-scan-findings)\. 27 | 28 | For AWS Management Console steps, see [Creating a repository](repository-create.md)\. 29 | 30 | #### To create a repository configured for scan on push \(AWS CLI\) 31 | 32 | Use the following command to create a new repository with image **scan on push** configured\. 33 | + [create\-repository](https://docs.aws.amazon.com/cli/latest/reference/ecr/create-repository.html) \(AWS CLI\) 34 | 35 | ``` 36 | aws ecr create-repository --repository-name name --image-scanning-configuration scanOnPush=true --region us-east-2 37 | ``` 38 | 39 | #### To create a repository configured for scan on push \(AWS Tools for Windows PowerShell\) 40 | 41 | Use the following command to create a new repository with image **scan on push** configured\. 42 | + [New\-ECRRepository](https://docs.aws.amazon.com/powershell/latest/reference/items/New-ECRRepository.html) \(AWS Tools for Windows PowerShell\) 43 | 44 | ``` 45 | New-ECRRepository -RepositoryName name -ImageScanningConfiguration_ScanOnPush true -Region us-east-2 -Force 46 | ``` 47 | 48 | ### Configure an existing repository to scan on push 49 | 50 | Your existing repositories can be configured to scan images when you push them to a repository\. This setting will apply to future image pushes\. Results from the last completed image scan can then be retrieved\. For more information, see [Retrieving image scan findings](#describe-scan-findings)\. 51 | 52 | For AWS Management Console steps, see [Editing a repository](repository-edit.md)\. 53 | 54 | #### To edit the settings of an existing repository \(AWS CLI\) 55 | 56 | Use the following command to edit the image scanning settings of an existing repository\. 57 | + [put\-image\-scanning\-configuration](https://docs.aws.amazon.com/cli/latest/reference/ecr/put-image-scanning-configuration.html) \(AWS CLI\) 58 | 59 | ``` 60 | aws ecr put-image-scanning-configuration --repository-name name --image-scanning-configuration scanOnPush=true --region us-east-2 61 | ``` 62 | **Note** 63 | To disable image **scan on push** for a repository, specify `scanOnPush=false`\. 64 | 65 | #### To edit the settings of an existing repository \(AWS Tools for Windows PowerShell\) 66 | 67 | Use the following command to edit the image scanning settings of an existing repository\. 68 | + [New\-ECRRepository](https://docs.aws.amazon.com/powershell/latest/reference/items/Write-ECRImageScanningConfiguration.html) \(AWS Tools for Windows PowerShell\) 69 | 70 | ``` 71 | Write-ECRImageScanningConfiguration -RepositoryName name -ImageScanningConfiguration_ScanOnPush true -Region us-east-2 -Force 72 | ``` 73 | 74 | ## Manually scanning an image 75 | 76 | You can start image scans manually when you want to scan images in repositories that aren't configured to **scan on push**\. An image can only be scanned once each day\. This limit includes the initial **scan on push**, if enabled, and any manual scans\. 77 | 78 | For troubleshooting details for some common issues when scanning images, see [Troubleshooting image scanning issues](image-scanning-troubleshooting.md)\. 79 | 80 | ### To start a manual scan of an image \(console\) 81 | 82 | Use the following steps to start a manual image scan using the AWS Management Console\. 83 | 84 | 1. Open the Amazon ECR console at [https://console\.aws\.amazon\.com/ecr/repositories](https://console.aws.amazon.com/ecr/repositories)\. 85 | 86 | 1. From the navigation bar, choose the Region to create your repository in\. 87 | 88 | 1. In the navigation pane, choose **Repositories**\. 89 | 90 | 1. On the **Repositories** page, choose the repository that contains the image to scan\. 91 | 92 | 1. On the **Images** page, select the image to scan and then choose **Scan**\. 93 | 94 | ### To start a manual scan of an image \(AWS CLI\) 95 | 96 | Use the following AWS CLI command to start a manual scan of an image\. You can specify an image using the `imageTag` or `imageDigest`, both of which can be obtained using the [list\-images](https://docs.aws.amazon.com/cli/latest/reference/ecr/list-images.html) CLI command\. 97 | + [start\-image\-scan](https://docs.aws.amazon.com/cli/latest/reference/ecr/start-image-scan.html) \(AWS CLI\) 98 | 99 | The following example uses an image tag\. 100 | 101 | ``` 102 | aws ecr start-image-scan --repository-name name --image-id imageTag=tag_name --region us-east-2 103 | ``` 104 | 105 | The following example uses an image digest\. 106 | 107 | ``` 108 | aws ecr start-image-scan --repository-name name --image-id imageDigest=sha256_hash --region us-east-2 109 | ``` 110 | 111 | ### To start a manual scan of an image \(AWS Tools for Windows PowerShell\) 112 | 113 | Use the following AWS Tools for Windows PowerShell command to start a manual scan of an image\. You can specify an image using the `ImageId_ImageTag` or `ImageId_ImageDigest`, both of which can be obtained using the [Get\-ECRImage](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-ECRImage.html) CLI command\. 114 | + [Get\-ECRImageScanFinding](https://docs.aws.amazon.com/powershell/latest/reference/items/Start-ECRImageScan.html) \(AWS Tools for Windows PowerShell\) 115 | 116 | The following example uses an image tag\. 117 | 118 | ``` 119 | Start-ECRImageScan -RepositoryName name -ImageId_ImageTag tag_name -Region us-east-2 -Force 120 | ``` 121 | 122 | The following example uses an image digest\. 123 | 124 | ``` 125 | Start-ECRImageScan -RepositoryName name -ImageId_ImageDigest sha256_hash -Region us-east-2 -Force 126 | ``` 127 | 128 | ## Retrieving image scan findings 129 | 130 | You can retrieve the scan findings for the last completed image scan\. The findings list by severity the software vulnerabilities that were discovered, based on the Common Vulnerabilities and Exposures \(CVEs\) database\. 131 | 132 | For troubleshooting details for some common issues when scanning images, see [Troubleshooting image scanning issues](image-scanning-troubleshooting.md)\. 133 | 134 | ### To retrieve image scan findings \(console\) 135 | 136 | Use the following steps to retrieve image scan findings using the AWS Management Console\. 137 | 138 | 1. Open the Amazon ECR console at [https://console\.aws\.amazon\.com/ecr/repositories](https://console.aws.amazon.com/ecr/repositories)\. 139 | 140 | 1. From the navigation bar, choose the Region to create your repository in\. 141 | 142 | 1. In the navigation pane, choose **Repositories**\. 143 | 144 | 1. On the **Repositories** page, choose the repository that contains the image to retrieve the scan findings for\. 145 | 146 | 1. On the **Images** page, under the **Vulnerabilities** column, select **Details** for the image to retrieve the scan findings for\. 147 | 148 | ### To retrieve image scan findings \(AWS CLI\) 149 | 150 | Use the following AWS CLI command to retrieve image scan findings using the AWS CLI\. You can specify an image using the `imageTag` or `imageDigest`, both of which can be obtained using the [list\-images](https://docs.aws.amazon.com/cli/latest/reference/ecr/list-images.html) CLI command\. 151 | + [describe\-image\-scan\-findings](https://docs.aws.amazon.com/cli/latest/reference/ecr/describe-image-scan-findings.html) \(AWS CLI\) 152 | 153 | The following example uses an image tag\. 154 | 155 | ``` 156 | aws ecr describe-image-scan-findings --repository-name name --image-id imageTag=tag_name --region us-east-2 157 | ``` 158 | 159 | The following example uses an image digest\. 160 | 161 | ``` 162 | aws ecr describe-image-scan-findings --repository-name name --image-id imageDigest=sha256_hash --region us-east-2 163 | ``` 164 | 165 | ### To retrieve image scan findings \(AWS Tools for Windows PowerShell\) 166 | 167 | Use the following AWS Tools for Windows PowerShell command to retrieve image scan findings\. You can specify an image using the `ImageId_ImageTag` or `ImageId_ImageDigest`, both of which can be obtained using the [Get\-ECRImage](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-ECRImage.html) CLI command\. 168 | + [Get\-ECRImageScanFinding](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-ECRImageScanFinding.html) \(AWS Tools for Windows PowerShell\) 169 | 170 | The following example uses an image tag\. 171 | 172 | ``` 173 | Get-ECRImageScanFinding -RepositoryName name -ImageId_ImageTag tag_name -Region us-east-2 174 | ``` 175 | 176 | The following example uses an image digest\. 177 | 178 | ``` 179 | Get-ECRImageScanFinding -RepositoryName name -ImageId_ImageDigest sha256_hash -Region us-east-2 180 | ``` --------------------------------------------------------------------------------