Skip to content

embedded-image-template-functions.mdx

Latest commit

 

History

History
249 lines (180 loc) · 9.25 KB

embedded-image-template-functions.mdx

File metadata and controls

249 lines (180 loc) · 9.25 KB

Image Template Functions for Embedded Cluster (Beta)

This topic describes how to use image template functions in Embedded Cluster v3 Helm extension values and in the KOTS HelmChart custom resource. These functions ensure that image references resolve correctly in both online and air gap installations.

For information about Embedded Cluster extensions, see extensions in Embedded Cluster Config. For information about the HelmChart custom resource, see HelmChart v2.

Overview

Image template functions automatically rewrite image references based on the installation mode:

  • Online: Images are served through the Replicated proxy registry (proxy.replicated.com or your custom domain). Images that do not need to go through the proxy can be left unchanged using the noProxy parameter.
  • Air gap: All images are rewritten to the local registry regardless of the noProxy parameter.

Recommended Setup

Replicated recommends setting your chart's values.yaml image defaults to point to the Replicated proxy registry for all private and third-party images. This ensures the chart works out of the box when installed with helm install in online environments.

The proxy registry URL follows this format: DOMAIN/proxy/APP_SLUG/UPSTREAM_REGISTRY/IMAGE_PATH

Where:

  • DOMAIN is proxy.replicated.com or your custom domain.
  • APP_SLUG is the unique slug of your application.
  • UPSTREAM_REGISTRY/IMAGE_PATH is the full upstream image path (for example, ghcr.io/my-org/my-image or docker.io/bitnami/postgresql).

Charts with separate registry and repository fields

If a chart splits image references into separate registry and repository fields, set the proxy defaults in values.yaml and use ReplicatedImageRegistry and ReplicatedImageRepository in the HelmChart CR:

# values.yaml
image:
  registry: proxy.replicated.com
  repository: proxy/my-app/ghcr.io/my-org/my-image
  tag: v1.0.0
# helmchart.yaml
apiVersion: kots.io/v1beta2
kind: HelmChart
spec:
  values:
    image:
      registry: '{{repl ReplicatedImageRegistry (HelmValue ".image.registry") }}'
      repository: '{{repl ReplicatedImageRepository (HelmValue ".image.repository") true }}'
    imagePullSecrets:
      - name: '{{repl ImagePullSecretName }}'

ReplicatedImageRegistry omits noProxy so the function returns the correct proxy domain for the installation, including any custom domain configuration. ReplicatedImageRepository sets noProxy to true because the repository value in values.yaml already contains the proxy path prefix (proxy/my-app/...). In air gap mode, both functions rewrite to the local registry regardless of noProxy.

Charts with a single image field

If a chart expects the full image reference in a single field, set the proxy URL as the default in values.yaml and use ReplicatedImageName with noProxy set to true:

# values.yaml
initImage: proxy.replicated.com/proxy/my-app/docker.io/library/busybox:1.36
# helmchart.yaml
values:
  initImage: '{{repl ReplicatedImageName (HelmValue ".initImage") true }}'

Additional Use Cases

Public images

If an image is public and does not need to go through the proxy registry, set the upstream reference directly in values.yaml and use noProxy so the reference is left unchanged in online mode but still rewritten for air gap:

# values.yaml
publicImage: docker.io/library/busybox:1.36
# helmchart.yaml
values:
  publicImage: '{{repl ReplicatedImageName (HelmValue ".publicImage") true }}'

Subchart images

If your chart includes subcharts that have their own image.registry and image.repository fields, apply the same pattern for each subchart. Set the proxy defaults under the subchart key in values.yaml:

# values.yaml
my-subchart:
  image:
    registry: proxy.replicated.com
    repository: proxy/my-app/docker.io/some-org/some-image
    tag: "1.0.0"
# helmchart.yaml
values:
  my-subchart:
    image:
      registry: '{{repl ReplicatedImageRegistry (HelmValue ".my-subchart.image.registry") }}'
      repository: '{{repl ReplicatedImageRepository (HelmValue ".my-subchart.image.repository") true }}'

imagePullSecrets

