# Private images in Amazon ECR
Amazon ECR stores Docker images, Open Container Initiative (OCI) images, and OCI compatible artifacts in private repositories. You can use the Docker CLI, or your preferred client, to push and pull images to and from your repositories.
With Amazon ECR support for OCI v1.1, you can store and manage reference artifacts that are defined by the OCI [Referrers API](https://github.com/opencontainers/distribution-spec/blob/main/spec.md#enabling-the-referrers-api). Artifacts include signatures, Software Bill of Materials (SBoMs), Helm charts, scan results, and attestations. A set of artifacts for a container image is transferred with that container and stored as a separate image that counts as an image consumed for your repository.
The [Sign images in Amazon ECR](image-signing.md) and [Deleting signatures and other artifacts from an Amazon ECR private repository](image-artifact-delete.md) pages provide examples of how to use signature-related artifacts. For more information on signing container images, see [Signing container images](https://docs.aws.amazon.com/signer/latest/developerguide/container-workflow.html) in the *AWS Signer Developer Guide*.
**Topics**
+ [Pushing an image to an Amazon ECR private repository](image-push.md)
+ [Deleting signatures and other artifacts from an Amazon ECR private repository](image-artifact-delete.md)
+ [Viewing image details in Amazon ECR](image-info.md)
+ [Pulling an image to your local environment from an Amazon ECR private repository](docker-pull-ecr-image.md)
+ [Pulling the Amazon Linux container image](amazon_linux_container_image.md)
+ [Deleting an image in Amazon ECR](delete_image.md)
+ [Archiving an image in Amazon ECR](archive_restore_image.md)
+ [Retagging an image in Amazon ECR](image-retag.md)
+ [Preventing image tags from being overwritten in Amazon ECR](image-tag-mutability.md)
+ [Container image manifest format support in Amazon ECR](image-manifest-formats.md)
+ [Using Amazon ECR images with Amazon ECS](ECR_on_ECS.md)
+ [Using Amazon ECR Images with Amazon EKS](ECR_on_EKS.md)
# 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).
# Deleting signatures and other artifacts from an Amazon ECR private repository
You can use the ORAS client to list and delete signatures and other reference type artifacts from an Amazon ECR private repository. Deleting signatures and other reference artifacts is similar to how an image is deleted (see [Deleting an image in Amazon ECR](delete_image.md)). Here is how to list artifacts and delete signatures:
**To manage image artifacts using the ORAS CLI**
1. Install and configure the ORAS client.
For information about installing and configuring the ORAS client, see [Installation](https://oras.land/docs/installation) in the ORAS documentation.
1. To list available artifacts for an Amazon ECR image, use `oras discover`, followed by an image name:
```
oras discover 111222333444.dkr.ecr.us-east-1.amazonaws.com/oci:helloworld
```
The output should look similar to this:
```
111222333444.dkr.ecr.us-east-1.amazonaws.com/oci@sha256:88c0c54329bfdc1d94d6f58cd3fcb1226d46f58670f44a8c689cb3c9b37b6925
└── application/vnd.cncf.notary.signature
├── sha256:387c10c1598ee18aae81dcfc86d0d06d116e46461d1c3cda8927e69c48108c42
└── sha256:6527bcec87adf1d55460666183b9d0968b3cd4e4bc34602d485206a219851171
```
1. To delete a signature using the ORAS CLI, given the previous example, run the following command:
```
oras manifest delete 111222333444.dkr.ecr.us-east-1.amazonaws.com/oci@sha256:387c10c1598ee18aae81dcfc86d0d06d116e46461d1c3cda8927e69c48108c42
```
The output should look similar to this:
```
Are you sure you want to delete the manifest "111222333444.dkr.ecr.us-east-1.amazonaws.com/oci@sha256:387c10c1598ee18aae81dcfc86d0d06d116e46461d1c3cda8927e69c48108c42" and all tags associated with it? [y/N] y
```
1. Press `y`. The artifact should be deleted.
**To troubleshoot artifact deletion**
If a signature deletion, such as the one just shown, should fail, output similar to the following appears.
```
Error response from registry: failed to delete 111222333444.dkr.ecr.us-east-1.amazonaws.com/oci@sha256:387c10c1598ee18aae81dcfc86d0d06d116e46461d1c3cda8927e69c48108c42:
unsupported: Requested image referenced by manifest list: [sha256:005e2c97a6373e483799fa4ff29ac64a42dd10f08efcc166d6775f9b74943b5b]
```
This failure can happen when deleting an image pushed before the OCI 1.1 launch. As noted in the error, you must delete the manifest referencing the image before you can delete the image as follows:
1. To delete the manifest associated with the signature you want to delete, type:
```
oras manifest delete 111222333444.dkr.ecr.us-east-1.amazonaws.com/oci@sha256:005e2c97a6373e483799fa4ff29ac64a42dd10f08efcc166d6775f9b74943b5b
```
The output should look similar to this:
```
Are you sure you want to delete the manifest "sha256:005e2c97a6373e483799fa4ff29ac64a42dd10f08efcc166d6775f9b74943b5b" and all tags associated with it? [y/N] y
```
1. Press `y`. The manifest should be deleted.
1. With the manifest gone, you can delete the signature:
```
oras manifest delete 111222333444.dkr.ecr.us-east-1.amazonaws.com/oci@sha256:387c10c1598ee18aae81dcfc86d0d06d116e46461d1c3cda8927e69c48108c42
```
The output should look similar to this. Press `y`.
```
Are you sure you want to delete the manifest "sha256:387c10c1598ee18aae81dcfc86d0d06d116e46461d1c3cda8927e69c48108c42" and all tags associated with it? [y/N] y
Deleted [registry] 111222333444.dkr.ecr.us-east-1.amazonaws.com/oci@sha256:387c10c1598ee18aae81dcfc86d0d06d116e46461d1c3cda8927e69c48108c42
```
1. To see that the signature was deleted, type:
```
oras discover 111222333444.dkr.ecr.us-east-1.amazonaws.com/oci:helloworld
```
The output should look similar to this:
```
111222333444.dkr.ecr.us-east-1.amazonaws.com/oci@sha256:88c0c54329bfdc1d94d6f58cd3fcb1226d46f58670f44a8c689cb3c9b37b6925
└── application/vnd.cncf.notary.signature
└── sha256:6527bcec87adf1d55460666183b9d0968b3cd4e4bc34602d485206a219851171
```
# Viewing image details in Amazon ECR
After you push an image to your repository, you can view information about it. The details included are as follows:
+ Image URI
+ Image tags
+ Artifact media type
+ Image manifest type
+ Scanning status
+ The size of the image in MB
+ When the image was pushed to the repository
+ The replication status
**To view image details (AWS Management Console)**
1. Open the Amazon ECR console at [https://console.aws.amazon.com/ecr/repositories](https://console.aws.amazon.com/ecr/repositories).
1. From the navigation bar, choose the Region that contains the repository containing your image.
1. In the navigation pane, choose **Repositories**.
1. On the **Repositories** page, choose the repository to view.
1. On the **Repositories : *repository\$1name*** page, choose the image to view the details of.
# Pulling an image to your local environment from an Amazon ECR private repository
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).
**Important**
You cannot pull an archived image. Archived images must be restored before they can be pulled. For more information about archiving and restoring images, see [Archiving an image in Amazon ECR](archive_restore_image.md).
**Important**
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 AWS managed policies to control user access at varying levels. For information about the AWS managed policies for Amazon ECR, see [AWS managed policies for Amazon Elastic Container Registry](security-iam-awsmanpol.md).
**To pull a Docker image from an Amazon ECR repository**
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 in Amazon ECR](registry_auth.md).
1. (Optional) Identify the image to pull.
+ You can list the repositories in a registry with the **aws ecr describe-repositories** command:
```
aws ecr describe-repositories
```
The example registry above has a repository called `amazonlinux` .
+ You can describe the images within a repository with the **aws ecr describe-images** command:
```
aws ecr describe-images --repository-name amazonlinux
```
The example repository above has an image tagged as `latest` and `2016.09`, with the image digest ` sha256:f1d4ae3f7261a72e98c6ebefe9985cf10a0ea5bd762585a43e0700ed99863807`.
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.
```
docker pull aws_account_id.dkr.ecr.us-west-2.amazonaws.com/amazonlinux:latest
```
**Important**
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 in Amazon ECR](registry_auth.md).
# Pulling the Amazon Linux container image
The Amazon Linux container image is built from the same software components that are included in the Amazon Linux AMI. The Amazon Linux container image is available for use in any environment as a base image for Docker workloads. If you use the Amazon Linux AMI for applications in Amazon EC2, you can containerize your applications with the Amazon Linux container image.
You can use the Amazon Linux container image in your local development environment and then push your application to AWS using Amazon ECS. For more information, see [Using Amazon ECR images with Amazon ECS](ECR_on_ECS.md).
The Amazon Linux container image is available on Amazon ECR Public and on [Docker Hub](https://hub.docker.com/_/amazonlinux/). For support for the Amazon Linux container image, go to the [AWS developer forums](https://forums.aws.amazon.com/forum.jspa?forumID=228).
**To pull the Amazon Linux container image from Amazon ECR Public**
1. Authenticate your Docker client to the Amazon Linux Public registry. Authentication tokens are valid for 12 hours. For more information, see [Private registry authentication in Amazon ECR](registry_auth.md).
**Note**
The **ecr-public** commands are available in the AWS CLI starting with version `1.18.1.187`, however we recommend using 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-public get-login-password --region us-east-1 | docker login --username AWS --password-stdin public.ecr.aws
```
The output is as follows:
```
Login succeeded
```
1. Pull the Amazon Linux container image using the **docker pull** command. To view the Amazon Linux container image on the Amazon ECR Public Gallery, see [Amazon ECR Public Gallery - amazonlinux](https://gallery.ecr.aws/amazonlinux/amazonlinux).
```
docker pull public.ecr.aws/amazonlinux/amazonlinux:latest
```
1. (Optional) Run the container locally.
```
docker run -it public.ecr.aws/amazonlinux/amazonlinux /bin/bash
```
**To pull the Amazon Linux container image from Docker Hub**
1. Pull the Amazon Linux container image using the **docker pull** command.
```
docker pull amazonlinux
```
1. (Optional) Run the container locally.
```
docker run -it amazonlinux:latest /bin/bash
```
# Deleting an image in Amazon ECR
If you're finished using an image, you can delete it from your repository. 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 private repository in Amazon ECR](repository-delete.md).
As an alternative to deleting images manually, you can create repository lifecycle policies which provide more control over the lifecycle management of images in your repositories. Lifecycle policies automate this process for you. For more information, see [Automate the cleanup of images by using lifecycle policies in Amazon ECR](LifecyclePolicies.md).
**Note**
If your repository has a mix of images, some of which were pushed before Amazon ECR supported OCI v1.1, some signatures will have image indexes or manifest lists pointing to them. As a result, when you delete a pre-OCI v1.1 image, you might need to manually delete the manifest list that references the image in order to delete the artifact.
**To delete an image (AWS Management Console)**
1. Open the Amazon ECR console at [https://console.aws.amazon.com/ecr/repositories](https://console.aws.amazon.com/ecr/repositories).
1. From the navigation bar, choose the Region that contains the image to delete.
1. In the navigation pane, choose **Repositories**.
1. On the **Repositories** page, choose the repository that contains the image to delete.
1. On the **Repositories: *repository\$1name*** page, select the box to the left of the image to delete and choose ** Delete**.
1. In the **Delete image(s)** dialog box, verify that the selected images should be deleted and choose **Delete**.
**To delete an image (AWS CLI)**
1. List the images in your repository. Tagged images will have both an image digest as well as a list of associated tags. Untagged images will only have an image digest.
```
aws ecr list-images \
--repository-name my-repo
```
1. (Optional) Delete any unwanted tags for the image by specifying the tag associated with the image you want to delete. When the last tag is deleted from an image, the image is also deleted.
```
aws ecr batch-delete-image \
--repository-name my-repo \
--image-ids imageTag=tag1 imageTag=tag2
```
1. Delete a tagged or untagged image by specifying the image digest. When you delete an image by referencing its digest, the image and all of its tags are deleted.
```
aws ecr batch-delete-image \
--repository-name my-repo \
--image-ids imageDigest=sha256:4f70ef7a4d29e8c0c302b13e25962d8f7a0bd304EXAMPLE
```
To delete multiple images, you can specify multiple image tags or image digests in the request.
```
aws ecr batch-delete-image \
--repository-name my-repo \
--image-ids imageDigest=sha256:4f70ef7a4d29e8c0c302b13e25962d8f7a0bd304EXAMPLE imageDigest=sha256:f5t0e245ssffc302b13e25962d8f7a0bd304EXAMPLE
```
# Archiving an image in Amazon ECR
## What is the ECR archival storage class?
Amazon ECR archival storage class is a new storage class that provides low-cost, long-term storage for container images. Amazon ECR offers two storage classes:
+ **ECR standard storage class** – The default storage class for active images that are regularly accessed.
+ **ECR archival storage class** – A low-cost storage class for images that are rarely accessed but need to be retained for compliance or long-term reference. The archival storage class provides cost savings for large amount of images compared to the Standard storage class for long-term image retention. For detailed pricing information, see [Amazon ECR pricing](https://aws.amazon.com/ecr/pricing/).
To archive images, you have two options. First, you can configure lifecycle rules to automatically archive images based on:
+ Time since the image was pushed
+ Time since the image was last pulled
+ Number of images in the repository
You can also configure settings to permanently delete images after they've been archived for a specified period. Refer to [Automate the cleanup of images by using lifecycle policies in Amazon ECR](LifecyclePolicies.md) for more information.
You can also archive images using the Amazon ECR console or AWS CLI. Refer to [Archiving an image](archive-image.md) for more information.
When you need to use an archived image again, you can restore it back to the ECR Standard storage class. You can expect ECR to restore the image within 20 minutes. Restored images behave like newly pushed images and are immediately available for use when the restore is complete. Restored images are subject to scanning, replication, and repository lifecycle policies. Refer to [Restoring an image](restore-image.md) for more information.
# Archiving an image
You can archive images manually using the Amazon ECR console or AWS CLI, or automatically using lifecycle policies. When an image is archived:
+ The image is moved to the archival storage class.
+ Archived images cannot be pulled. Requests to pull the archived image will fail with a 404 error.
+ While the image cannot be pulled, it can still be described using the ** describe-images** command, or listed using the **list-images** command. The image status will be shown as `ARCHIVED`.
+ Archived images have a minimum storage duration of 90 days. You cannot configure lifecycle policies that delete images that have been in archive for less than 90 days. If you must delete images that have been archived for less than 90 days, you need to use the **batch-delete-image** API, but you will be charged for the 90-day minimum storage duration.
+ The image appears in an **Archived images** tab in the repository view (this tab will appear only if at least one image is archived in the repository).
+ The image can be restored as an active image by manually selecting it to be restored or by re-pushing the image to the repository.
+ The image will be deleted if the repository has lifecycle policies that delete the image with criteria such as time in archive.
------
#### [ AWS Management Console ]
**To archive an image**
1. Open the Amazon ECR console at [https://console.aws.amazon.com/ecr/repositories](https://console.aws.amazon.com/ecr/repositories).
1. From the navigation bar, choose the Region that contains the repository with the image you want to archive.
1. In the navigation pane, choose **Repositories**.
1. On the **Repositories** page, choose the repository containing the image you want to archive.
1. Select the image you want to archive. You will see Image Details.
1. To archive the image, select the **Archive** button and select **Confirm** when you are prompted.
1. If this is the first archived image in the repository, a new **Archived images** tab appears with the newly archived image. If there are other archived images, this image will be added to that tab.
------
#### [ AWS CLI ]
**To archive an image**
+ Use the **update-image-storage-class** command to archive an image by updating its storage class to `ARCHIVE`:
```
aws ecr update-image-storage-class \
--repository-name my-repository \
--image-id imageDigest=sha256:4f70ef7a4d29e8c0c302b13e25962d8f7a0bd304EXAMPLE \
--target-storage-class ARCHIVE
```
------
**To archive an image using lifecycle policies**
+ You can configure archive rules for your repositories using lifecycle policies to automatically archive images. Lifecycle policies allow you to automatically archive images based on criteria such as:
+ Time since the image was pushed
+ Time since the image was last pulled
+ Maximum number of images to keep active
You can also configure lifecycle policies to permanently delete images after they've been archived for a specified period. For more information and examples of lifecycle policies with archive actions, see [Automate the cleanup of images by using lifecycle policies in Amazon ECR](LifecyclePolicies.md).
**Note**
Archived images have a minimum storage duration of 90 days. You cannot configure lifecycle policies that delete images that have been in archive for less than 90 days. If you must delete images that have been archived for less than 90 days, you need to use the **batch-delete-image** API, but you will be charged for the 90-day minimum storage duration.
When you describe images using the **describe-images** command, archived images have an `image-status` of `ARCHIVED`. You can filter images by `image-status` to view only archived images or only active images.
# Restoring an image
When you restore an archived image, it is moved from the ECR Archive storage class back to the ECR Standard storage class. Restored images are charged at the standard storage rates. The restore process performs similar actions that occur when a new image is created:
+ The image becomes available for pulling when the restore is complete. Restore typically takes up to 20 minutes, though it may complete faster.
+ If scan on push is enabled for the repository, the restored image will be scanned. Note that previous scan results from before the image was archived will not be available.
+ If replication is configured for the repository, the restored image will be replicated if replication was enabled at the time of restore.
+ The restored image appears in the active images list.
Restoring an image typically takes up to 20 minutes, though it may complete faster. During the restore process, the image remains in the archived state and cannot be pulled until the restore completes.
------
#### [ AWS Management Console ]
**To restore an archived image**
1. Open the Amazon ECR console at [https://console.aws.amazon.com/ecr/repositories](https://console.aws.amazon.com/ecr/repositories).
1. From the navigation bar, choose the Region that contains the repository with the archived image you want to restore.
1. In the navigation pane, choose **Repositories**.
1. On the **Repositories** page, choose the repository containing the archived image.
1. Choose the **Archived images** tab.
1. Select the archived image you want to restore.
1. Choose **Restore** and confirm the restore action.
1. Wait for the restore to complete. The image will appear in the active images list once restoration is complete.
------
#### [ AWS CLI ]
**To restore an archived image**
+ Use the **update-image-storage-class** command to restore an archived image by updating its storage class to `STANDARD`:
```
aws ecr update-image-storage-class \
--repository-name my-repository \
--image-id imageDigest=sha256:4f70ef7a4d29e8c0c302b13e25962d8f7a0bd304EXAMPLE \
--target-storage-class STANDARD
```
------
When you describe images using the **describe-images** command, images that are being restored have an `image-status` of `ACTIVATING`. You can filter images by `image-status` with the value `ACTIVATING` to view images that are currently being restored.
An alternative method to restore an archived image is to re-push the image to the repository. When you push an image that is currently archived, that image will be immediately restored and removed from the archive.
# Retagging an image in Amazon ECR
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.
## To retag an image (AWS CLI)
**To retag an image with the AWS CLI**
1. Use the **batch-get-image** command to get the image manifest for the image to retag and write it to a file. In this example, the manifest for an image with the tag, *latest*, in the repository, *amazonlinux*, is written to an environment variable named *MANIFEST*.
```
MANIFEST=$(aws ecr batch-get-image --repository-name amazonlinux --image-ids imageTag=latest --output text --query 'images[].imageManifest')
```
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*.
**Note**
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*.
```
aws ecr put-image --repository-name amazonlinux --image-tag 2017.03 --image-manifest "$MANIFEST"
```
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`.
```
aws ecr describe-images --repository-name amazonlinux
```
The output is as follows:
```
{
"imageDetails": [
{
"imageSizeInBytes": 98755613,
"imageDigest": "sha256:8d00af8f076eb15a33019c2a3e7f1f655375681c4e5be157a26EXAMPLE",
"imageTags": [
"latest",
"2017.03"
],
"registryId": "aws_account_id",
"repositoryName": "amazonlinux",
"imagePushedAt": 1499287667.0
}
]
}
```
## To retag an image (AWS Tools for Windows PowerShell)
**To retag an image with the AWS Tools for Windows PowerShell**
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, *\$1Image* .
**Note**
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 PowerShell User Guide*.
```
$Image = Get-ECRImageBatch -ImageId @{ imageTag="latest" } -RepositoryName amazonlinux
```
1. Write the manifest of the image to the *\$1Manifest* environment variable.
```
$Manifest = $Image.Images[0].ImageManifest
```
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*.
```
Write-ECRImage -RepositoryName amazonlinux -ImageManifest $Manifest -ImageTag 2017.09
```
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`.
```
Get-ECRImage -RepositoryName amazonlinux
```
The output is as follows:
```
ImageDigest ImageTag
----------- --------
sha256:359b948ea8866817e94765822787cd482279eed0c17bc674a7707f4256d5d497 latest
sha256:359b948ea8866817e94765822787cd482279eed0c17bc674a7707f4256d5d497 2017.09
```
# Preventing image tags from being overwritten in Amazon ECR
You can prevent image tags from being overwritten by turning on tag immutability in a repository. After tag immutability is turned on, the ` ImageTagAlreadyExistsException` error is returned if you push an image with a tag that is already in the repository. Tag immutability affects all tags. You cannot make some tags immutable while others aren't.
You can use the AWS Management Console and AWS CLI tools to set image tag mutability for a new repository or for an existing repository. To create a repository using console steps, see [Creating an Amazon ECR private repository to store images](repository-create.md).
## Setting image tag mutability (AWS Management Console)
**To set image tag mutability**
1. Open the Amazon ECR console at [https://console.aws.amazon.com/ecr/repositories](https://console.aws.amazon.com/ecr/repositories).
1. From the navigation bar, choose the Region that contains the repository to edit.
1. In the navigation pane, choose **Repositories** under **Private registry**.
If you don't see **Repositories**, choose **Private registry** to expand the menu and then choose ** Repositories**.
1. On the **Private repositories** page, choose the radio button before the repository name for which you want to set the image tag mutability settings.
1. Choose **Actions** and then choose **Repository** under **Edit**.
1. For **Image tag immutability**, choose one of the following tag mutability settings for the repository.
+ **Mutable** – Choose this option if you want image tags to be overwritten. Recommended for repositories using pull through cache actions to ensure Amazon ECR can update cached images. Additionally, to disable tag updates for a few mutable tags, enter tag names or use wildcards (\$1) to match multiple similar tags in the **Mutable tag exclusion** text box.
+ **Immutable** – Choose this option if you want to prevent image tags from being overwritten, and it applies to all tags and exclusions in the repository when pushing an image with existing tag. Amazon ECR returns an `ImageTagAlreadyExistsException` if you attempt to push an image with an existing tag. Additionally, to enable tag updates for a few immutable tags, enter tag names or use wildcards (\$1) to match multiple similar tags in the **Immutable tag exclusion** text box.
1. For **Image scan settings**, while you can specify the scan settings at the repository level for basic scanning, it is best practice to specify the scan configuration at the private registry level. Specify the scanning settings at the private registry allow you to enable either enhanced scanning or basic scanning as well as define filters to specify which repositories are scanned. For more information, see [Scan images for software vulnerabilities in Amazon ECR](image-scanning.md).
1. For **Encryption settings**, this is a view only field as the encryption settings for a repository can't be changed once the repository is created.
1. Choose **Save** to update the repository settings.
## Setting image tag mutability (AWS CLI)
**To create a repository with immutable tags configured**
Use one of the following commands to create a new image repository with immutable tags configured.
+ [create-repository](https://docs.aws.amazon.com/cli/latest/reference/ecr/create-repository.html) (AWS CLI) with image tag mutability
```
aws ecr create-repository --repository-name name --image-tag-mutability IMMUTABLE --region us-east-2
```
+ [create-repository](https://docs.aws.amazon.com/cli/latest/reference/ecr/create-repository.html) (AWS CLI) with image tag mutability exclusion filters
```
aws ecr create-repository --repository-name name --image-tag-mutability IMMUTABLE_WITH_EXCLUSION --image-tag-mutability-exclusion-filters filterType=WILDCARD,filter=filter-text --region us-east-2
```
+ [New-ECRRepository](https://docs.aws.amazon.com/powershell/latest/reference/items/New-ECRRepository.html) (AWS Tools for Windows PowerShell) with image tag mutability
```
New-ECRRepository -RepositoryName name -ImageTagMutability IMMUTABLE -Region us-east-2 -Force
```
+ [New-ECRRepository](https://docs.aws.amazon.com/powershell/latest/reference/items/New-ECRRepository.html) (AWS Tools for Windows PowerShell) with image tag mutability exclusion filters
```
New-ECRRepository -RepositoryName name -ImageTagMutability IMMUTABLE_WITH_EXCLUSION -ImageTagMutabilityExclusionFilter @{FilterType=WILDCARD Filter=filter-text} -Region us-east-2 -Force
```
**To update the image tag mutability settings for a repository**
Use one of the following commands to update the image tag mutability settings for an existing repository.
+ [ put-image-tag-mutability](https://docs.aws.amazon.com/cli/latest/reference/ecr/put-image-tag-mutability.html) (AWS CLI) with image tag mutability
```
aws ecr put-image-tag-mutability --repository-name name --image-tag-mutability IMMUTABLE --region us-east-2
```
+ [ put-image-tag-mutability](https://docs.aws.amazon.com/cli/latest/reference/ecr/put-image-tag-mutability.html) (AWS CLI) with image tag mutability exclusion filters
```
aws ecr put-image-tag-mutability --repository-name name --image-tag-mutability IMMUTABLE_WITH_EXCLUSION --image-tag-mutability-exclusion-filters filterType=WILDCARD,filter=latest --region us-east-2
```
+ [ Write-ECRImageTagMutability](https://docs.aws.amazon.com/powershell/latest/reference/items/Write-ECRImageTagMutability.html) (AWS Tools for Windows PowerShell) with image tag mutability
```
Write-ECRImageTagMutability -RepositoryName name -ImageTagMutability IMMUTABLE -Region us-east-2 -Force
```
+ [ Write-ECRImageTagMutability](https://docs.aws.amazon.com/powershell/latest/reference/items/Write-ECRImageTagMutability.html) (AWS Tools for Windows PowerShell) with image tag mutability exclusion filters
```
Write-ECRImageTagMutability -RepositoryName name -ImageTagMutability IMMUTABLE_WITH_EXCLUSION -ImageTagMutabilityExclusionFilter @{FilterType=WILDCARD Filter=latest}
```
# Container image manifest format support in Amazon ECR
Amazon ECR supports the following container image manifest formats:
+ Docker Image Manifest V2 Schema 1 (used with Docker version 1.9 and older)
+ Docker Image Manifest V2 Schema 2 (used with Docker version 1.10 and newer)
+ Open Container Initiative (OCI) Specifications (v1.0 and v1.1)
Support for Docker Image Manifest V2 Schema 2 provides the following functionality:
+ The ability to use multiple tags for a singular image.
+ Support for storing Windows container images.
## Amazon ECR image manifest conversion
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.
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.
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*:
| Schema requested by client | Pushed to ECR as V2, schema 1 | Pushed to ECR as V2, schema 2 | Pushed to ECR as OCI |
| --- | --- | --- | --- |
| V2, schema 1 | No translation required | Translated to V2, schema 1 | No translation available |
| V2, schema 2 | No translation available, client falls back to V2, schema 1 | No translation required | Translated to V2, schema 2 |
| OCI | No translation available | Translated to OCI | No translation required |
**Important**
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.
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.
# Using Amazon ECR images with Amazon ECS
You can use your Amazon ECR private repositories to host container images and artifacts that your Amazon ECS tasks may pull from. For this to work, the Amazon ECS, or Fargate, container agent must have permissions to make the `ecr:BatchGetImage`, `ecr:GetDownloadUrlForLayer`, and `ecr:GetAuthorizationToken` APIs.
## Required IAM permissions
The following table shows the IAM role to use, for each launch type, that provides the required permissions for your tasks to pull from an Amazon ECR private repository. Amazon ECS provides managed IAM policies that include the required permissions.
****
| Launch type | IAM role | AWS managed IAM policy |
| --- | --- | --- |
| Amazon ECS on Amazon EC2 instances | Use the container instance IAM role, which is associated with the Amazon EC2 instance registered to your Amazon ECS cluster. For more information, see [Container instance IAM role](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/instance_IAM_role.html) in the *Amazon Elastic Container Service Developer Guide*. | `AmazonEC2ContainerServiceforEC2Role` For more information, see [https://docs.aws.amazon.com/AmazonECS/latest/developerguide/security-iam-awsmanpol.html#security-iam-awsmanpol-AmazonEC2ContainerServiceforEC2Role](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/security-iam-awsmanpol.html#security-iam-awsmanpol-AmazonEC2ContainerServiceforEC2Role) in the *Amazon Elastic Container Service Developer Guide* |
| Amazon ECS on Fargate | Use the task execution IAM role that you reference in your Amazon ECS task definition. For more information, see [Task execution IAM role](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_execution_IAM_role.html) in the *Amazon Elastic Container Service Developer Guide*. | `AmazonECSTaskExecutionRolePolicy` For more information, see [https://docs.aws.amazon.com/AmazonECS/latest/developerguide/security-iam-awsmanpol.html#security-iam-awsmanpol-AmazonECSTaskExecutionRolePolicy](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/security-iam-awsmanpol.html#security-iam-awsmanpol-AmazonECSTaskExecutionRolePolicy) in the *Amazon Elastic Container Service Developer Guide*. |
| Amazon ECS on external instances | Use the container instance IAM role, which is associated with the on-premises server or virtual machine (VM) registered to your Amazon ECS cluster. For more information, see [Container instance Amazon ECS role](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/instance_IAM_role.html) in the *Amazon Elastic Container Service Developer Guide*. | `AmazonEC2ContainerServiceforEC2Role` For more information, see [https://docs.aws.amazon.com/AmazonECS/latest/developerguide/security-iam-awsmanpol.html#security-iam-awsmanpol-AmazonEC2ContainerServiceforEC2Role](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/security-iam-awsmanpol.html#security-iam-awsmanpol-AmazonEC2ContainerServiceforEC2Role) in the *Amazon Elastic Container Service Developer Guide*. |
**Important**
The AWS managed IAM policies contain additional permissions that you may not require for your use. In this case, these are the minimum required permissions to pull from an Amazon ECR private repository.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ecr:BatchGetImage",
"ecr:GetDownloadUrlForLayer",
"ecr:GetAuthorizationToken"
],
"Resource": "*"
}
]
}
```
## Specifying an Amazon ECR image in an Amazon ECS task definition
When creating an Amazon ECS task definition, you can specify a container image hosted in an Amazon ECR private repository. In the task definition, ensure that you use the full `registry/repository:tag` naming for your Amazon ECR images. For example, `aws_account_id.dkr.ecr.region.amazonaws.com``/my-repository:latest`.
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.
```
{
"family": "task-definition-name",
...
"containerDefinitions": [
{
"name": "container-name",
"image": "aws_account_id.dkr.ecr.region.amazonaws.com/my-repository:latest",
...
}
],
...
}
```
# Using Amazon ECR Images with Amazon EKS
You can use your Amazon ECR images with Amazon EKS.
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-repository:latest`.
## Required IAM permissions
If you have Amazon EKS workloads hosted on managed nodes, self-managed nodes, or AWS Fargate, review the following:
+ Amazon EKS workloads hosted on managed or self-managed nodes: The Amazon EKS worker node IAM role (`NodeInstanceRole`) is required. The Amazon EKS worker node IAM role must contain the following IAM policy permissions for Amazon ECR.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ecr:BatchCheckLayerAvailability",
"ecr:BatchGetImage",
"ecr:GetDownloadUrlForLayer",
"ecr:GetAuthorizationToken"
],
"Resource": "*"
}
]
}
```
------
**Note**
If you used `eksctl` or the 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.
+ Amazon EKS workloads hosted on AWS Fargate: Use the Fargate pod execution role, which provides your pods permission to pull images from private Amazon ECR repositories. For more information, see [Create a Fargate pod execution role](https://docs.aws.amazon.com/eks/latest/userguide/fargate-getting-started.html#fargate-sg-pod-execution-role).
# Installing a Helm chart on an Amazon EKS cluster
Helm charts hosted in Amazon ECR can be installed on your Amazon EKS clusters.
**Prerequisites**
+ Install the latest version of the Helm client. These steps were written using Helm version `3.9.0`. For more information, see [Installing Helm](https://helm.sh/docs/intro/install/).
+ You have at least version `1.23.9` or `2.6.3` of the AWS CLI installed on your computer. For more information, see [Installing or updating the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
+ You have pushed a Helm chart to your Amazon ECR repository. For more information, see [Pushing a Helm chart to an Amazon ECR private repository](push-oci-artifact.md).
+ 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.
```
kubectl get svc
```
**To install a Helm chart on an Amazon EKS cluster**
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 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. Install the chart. Replace *helm-test-chart* with your repository and *0.1.0* with your Helm chart's tag.
```
helm install ecr-chart-demo oci://aws_account_id.dkr.ecr.region.amazonaws.com/helm-test-chart --version 0.1.0
```
The output should look similar to this:
```
NAME: ecr-chart-demo
LAST DEPLOYED: Tue May 31 17:38:56 2022
NAMESPACE: default
STATUS: deployed
REVISION: 1
TEST SUITE: None
```
1. Verify the chart installation.
```
helm list -n default
```
Example output:
```
NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION
ecr-chart-demo default 1 2022-06-01 15:56:40.128669157 +0000 UTC deployed helm-test-chart-0.1.0 1.16.0
```
1. (Optional) See the installed Helm chart `ConfigMap`.
```
kubectl describe configmap helm-test-chart-configmap
```
1. When you are finished, you can remove the chart release from your cluster.
```
helm uninstall ecr-chart-demo
```