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.

You can use this global.replicated.dockerconfigjson field to create the pull secret required to authenticate with the proxy registry. 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.

note

For Helm charts that include the Replicated SDK as a dependency, the image used by the Replicated SDK is automatically proxied through the proxy registry. No additional configuration is required. For more information, see About the Replicated SDK.

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 domain for this URL is either proxy.replicated.com or your custom domain.

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 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.

note
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/replicated-pull-secret.yaml

{{ if .Values.global.replicated.dockerconfigjson }}
apiVersion: v1
kind: Secret
metadata:
  # Note: Do not use "replicated" for the name of the pull secret
  name: replicated-pull-secret
type: kubernetes.io/dockerconfigjson
data:
  .dockerconfigjson: {{ .Values.global.replicated.dockerconfigjson }}
{{ end }}
```

In your _helper.tpl, add a Helm helper for the image pull secret. This helper creates an imagePullSecrets value that lists both the Replicated pull secret that you created (if present) as well as any global or chart-level pull secrets provided by your customers. This supports use cases where customers need to provide additional pull secrets, 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 secret created with injected docker config */}}
  {{- if hasKey ((.Values.global).replicated) "dockerconfigjson" }}
    {{- $pullSecrets = append $pullSecrets "replicated-pull-secret" -}}
  {{- end -}}


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

Use your helper in any manifests that reference the image.

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

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.

Overview​

Configure Your Application to Use the Proxy Registry​

Overview

Configure Your Application to Use the Proxy Registry