> For the complete documentation index, see [llms.txt](https://docs.release.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.release.com/integrations/integrations-overview/aws-integration/private-aws-ecr-image-repository.md).
# Private ECR Repositories
If you are a self-hosted user, Release automatically integrates with AWS Elastic Container Registry (ECR) and creates a private Docker image repository in your AWS account when you [add an AWS integration](/integrations/integrations-overview/aws-integration.md).
The default ECR image repositories created by Release are private and images are only accessible by your AWS account and by our AWS IAM user. However, you may wish to deploy images from a different ECR repository, or even from an entirely different AWS account, to nodes in your Release environments.
In this guide, we'll add an ECR repository policy that allows Release's IAM user to pull Docker images from a private ECR repository in a different AWS account.
## How to find Release's AWS IAM ID and cluster region
First, you'll need to find Release's AWS IAM user ID and cluster region under [Account Settings > Clusters](/reference-documentation/account-settings/view-clusters.md).
Note down your Release AWS IAM ID and your cluster's AWS region.
In the example below, we'll use two example AWS accounts, `111111111111` as Release's IAM user, and `222222222222` as an external AWS account from which we'll pull an image.
## How to use an image from a different ECR repository
This abridged application template shows how you could use an image from AWS ECR for one of your services in Release:
```yaml
services:
- name: vendorapp
image: 222222222222.dkr.ecr.eu-west-2.amazonaws.com/vendorapp:latest
has_repo: false
static: false
```
By looking at the example image URL, you might notice that the image belongs to the AWS IAM user `222222222222` in the AWS region `eu-west-2`.
{% hint style="info" %}
For cross-account ECR access to work, the ECR repository must be in the same AWS region as your Release cluster. If your image repository is in a different region, you can use [image replication](https://docs.aws.amazon.com/AmazonECR/latest/userguide/registry-settings-examples.html) in ECR to copy images from one AWS region to another.
{% endhint %}
## How to grant Release's IAM user permissions to pull images from an external repository
To grant `111111111111` permissions to pull images from `222222222222`'s ECR repository, `222222222222` should add an ECR repository policy by following the steps below.
1. [Log in to AWS](https://console.aws.amazon.com/) using IAM ID `222222222222`.
2. Navigate to Amazon Elastic Container Registry.
1. Click on **Repositories** in the sidebar.
2. Select the repository that contains the image you would like to use.
3. Click the **Actions** dropdown.
4. Click **Permissions**.
1. Click **Edit policy JSON**.
1. Paste the following JSON (change `111111111111` to Release's IAM user ID):
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowReleasePull",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111111111111:root"
},
"Action": [
"ecr:BatchCheckLayerAvailability",
"ecr:BatchGetImage",
"ecr:DescribeImages",
"ecr:DescribeRepositories",
"ecr:GetAuthorizationToken",
"ecr:GetDownloadUrlForLayer",
"ecr:GetRepositoryPolicy",
"ecr:ListImages"
]
}
]
}
```
1. Click **Save**.
2. If AWS successfully validates your policy JSON, the permissions screen should look like this:
Now you can try to deploy your application again and Release's IAM user should have the required permissions to pull the image.
## How to configure Release's ECR private registry integration
To allow the private registry to be used as a `FROM` image in a Dockerfile built by Release, you'll also need to configure an ECR registry integration:
1. Navigate to **Account Settings > Integrations**
2. Click **Setup** under the AWS ECR private registry integration
3. Enter the ECR private registry hostname (e.g. `222222222222.dkr.ecr.eu-west-2.amazonaws.com`).
4. Choose the same cloud integration used in the [policy above](#how-to-grant-releases-iam-user-permissions-to-pull-images-from-an-external-repository).
5. Click **Save.**
Screenshot showing completed AWS ECR registry integration form
Now you can try to build your image again the release builder should have the required permissions to pull the base image.
## Security considerations
As with any AWS IAM policy update, it is important to make sure you understand what a policy does before applying it to your resources. This means making sure that you apply the policy to the correct ECR repository, using the correct external IAM user ID, and allowing only the necessary actions.
For convenience, we've listed the Actions from our recommended policy, with links to relevant documentation:
* [BatchCheckLayerAvailability](https://docs.aws.amazon.com/AmazonECR/latest/APIReference/API_BatchCheckLayerAvailability.html) - Checks the availability of one or more image layers in a repository.
* [BatchGetImage](https://docs.aws.amazon.com/AmazonECR/latest/APIReference/API_BatchGetImage.html) - Gets detailed information for an image.
* [DescribeImages](https://docs.aws.amazon.com/AmazonECR/latest/APIReference/API_DescribeImages.html) - Returns metadata about the images in a repository.
* [DescribeRepositories](https://docs.aws.amazon.com/AmazonECR/latest/APIReference/API_DescribeRepositories.html) - Describes image repositories in a registry.
* [GetAuthorizationToken](https://docs.aws.amazon.com/AmazonECR/latest/APIReference/API_GetAuthorizationToken.html) - Retrieves an authorization token.
* [GetDownloadUrlForLayer](https://docs.aws.amazon.com/AmazonECR/latest/APIReference/API_GetDownloadUrlForLayer.html) - Retrieves the pre-signed Amazon S3 download URL corresponding to an image layer.
* [GetRepositoryPolicy](https://docs.aws.amazon.com/AmazonECR/latest/APIReference/API_GetRepositoryPolicy.html) - Retrieves the repository policy for the specified repository.
* [ListImage](https://docs.aws.amazon.com/AmazonECR/latest/APIReference/API_ListImages.html) - Lists all the image IDs for the specified repository.
We also recommend reading the AWS documentation about [Private repository policies](https://docs.aws.amazon.com/AmazonECR/latest/userguide/repository-policies.html).
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.release.com/integrations/integrations-overview/aws-integration/private-aws-ecr-image-repository.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
