Skip to main content

About Proxying Images with Replicated

This topic describes using the Replicated proxy service to grant proxy access to your application's private images. It also includes information about how Replicated KOTS accesses images through the proxy service.

About the Proxy Service​

If your application images are available in a private image registry exposed to the Internet, such as Docker Hub or Amazon Elastic Container Registry (ECR), then the Replicated proxy service can grant proxy, or pull-through, access to the images without exposing registry credentials to your customers. When you use the proxy service, you do not have to modify the process that you already use to build and push images to deploy your application with Replicated.

To grant proxy access, the proxy service uses the customer licenses that you create in the Replicated vendor portal. This allows you to revoke a customer’s ability to pull private images by editing their license, rather than having to manage image access through separate identity or authentication systems. For example, when a trial license expires, the customer's ability to pull private images is automatically revoked.

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

Proxy service workflow diagram

View a larger version of this image

How to Enable the Proxy Service​

The proxy service requires the following to grant proxy access to your images:

  • Read-only credentials to your private registry. For information about how to provide registry credentials, see Connecting to an External Registry.

  • An image pull Secret with type: kubernetes.io/dockerconfigjson. For KOTS installations, the required Secret is automatically created in the application namespace during installation or upgrade using the customer's license. For more information, see How KOTS Accesses Images Through the Proxy Service.

    For Helm installations, you use a value that is automatically injected into the Helm chart values.yaml during installation to create the Secret. For more information about delivering image pull Secrets for Helm installations, see Proxying Images for Helm Installations.

You can also optionally use a custom domain for the proxy service instead of proxy.replicated.com. For more information, see Using Custom Domains.

How KOTS Accesses Images Through the Proxy Service​

This section describes how KOTS uses the customer license during installation 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 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 quay.io/my-org/api:v1.0.1:

  apiVersion: apps/v1
  kind: Deployment
  metadata:
    name: example
  spec:
    template:
      spec:
        containers:
          - name: api
            image: quay.io/my-org/api:v1.0.1

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

  apiVersion: kustomize.config.k8s.io/v1beta1
  bases:
  - ../../base
  images:
  - name: quay.io/my-org/api:v1.0.1
    newName: proxy.replicated.com/proxy/my-kots-app/quay.io/my-org/api

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 with type: kubernetes.io/dockerconfigjson that is based on the customer license. KOTS uses this secret to authenticate and pull private images from proxy.replicated.com.

For information about how Kubernetes uses the kubernetes.io/dockerconfigjson Secret type to authenticate to a private image registry, see Pull an Image from a Private Registry in the Kubernetes documentation.

KOTS does not patch the image location URL for images hosted on the Replicated registry at registry.replicated.com. However, KOTS adds the same imagePullSecret to PodSpecs that reference images in the Replicated registry. For more information about using the Replicated registry, see Using the Replicated Registry for KOTS Installations.

note

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.