Skip to main content

Using ECR for Private Images

The Replicated app manager supports working with private images stored in Amazon's Elastic Container Registry (ECR).


The purpose of this guide is to walk you through a hello-world example on how to configure Replicated to pull images from a private registry in Amazon's Elastic Container Registry (ECR).

Prerequisites & Assumptions

This power-user's guide assumes you have completed the Replicated product installation tutorials without an existing cluster or the using the CLI, as this guide is a continuation of those tutorials.

As with the previous tutorials, we will also need a virtual machine (VM) to install the application with the following minimum requirements:

  • Ubuntu 18.04
  • At least 8 GB of RAM
  • 4 CPU cores
  • At least 40GB of disk space

We are going to focus on the difference between using a public image versus a private image in Replicated. To do this, we'll pull the public NGINX container and then push it to a private repository in ECR.

This means we'll need:

  • An ECR Repository
  • An AWS Account to use with Docker to pull and push the public NGINX image to the ECR repository
  • Docker
  • The AWS CLI

Later in the guide we will configure Replicated to pull from the ECR repository using a read-only account. To do this we'll need to make sure the above AWS account can also create this user.


The guide is divided into the following steps:

  1. Set Up the Testing Environment

  2. Configure Private Registries in Replicated

  3. Update Definition Files

  4. Install the New Version

1. Set Up the Testing Environment

We are going to use the default NGINX deployment to create our application and then update it to pull the same container from a private repository in ECR and note the differences.

Create Sample Application and deploy the first release

In this section, we cover at a high level the steps to create a new application and install it on a VM. As mentioned earlier, it is assumed that you have completed the Replicated product installation tutorials without an existing cluster or the using the CLI, which cover these steps in detail.

To create our sample application follow these steps:

  • Create a new application in the Replicated vendor portal and call it 'MySampleECRApp'.
  • Create the first release using the default definition files and promote it to the unstable channel.
  • Create a customer, assign it to the Unstable channel and download the license file after creating the customer.
  • Install the application to a VM

Log in to the Replicated admin console. To inspect what was deployed, look at the files under View Files from the admin console. In the Upstream files (files from the release created in the vendor portal) show that we are pulling the public image.


We can further validate this if we switch back to the terminal window on the VM where we installed the application. If we run kubectl describe pod <pod-name> on the NGINX pod, we can confirm that it was in fact pulled from the public repository.


Now that we have the basic application installed, we are now going to pull the same image, but from an ECR repository.

Pull Public Image and Push to ECR

To keep the changes to a minimum and only focus on using a private registry, we are going to pull the public NGINX container (as specified in the deployment.yaml file) to our local environment, and then push it to a repository in ECR. To use docker login with ECR, we will need to configure AWS CLI with the AWS Access Key ID and AWS Secret Key for this user.

Let's start by pulling the public image:

$ docker pull nginx

You should have an output similar to this:

Using default tag: latest
latest: Pulling from library/nginx
d121f8d1c412: Pull complete
ebd81fc8c071: Pull complete
655316c160af: Pull complete
d15953c0e0f8: Pull complete
2ee525c5c3cc: Pull complete
Digest: sha256:c628b67d21744fce822d22fdcc0389f6bd763daac23a6b77147d0712ea7102d0
Status: Downloaded newer image for nginx:latest

Next, log in to ECR and push this container. To use docker login with ECR, install the AWS CLI and configure it if not already done. As part of this, we will need to provide the AWS Access Key ID and AWS Secret Key for a user that has permissions to create and push images to the repository. For more information about working with containers and ECR in the AWS CLI, see Using Amazon ECR with the AWS CLI.

Just like with any other private registry, we need to know the registry endpoint to pass the docker login command. The syntax is as follows:

docker login [some.private.registry]:[port]

In this case, the endpoint is the [some.private.registry]:[port]

To determine the endpoint for ECR, log in to the AWS console and search for 'ECR', which should bring up Elastic Container Registry as an option as shown below.


Select 'Elastic Container Registry' from the options in the dropdown to get to the list of repositories.


As you can see from the screenshot above, you can see the endpoints for each repository under the URI column. For the purpose of this guide, we will push the NGINX image to the demo-apps repository.

To determine the endpoint to use in the login command, use the URL without the repository name.

When logging in to ECR, use the AWS CLI to the user credentials. For example, to log in to ECR, we run the following command:

$ aws ecr get-login-password --region us-east-2 | docker login --username AWS --password-stdin

A successful login will display a Login Succeeded message. To push this image to our private repository, tag the image. The new tag will consist of:

<ecr repoendpoint>/image

For example, to tag the public NGINX image, we run the following command:

$ docker tag nginx

Assuming the tagging is successful, push the container to our ECR repository:

$ docker push      
The push refers to repository []
908cf8238301: Pushed
eabfa4cd2d12: Pushed
60c688e8765e: Pushed
f431d0917d41: Pushed
07cab4339852: Pushed
latest: digest: sha256:794275d96b4ab96eeb954728a7bf11156570e8372ecd5ed0cbc7280313a27d19 size: 1362

Our testing environment is all set. We are now ready to update Replicated to use the private registry.

2. Configure Private Registries in Replicated

To configure a Private Registry in Replicated, we need to provide the same information we needed to login to ECR in the previous step:

  • Endpoint
  • Username
  • Password

The difference is that we'll use a different user than the one we used previously. Since Replicated only needs to pull images, it is a best practice to create a 'read-only' user for this specific purpose.

Determine the endpoint

The endpoint should be the same as the one we provided in the previous step.

Setting up the Service Account User

Replicated only needs access to pull images from the private registry. Let's create a new user in AWS:


As far as permissions go, there are a couple of options, depending on scope of access. If exposing all images to Replicated is an acceptable solution, the Amazon-provided AmazonEC2ContainerRegistryReadOnly policy will work:

"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"Resource": "*"

If you wish to limit Replicated to only certain images, this policy should be used instead:

"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"Resource": [
"Version": "2012-10-17",
"Statement": [
"Effect": "Allow",
"Action": [
"Resource": "*"

We will need the AWS Access Key ID and AWS Secret Key in the next section as these will map to the Username and Password fields. You can obtain these as you create the user or after the user has been created.

Enter Registry Information in Replicated

First, we must link Replicated with the registry. To do this, click on Add External Registry from the Images tab.


The values for the fields are:

Endpoint: Enter the same URL used to log in to ECR. For example, to link to the same registry as the one in the section, we would enter

Username: Enter the AWS Access Key ID for the user created in the Setting Up the Service Account User section.

Password: Enter the AWS Secret Key for the user created in the Setting Up the Service Account User section.

3. Update Definition Files

Last step is to update our definition manifest to pull the image from the ECR repository. To do this, we'll update the deployment.yaml file by adding the ECR registry URL to the image value. Below is an example using the registry URL used in this guide.

- name: nginx
- image: nginx
+ image:

Save your changes and create the new release and promote it to the Unstable channel.

4. Install the New Version

To deploy the new version of the application, go back to the admin console and select the Version History tab. Click on Check for Updates and then Deploy when the new version is listed. To confirm that the new version was in fact installed, it should look like the screenshot below.


Now, we can inspect to see the changes in the definition files. Looking at the deployment.yaml upstream file, we see the image path as we set it in the Update Definition Files section.


Since the app manager is able to detect that it cannot pull this image anonymously, it then tries to proxy the private registries configured. Looking at the kustomization.yaml downstream file we can see that the image path is changed to use the Replicated proxy.


The install of the new version should have created a new pod. If we run kubectl describe pod on the new NGINX pod, we can confirm that the image was in fact pulled from the ECR repository.


Additional resources