Use the Proxy Registry with Helm CLI Installations

This topic describes how to configure your application to use the Replicated proxy registry with Helm CLI installations. For more information about the proxy registry, see About the Replicated Proxy Registry. For more information about installing applications distributed with Replicated using Helm, see About Helm Installations with Replicated.

Overview

During Helm CLI installations with Replicated, after customers provide their unique license ID, a global.replicated.dockerconfigjson field that contains a base64 encoded Docker configuration file is automatically injected in the Helm chart values. For more information about how Kubernetes uses the kubernetes.io/dockerconfigjson Secret type to provide authentication for a private registry, see Pull an Image from a Private Registry in the Kubernetes documentation.

The Replicated SDK automatically uses this value to create an image pull secret named enterprise-pull-secret. You can configure your Helm chart to use enterprise-pull-secret to authenticate with the Replicated proxy registry so that your application images can be proxied.

note

The image used by the Replicated SDK is automatically proxied through the proxy registry. No additional configuration is required.

Prerequisite

Include the Replicated SDK version 1.15.0 or later as a dependency of your Helm chart. See Install the SDK as a Subchart in Install the Replicated SDK.

If you want to create your own pull secret instead of using the enterprise-pull-secret created by the SDK (such as if you manage the pull secret externally), see (Optional) Create Your Own Pull Secret on this page.

Configure Your Application to Use the Proxy Registry

To configure your application to use the proxy registry with Helm CLI installations:

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.
(Recommended) Go to Custom Domains > Add custom domain and add a custom domain for the proxy registry. See Use Custom Domains.
For each image reference in your Helm chart values file, set the image repository URL to the location of the image in the proxy registry.

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.replicated.com or your custom domain
    registry: proxy.replicated.com
    repository: proxy/your-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.image.api.registry }}/{{ .Values.image.api.repository }}:{{ .Values.image.api.tag }}
```

In your chart _helper.tpl, add the following Helm helper. This helper creates an imagePullSecrets value that lists both the Replicated enterprise-pull-secret as well as any global or chart-level pull secrets provided by your customers. Using this helper supports use cases where customers need to provide one or more pull secrets in addition to the enterprise-pull-secret, such as in air gap installations where images are pushed to a private regitsry in the air-gapped environment.

{{/*
Image pull secrets
*/}}
{{- define "replicated.imagePullSecrets" -}}
  {{- $pullSecrets := list }}

  {{- with ((.Values.global).imagePullSecrets) -}}
    {{- range . -}}
      {{- if kindIs "map" . -}}
        {{- $pullSecrets = append $pullSecrets .name -}}
      {{- else -}}
        {{- $pullSecrets = append $pullSecrets . -}}
      {{- end }}
    {{- end -}}
  {{- end -}}

  {{/* use image pull secrets provided as values */}}
  {{- with .Values.images -}}
    {{- range .pullSecrets -}}
      {{- if kindIs "map" . -}}
        {{- $pullSecrets = append $pullSecrets .name -}}
      {{- else -}}
        {{- $pullSecrets = append $pullSecrets . -}}
      {{- end -}}
    {{- end -}}
  {{- end -}}

  {{/* use the pull secret created by the SDK */}}
  {{- if hasKey ((.Values.global).replicated) "dockerconfigjson" }}
    {{- $pullSecrets = append $pullSecrets "enterprise-pull-secret" -}}
  {{- end -}}


  {{- if (not (empty $pullSecrets)) -}}
imagePullSecrets:
    {{- range $pullSecrets | uniq }}
  - name: {{ . }}
    {{- end }}
  {{- end }}
{{- end -}}

Use your helper to include the image pull secrets in any manifests that reference the image.

Example:

apiVersion: v1
kind: Pod
spec:
  # Add the pull secret with your helper
  {{- include "replicated.imagePullSecrets" . | nindent 6 }}
  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 }}

If your application is deployed as multiple Helm charts, repeat the previous steps to modify image references and add the pull secret for each of your charts.
Package your Helm chart and add it to a release. Promote the release to a development channel. See Managing Releases with Vendor Portal.
Install in a development environment to test your changes. See Install with Helm.

(Optional) Create Your Own Image Pull Secret

You can optionally create your own image pull secret to authenticate with the Replicated proxy registry instead of using the enterprise-pull-secret that is automatically created by the Replicated SDK. You might want to create your own pull secret if you manage the pull secret externally.

To create a pull secret for the proxy registry:

In your Helm chart values.yaml file, set the Replicated SDK's createPullSecret value to false. When createPullSecret is false, the SDK does not automatically create the enterprise-pull-secret during installation.
```
# Your Helm chart values.yaml

replicated:
  createPullSecret: false
```
In your Helm chart templates, add a YAML file that evaluates if the global.replicated.dockerconfigjson value is set, and then writes the rendered value into a Secret on the cluster, as shown below.

The following example names the Secret enterprise-pull-secret. If you use a different name, be sure to update any Helm helpers and image references in your chart accordingly. Do not use replicated for the name of the image pull secret because the Replicated SDK automatically creates a Secret named replicated. Using the same name causes an error.
```
# templates/enterprise-pull-secret.yaml

{{- $global := default dict .Values.global -}}
{{- $replicated := default dict (index $global "replicated") -}}
{{- if hasKey $replicated "dockerconfigjson" }}
apiVersion: v1
kind: Secret
metadata:
  name: enterprise-pull-secret
type: kubernetes.io/dockerconfigjson
data:
  .dockerconfigjson: {{ .Values.global.replicated.dockerconfigjson }}
{{ end }}
```
Complete the steps in Configure Your Application to Pull Images Through the Proxy Registry to create and use a Helm helper to add the enterprise-pull-secret that you created to image references in your chart.

Overview​

Prerequisite​

Configure Your Application to Use the Proxy Registry​

(Optional) Create Your Own Image Pull Secret​

Overview

Prerequisite

Configure Your Application to Use the Proxy Registry

(Optional) Create Your Own Image Pull Secret