Skip to main content

Proxying Images for Helm Installations

This topic describes how to use the Replicated proxy service to proxy images for installations with Helm. For more information about the proxy service, see About Proxying Images with Replicated.

Overview

With the Replicated proxy service, each customer's unique license can grant proxy access to images in an external private registry. To enable the proxy service for Helm installations, you must create a Secret with type: kubernetes.io/dockerconfigjson to authenticate with the proxy service. During Helm installations, after customers provide their license ID, a global.replicated.dockerconfigjson field that contains a base64 encoded Docker configuration file is automatically injected in the Helm chart values. You use this global.replicated.dockerconfigjson field to create the required pull secret.

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.

Prerequisites

  • Provide read-only credentials for the external private registry in your Replicated account. This allows Replicated to access the images through the proxy service. See Add Credentials for an External Registry in Connecting to an External Registry.
  • (Optional) Add a custom domain for the proxy service instead of proxy.replicated.com. See Using Custom Domains.

Deliver Image Pull Secrets for the Proxy Service

To create an image pull secret to enable the proxy service for Helm installations:

  1. In your Helm chart templates, create a Kubernetes Secret to evaluate if the global.replicated.dockerconfigjson value is set, and then write the rendered value into a Secret on the cluster:

    # /templates/replicated-pull-secret.yaml

    {{ if .Values.global.replicated.dockerconfigjson }}
    apiVersion: v1
    kind: Secret
    metadata:
    name: replicated-pull-secret
    type: kubernetes.io/dockerconfigjson
    data:
    .dockerconfigjson: {{ .Values.global.replicated.dockerconfigjson }}
    {{ end }}
    note

    If you use the Replicated SDK, do not use replicated for the name of the image pull secret because the SDK automatically creates a Secret named replicated. Using the same name causes an error.

  2. Ensure that you have a field in your Helm chart values file for your image repository URL, and that any references to the image in your Helm chart access the field from your values file.

    Example:

    # values.yaml
    ...
    images:
    myapp:
    # Add image URL in the values file
    apiImageRepository: quay.io/my-org/api
    apiImageTag: v1.0.1
    # /templates/deployment.yaml

    apiVersion: apps/v1
    kind: Deployment
    metadata:
    name: example
    spec:
    template:
    spec:
    containers:
    - name: api
    # Access the apiImageRepository field from the values file
    image: {{ .Values.images.myapp.apiImageRepository }}:{{ .Values.images.myapp.apiImageTag }}
  3. In your Helm chart templates, add the image pull secret that you created to any manifests that reference the private image:

    # /templates/example.yaml
    ...
    {{ if .Values.global.replicated.dockerconfigjson }}
    imagePullSecrets:
    - name: replicated-pull-secret
    {{ end }}

    Example:

    # /templates/deployment.yaml
    ...
    image: "{{ .Values.images.myapp.apiImageRepository }}:{{ .Values.images.myapp.apiImageTag }}"
    {{ if .Values.global.replicated.dockerconfigjson }}
    imagePullSecrets:
    - name: replicated-pull-secret
    {{ end }}
    name: myapp
    ports:
    - containerPort: 3000
    name: http
  4. Package your Helm chart and add it to a release. Promote the release to a development channel. See Managing Releases with Vendor Portal.

  5. Install the chart in a development environment to test your changes:

    1. Create a local values.yaml file to override the default external registry image URL with the URL for the image on proxy.replicated.com.

      The proxy service URL has the following format: proxy.replicated.com/proxy/APP_SLUG/EXTERNAL_REGISTRY_IMAGE_URL

      Where:

      • APP_SLUG is the slug of your Replicated application.
      • EXTERNAL_REGISTRY_IMAGE_URL is the path to the private image on your external registry.

      Example

      # A local values.yaml file
      ...
      images:
      myapp:
      apiImageRepository: proxy.replicated.com/proxy/my-app/quay.io/my-org/api
      apiImageTag: v1.0.1

      note

      If you configured a custom domain for the proxy service, use the custom domain instead of proxy.replicated.com. For more information, see Using Custom Domains.

    2. Log in to the Replicated registry and install the chart, passing the local values.yaml file you created with the --values flag. See Installing with Helm.