Skip to main content

About Using an External Registry

This topic provides information about how Replicated KOTS accesses images when you connect an external private registry.

About the Proxy Service

If your application images are available in a private image registry exposed to the Internet, such as Docker Hub, Amazon Elastic Container Registry (ECR), or Google Container Registry (GCR), then the customer licenses for your application can grant proxy, or pull-through, access to the assignee without exposing registry credentials to the customer.

With proxy access, KOTS can use the Replicated registry proxy service to pull private images from an external registry. Instances of your application can then pull private images from the proxy service at during deployment. KOTS determines what images are private by attempting to fetch image metadata. If the request is forbidden, KOTS pulls the image through instead of pulling the image directly from an external registry.

Connecting KOTS to your external registry through a proxy is useful and recommended because it prevents you from having to modify the process you use to build and push application images in order to deploy your application with Replicated.

It also allows you to revoke a customer’s ability to pull private images without having to manage image access through separate identity or authentication systems. For example, when you connect KOTS to your external image registry, a customer's ability to pull private images is automatically revoked when their trial license expires.

The following diagram demonstrates how the registry proxy service pulls images from your external registry, and how deployed instances of your application pull images from the proxy service:

Registry proxy service workflow diagram

View a larger version of this image

How KOTS Accesses Private Images

KOTS uses Kustomize to change the location of the private image registry in the PodSpec during application deployment from the external registry domain to the Replicated proxy service domain. It then creates an imagePullSecret to access the images through the proxy service.

Patching the Image Location with Kustomize

When KOTS is installing an application, it attempts to load image manifests using the image reference from the PodSpec. If KOTS receives a 401 response, it assumes that this is a private image that must be proxied through the registry proxy service.

KOTS uses Kustomize to patch the midstream/kustomization.yaml file to change the image name during deployment to reference the proxy service.

For example, a PodSpec for a Deployment references a private image hosted at

  apiVersion: apps/v1
kind: Deployment
name: example
- name: api

When this application is deployed, KOTS detects that it cannot access the image at So, it creates a patch in the midstream/kustomization.yaml file that changes the image name in all manifest files for the application:

- ../../base
- name:

This causes the container runtime in the cluster to use the proxy service to pull the images, using the license information provided to KOTS for authentication.

Accessing the Proxy Service with an Image Pull Secret

During installation, KOTS automatically creates an imagePullSecret that is based on the customer license. KOTS uses this secret to authenticate and pull private images from

KOTS does not patch the image location URL for images hosted on the Replicated private registry at However, KOTS adds the same imagePullSecret to PodSpecs that reference images in the Replicated private registry.


When deploying Pods to namespaces other than the application namespace, you must add the namespace to the additionalNamespaces attribute of the Application custom resource manifest. This ensures that KOTS can provision the imagePullSecret in the namespace to allow the Pod to pull the image. For more information about the additionalNamespaces attribute, see Defining Additional Namespaces.