The ImagePullSecretName function returns the name of a pull secret that authenticates to the proxy registry or local registry. This secret is automatically created when you include the Replicated SDK as a subchart in your application.

Configure imagePullSecrets for your application and for each subchart. Set imagePullSecrets at whatever level each chart reads from. Consult each subchart's documentation to determine the correct location. Common patterns include:

# Top-level (used by most charts)
imagePullSecrets:
  - name: '{{repl ImagePullSecretName }}'

# Some charts use global.imagePullSecrets (for example, Bitnami charts)
my-subchart:
  global:
    imagePullSecrets:
      - '{{repl ImagePullSecretName }}'

# Some charts nest imagePullSecrets under the chart key
my-subchart:
  imagePullSecrets:
    - name: '{{repl ImagePullSecretName }}'

Embedded Cluster extension images

For Helm extensions in the Embedded Cluster Config, the approach depends on whether you control the chart's values.yaml.

Your own charts

For charts you own, you can set the proxy defaults in values.yaml and use the same HelmValue with noProxy pattern described in Recommended Setup.

Third-party charts

For third-party charts where you cannot modify values.yaml to set proxy defaults, provide the upstream image references directly in the extension values and omit noProxy. The template functions will add the proxy prefix in online mode and rewrite to the local registry in air gap mode.

If the chart uses separate registry and repository fields:

# embedded-cluster.yaml
extensions:
  helmCharts:
    - chart:
        name: ingress-nginx
        chartVersion: "4.11.3"
      releaseName: ingress-nginx
      namespace: ingress-nginx
      values: |
        controller:
          image:
            registry: 'repl{{ ReplicatedImageRegistry "registry.k8s.io" }}'
            repository: 'repl{{ ReplicatedImageRepository "registry.k8s.io/ingress-nginx/controller" }}'
            tag: 'repl{{ HelmValue ".Values.controller.image.tag" }}'
            digest: ""
            digestChroot: ""

Note: ReplicatedImageRepository requires the full upstream image path including the registry (for example, registry.k8s.io/ingress-nginx/controller), not just the repository portion.

If the chart uses a single image field:

      values: |
        image:
          repository: 'repl{{ ReplicatedImageName "docker.io/some-org/some-image" }}'

Tips

  • When referencing Docker Hub images, use docker.io as the hostname (for example, docker.io/bitnami/postgresql).
  • Always include imagePullSecrets using ImagePullSecretName for every pod that pulls from the proxy or local registry.

Function Reference

ReplicatedImageName

func ReplicatedImageName(image string, noProxy ...bool) string

Returns a full image reference (registry + repository + tag). Use this when a chart expects the entire image reference in a single field.

Mode noProxy Result
Online omitted proxy.replicated.com/proxy/<app-slug>/<image>
Online true <image> (unchanged)
Air gap any <local-registry>/<app-slug>/<name>:<tag>

ReplicatedImageRegistry

func ReplicatedImageRegistry(registry string, noProxy ...bool) string

Returns the registry host. Use this when a chart splits the image reference into separate registry and repository fields.

Mode noProxy Result
Online omitted proxy.replicated.com (or custom domain)
Online true <registry> (unchanged)
Air gap any <local-registry-address>

ReplicatedImageRepository

func ReplicatedImageRepository(repository string, noProxy ...bool) string

Returns the repository path. Use this together with ReplicatedImageRegistry.

Mode noProxy Result
Online omitted proxy/<app-slug>/<repository>
Online true <repository> (unchanged)
Air gap any <app-slug>/<name>

ImagePullSecretName

func ImagePullSecretName() string

Returns the name of the automatically created image pull secret (format: <app-slug>-registry).

HelmValue

func HelmValue(path string) string

Returns the value from the chart's values.yaml at the given dotted path. Use this to read the chart's default image values and pass them to image template functions.

KOTS-Compatible Aliases

For backward compatibility with KOTS, the following template functions are available as aliases:

KOTS function Equivalent
LocalImageName ReplicatedImageName
HasLocalRegistry Returns true in air gap mode
LocalRegistryHost Returns the local registry address
LocalRegistryNamespace Returns the app slug
LocalRegistryAddress Returns <host>/<namespace>

For new configurations, use the Replicated* functions.