# Pushing an image to an Amazon ECR private repository You can push your Docker images, manifest lists, and Open Container Initiative (OCI) images and compatible artifacts to your private repositories. Amazon ECR provides a way to replicate your images to other repositories. By specifying a replication configuration in your private registry settings, you can replicate across Regions in your own registry and across different accounts. For more information, see [Private registry settings in Amazon ECR](registry-settings.md). **Note** If you push an image that is currently archived, that image will be automatically restored and removed from the archive. For more information about archiving and restoring images, see [Archiving an image in Amazon ECR](archive_restore_image.md). When registry blob mounting is enabled and mounting parameters are included, Amazon ECR automatically checks for existing layers in your registry during push operations. If a layer already exists in another repository within the same registry, Amazon ECR will mount the existing layer instead of uploading a duplicate. For more information, see [Blob mounting in Amazon ECR](blob-mounting.md). **Topics** + [ # IAM permissions for pushing an image to an Amazon ECR private repository ](image-push-iam.md) + [ # Pushing a Docker image to an Amazon ECR private repository ](docker-push-ecr-image.md) + [ # Pushing a multi-architecture image to an Amazon ECR private repository ](docker-push-multi-architecture-image.md) + [ # Pushing a Helm chart to an Amazon ECR private repository ](push-oci-artifact.md) # IAM permissions for pushing an image to an Amazon ECR private repository Users need IAM permissions to push images to Amazon ECR private repositories. Following the best practice of granting least privilege, you can grant access to a specific repository. You can also grant access to all repositories. A user must authenticate to each Amazon ECR registry they want to push images to by requesting an authorization token. Amazon ECR provides several AWS managed policies to control user access at varying levels. For more information, see [AWS managed policies for Amazon Elastic Container Registry](security-iam-awsmanpol.md). You can also create a your own IAM policies. The following IAM policy grants the required permissions for pushing an image to a specific repository. To limit the permissions for a specific repository, use the full Amazon Resource Name (ARN) of the repository. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ecr:CompleteLayerUpload", "ecr:UploadLayerPart", "ecr:InitiateLayerUpload", "ecr:BatchCheckLayerAvailability", "ecr:PutImage", "ecr:BatchGetImage" ], "Resource": "arn:aws:ecr:us-east-1:111122223333:repository/repository-name" }, { "Effect": "Allow", "Action": "ecr:GetAuthorizationToken", "Resource": "*" } ] } ``` ------ The following IAM policy grants the required permissions for pushing an image to all repositories. ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ecr:CompleteLayerUpload", "ecr:GetAuthorizationToken", "ecr:UploadLayerPart", "ecr:InitiateLayerUpload", "ecr:BatchCheckLayerAvailability", "ecr:PutImage", "ecr:BatchGetImage" ], "Resource": "arn:aws:ecr:us-west-2:111122223333:repository/*" } ] } ``` # Pushing a Docker image to an Amazon ECR private repository You can push your container images to an Amazon ECR repository with the **docker push** command. Amazon ECR also supports creating and pushing Docker manifest lists that are used for multi-architecture images. For information, see [Pushing a multi-architecture image to an Amazon ECR private repository](docker-push-multi-architecture-image.md). **To push a Docker image to an Amazon ECR repository** The Amazon ECR repository must exist before you push the image, or you must have a repository creation template defined. For more information, see [Creating an Amazon ECR private repository to store images](repository-create.md) and [Templates to control repositories created during a pull through cache, create on push, or replication action](repository-creation-templates.md). 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 in Amazon ECR](registry_auth.md). To authenticate Docker to an Amazon ECR registry, run the **aws ecr get-login-password** command. When passing the authentication 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. **Important** 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*. ``` aws ecr get-login-password --region | docker login --username AWS --password-stdin .dkr.ecr..amazonaws.com ``` 1. If your image repository doesn't exist in the registry you intend to push to yet, and you have a repository creation template defined, you can push your image using your repository creation template's prefix and your desired repository name. ECR will automatically create the repository for you using the predefined settings of your repository creation template. If you do not have a matching repository creation template defined, you will need to create a repository. For more information, see [Templates to control repositories created during a pull through cache, create on push, or replication action](repository-creation-templates.md) or [Creating an Amazon ECR private repository to store images](repository-create.md). 1. Identify the local image to push. Run the **docker images** command to list the container images on your system. ``` docker images ``` You can identify an image with the *repository:tag* value or the image ID in the resulting command output. 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`. The following example tags a local image with the ID * e9ae3c220b23* as `aws_account_id.dkr.ecr.region.amazonaws.com/my-repository:tag`. ``` docker tag e9ae3c220b23 aws_account_id.dkr.ecr.region.amazonaws.com/my-repository:tag ``` 1. Push the image using the **docker push** command: ``` docker push aws_account_id.dkr.ecr.region.amazonaws.com/my-repository:tag ``` 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). # Pushing a multi-architecture image to an Amazon ECR private repository You can push multi-architecture images to an Amazon ECR repository by creating and pushing Docker manifest lists. 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 are 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/). A manifest list can be pulled or referenced in an Amazon ECS task definition or Amazon EKS pod spec like other Amazon ECR images. **Prerequisites** + In your Docker CLI, turn on experimental features. For information about experimental features, see [Experimental features](https://docs.docker.com/engine/reference/commandline/cli/#experimental-features) in the Docker documentation. + The Amazon ECR repository must exist before you push the image. For more information, see [Creating an Amazon ECR private repository to store images](repository-create.md). + Images must be pushed to your repository before you create the Docker manifest. For information about how to push an image, see [Pushing a Docker image to an Amazon ECR private repository](docker-push-ecr-image.md). **To push a multi-architecture Docker image to an Amazon ECR repository** 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 in Amazon ECR](registry_auth.md). To authenticate Docker to an Amazon ECR registry, run the **aws ecr get-login-password** command. When passing the authentication 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. **Important** 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*. ``` aws ecr get-login-password --region | docker login --username AWS --password-stdin .dkr.ecr..amazonaws.com ``` 1. List the images in your repository, confirming the image tags. ``` aws ecr describe-images --repository-name my-repository ``` 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. ``` docker manifest create aws_account_id.dkr.ecr.region.amazonaws.com/my-repository aws_account_id.dkr.ecr.region.amazonaws.com/my-repository:image_one_tag aws_account_id.dkr.ecr.region.amazonaws.com/my-repository:image_two ``` 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. ``` docker manifest inspect aws_account_id.dkr.ecr.region.amazonaws.com/my-repository ``` 1. Push the Docker manifest list to your Amazon ECR repository. ``` docker manifest push aws_account_id.dkr.ecr.region.amazonaws.com/my-repository ``` # Pushing a Helm chart to an Amazon ECR private repository You can push Open Container Initiative (OCI) artifacts to an Amazon ECR repository. To see an example of this functionality, use the following steps to push a Helm chart to Amazon ECR. For information about using your Amazon ECR hosted Helm charts with Amazon EKS, see [Installing a Helm chart on an Amazon EKS cluster](using-helm-charts-eks.md). **To push a Helm chart to an Amazon ECR repository** 1. Install the latest version of the Helm client. These steps were written using Helm version `3.18.6`. For compatibility with Amazon EKS supported Kubernetes versions, use Helm version 3.9 or later. For more information, see [Installing Helm](https://helm.sh/docs/intro/install/). 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/). 1. Create a Helm chart named `helm-test-chart` and clear the contents of the `templates` directory. ``` helm create helm-test-chart rm -rf ./helm-test-chart/templates/* ``` 1. Create a `ConfigMap` in the `templates` folder. ``` cd helm-test-chart/templates cat < configmap.yaml apiVersion: v1 kind: ConfigMap metadata: name: helm-test-chart-configmap data: myvalue: "Hello World" EOF ``` 1. Package the chart. The output will contain the filename of the packaged chart which you use when pushing the Helm chart. ``` cd ../.. helm package helm-test-chart ``` Output ``` Successfully packaged chart and saved it to: /Users/username/helm-test-chart-0.1.0.tgz ``` 1. Create a repository to store your Helm chart. The name of your repository should match the name you used when creating the Helm chart in step 2. For more information, see [Creating an Amazon ECR private repository to store images](repository-create.md). ``` aws ecr create-repository \ --repository-name helm-test-chart \ --region us-west-2 ``` 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 in Amazon ECR](registry_auth.md). ``` aws ecr get-login-password \ --region us-west-2 | helm registry login \ --username AWS \ --password-stdin aws_account_id.dkr.ecr.region.amazonaws.com ``` 1. Push the Helm chart using the **helm push** command. The output should include the Amazon ECR repository URI and SHA digest. ``` helm push helm-test-chart-0.1.0.tgz oci://aws_account_id.dkr.ecr.region.amazonaws.com/ ``` 1. Describe your Helm chart. ``` aws ecr describe-images \ --repository-name helm-test-chart \ --region us-west-2 ``` In the output, verify that the `artifactMediaType` parameter indicates the proper artifact type. ``` { "imageDetails": [ { "registryId": "aws_account_id", "repositoryName": "helm-test-chart", "imageDigest": "sha256:dd8aebdda7df991a0ffe0b3d6c0cf315fd582cd26f9755a347a52adEXAMPLE", "imageTags": [ "0.1.0" ], "imageSizeInBytes": 1620, "imagePushedAt": "2021-09-23T11:39:30-05:00", "imageManifestMediaType": "application/vnd.oci.image.manifest.v1+json", "artifactMediaType": "application/vnd.cncf.helm.config.v1+json" } ] } ``` 1. (Optional) For additional steps, install the Helm `ConfigMap` and get started with Amazon EKS. For more information, see [Installing a Helm chart on an Amazon EKS cluster](using-helm-charts-eks.md).