Use the Proxy Registry with Replicated Installers

This topic describes how to use the Replicated proxy registry with applications deployed with Replicated installers (Embedded Cluster, KOTS existing cluster, or kURL).

Overview

For installations that use a Replicated installer, KOTS automatically creates the required image pull secret for accessing the Replicated proxy registry during application deployment. When possible, KOTS also automatically rewrites image names in the application manifests to the location of the image at proxy.replicated.com or your custom domain.

Configure Your Application to Use the Proxy Registry

There are different methods for configuring your application to use the proxy registry depending on how your application is packaged and the installation method.

HelmChart v2

This section describes how to configure your application to use the proxy registry HelmChart v2 installations.

To use the proxy registry with HelmChart v2 installations:

1. In the Vendor Portal, go to Images > Add external registry and provide read-only credentials for your registry. This allows Replicated to access the images through the proxy registry. See Add Credentials for an External Registry in Connecting to an External Registry.

   

2. (Recommended) Go to Custom Domains > Add custom domain and add a custom domain for the proxy registry. See Use Custom Domains.

3. In your Helm chart values file, set your image repository URL to the location of the image on the proxy registry. If you added a custom domain, use your custom domain. Otherwise, use proxy.replicated.com.

   The proxy registry URL has the following format: DOMAIN/proxy/APP_SLUG/EXTERNAL_REGISTRY_IMAGE_URL

   Where:

   • DOMAIN is either proxy.replicated.com or your custom domain.
   • APP_SLUG is the unique slug of your application.
   • EXTERNAL_REGISTRY_IMAGE_URL is the path to the private image on your external registry.

   Example:

   # values.yaml
   api:
     image:
       # proxy.registry.com or your custom domain
       registry: ghcr.io
       repository: proxy/app/ghcr.io/cloudnative-pg/cloudnative-pg
       tag: catalog-1.24.0

   Ensure that any references to the image in your Helm chart access the field from your values file.

   Example:

   apiVersion: v1
   kind: Pod
   spec:
     containers:
       - name: api 
           # Access the registry, repository, and tag fields from the values file
           image: {{ .Values.images.api.registry }}/{{ .Values.images.api.repository }}:{{ .Values.images.api.tag }}

4. Provide authentication for the proxy registry by configuring the HelmChart v2 to inject a Replicated image pull secret into your Helm values. Use the KOTS ImagePullSecretName template function to get the pull secret name.

   What is the Replicated image pull secret?

   During application deployment, KOTS automatically creates an imagePullSecret with type: kubernetes.io/dockerconfigjson that is based on the customer license. This secret is used to authenticate with the proxy registry and grant proxy access to private images. 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.

   Example:

   # kots.io/v1beta2 HelmChart custom resource
   
   apiVersion: kots.io/v1beta2
   kind: HelmChart
   metadata:
     name: samplechart
   spec:
     values:
       image: 
         # Get the pull secret name with ImagePullSecretName
         pullSecrets:
           - name: '{{repl ImagePullSecretName }}'

   Ensure that you provide this pull secret in any Pod definitions that reference images to be pulled through the proxy registry.

   Example:

   apiVersion: v1
   kind: Pod
   metadata:
     name: nginx
   spec:
     containers:
     - name: nginx
       image: {{ .Values.image.registry }}/{{ .Values.image.repository }}
     # Access the value to provide the KOTS pull secret
     {{- with .Values.image.pullSecrets }}
     imagePullSecrets:
     {{- toYaml . | nindent 2 }}
     {{- end }}

5. If you are deploying Pods to namespaces other than the application namespace, add the namespace to the additionalNamespaces attribute of the KOTS Application custom resource. This ensures that KOTS can provision the imagePullSecret in the namespace to allow the Pod to pull the image. For instructions, see Define Additional Namespaces.

6. Create a new release with your changes. Promote the release to a development channel. See Managing Releases with Vendor Portal.

7. Install in a development environment to test your changes.

HelmChart v1 or Standard Manifests

For standard manifest-based applications or Helm charts deployed with the HelmChart v1 custom resource, no additional configuration is required. KOTS automatically rewrites image names and injects image pull secrets during deployment for these application types.

note

The HelmChart custom resource apiVersion: kots.io/v1beta1 is deprecated. For installations with Replicated KOTS v1.99.0 and later, use the HelmChart custom resource with apiVersion: kots.io/v1beta2 instead. See HelmChart v2 and Confguring the HelmChart Custom Resource v2.

How does KOTS patch image names?

For applications packaged with standard Kubernetes manifests (or Helm charts deployed with the HelmChart v1 custom resource), KOTS automatically patches image names to the location of the image at at proxy.replicated.com or your custom domain during deployment. If KOTS receives a 401 response when attempting to load image manifests using the image reference from the PodSpec, it assumes that this is a private image that must be proxied through the proxy registry.

KOTS uses Kustomize to patch the midstream/kustomization.yaml file to change the image name during deployment to reference the proxy registry. 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. This causes the container runtime in the cluster to use the proxy registry to pull the images, using the license information provided to KOTS for authentication.

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

To use the proxy registry with HelmChart v1 or applications packaged with tandard manifests:

1. In the Vendor Portal, go to Images > Add external registry and provide read-only credentials for your registry. This allows Replicated to access the images through the proxy registry. See Add Credentials for an External Registry in Connecting to an External Registry.

   

2. (Recommended) Go to Custom Domains > Add custom domain and add a custom domain for the proxy registry. See Use Custom Domains.

3. If you are deploying Pods to namespaces other than the application namespace, add the namespace to the additionalNamespaces attribute of the KOTS Application custom resource. This ensures that KOTS can provision the imagePullSecret in the namespace to allow the Pod to pull the image. For instructions, see Define Additional Namespaces.

4. Create a new release with your changes. Promote the release to a development channel. See Managing Releases with Vendor Portal.

5. Install in a development environment to test your changes.

Kubernetes Operators

To use the proxy registry with applications packaged as Kubernetes Operators:

1. In the Vendor Portal, go to Images > Add external registry and provide read-only credentials for your registry. This allows Replicated to access the images through the proxy registry. See Add Credentials for an External Registry in Connecting to an External Registry.

   

2. (Recommended) Go to Custom Domains > Add custom domain and add a custom domain for the proxy registry. See Use Custom Domains.

3. If you are deploying Pods to namespaces other than the application namespace, add the namespace to the additionalNamespaces attribute of the KOTS Application custom resource. This ensures that KOTS can provision the imagePullSecret in the namespace to allow the Pod to pull the image. For instructions, see Define Additional Namespaces.

4. For applications packaged with Kubernetes Operators, KOTS cannot modify pods that are created at runtime by the Operator. To support the use of private images in all environments, the Operator code should use KOTS functionality to determine the image name and image pull secrets for all pods when they are created. For instructions, see Reference Images in the Packaging Kubernetes Operators section.

5. Create a new release with your changes. Promote the release to a development channel. See Managing Releases with Vendor Portal.

6. Install in a development environment to test your changes.