Template Functions for Embedded Cluster (Beta)

This topic lists the Replicated template functions for Embedded Cluster. For more imformation about how to use Replicated template functions, including a list of all available template functions, see About Template Functions.

Image rewriting

Helm charts express images in three shapes. The shape of the chart's image fields determines which template function to use and which field to template:

Helm chart image shape	Field to template	Template function
Single field with the full image reference (for example, image: ghcr.io/myorg/init:1.4.0)	The image field	ReplicatedImageName
Separate repository and tag fields, where repository includes the registry host (for example, repository: ghcr.io/myorg/init)	The repository field. Leave tag unchanged.	ReplicatedImageName
Separate registry, repository, and tag fields (for example, registry: ghcr.io, repository: myorg/init)	The registry field. Leave repository and tag unchanged.	ReplicatedImageRegistry

For concrete input and output examples for each shape, see ReplicatedImageName and ReplicatedImageRegistry below.

ReplicatedImageName

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

Returns a full image reference, including the registry, repository, and tag (if any).

Use this template function when:

• A chart expects the full image reference in a single field, such as image: ghcr.io/myorg/init:1.4.0.
• A chart uses separate repository and tag fields, and the registry host is part of the repository value (for example, repository: ghcr.io/myorg/init, tag: 1.4.0). Template the repository field. Leave the tag field unchanged.

If the chart uses separate registry, repository, and tag fields, use ReplicatedImageRegistry on the registry field instead.

For more information, see Add support for air gap installations in Configure Embedded Cluster.

Parameters

image

The image reference to rewrite (with or without a tag). Use the HelmValue function to return the value from the chart's values.yaml at the given dotted path.

noProxy

The following table describes the value returned by ReplicatedImageName in online or air gap installations, when the noProxy field is omitted or set to true:

Install type	noProxy	Result
Online	Omitted	Returns the proxy registry URL for the image in the format: <proxy-registry-domain>/proxy/<app-slug>/<image>. The proxy registry domain is either proxy.replicated.com or your custom domain. If the image is already using the proxy registry URL, then ReplicatedImageName returns the image value unchanged.
Online	true	Returns the image reference with no changes
Air gap	true or omitted	Returns the location of the image at the local image registry in the format: <local-registry>/<repo-path>:<tag>

Examples

Single field with the full image reference

# values.yaml
initImage: ghcr.io/myorg/init:1.4.0

# HelmChart custom resource
apiVersion: kots.io/v1beta2
kind: HelmChart
spec:
  values:
    initImage: '{{repl ReplicatedImageName (HelmValue ".initImage") }}'

The rendered value of initImage for each install type:

Install type	Rendered value
Online	<proxy-registry-domain>/proxy/<app-slug>/ghcr.io/myorg/init:1.4.0
Air gap	<local-registry>/myorg/init:1.4.0

Separate repository and tag fields with the registry host in repository

# values.yaml
image:
  repository: ghcr.io/myorg/init
  tag: 1.4.0

# HelmChart custom resource
apiVersion: kots.io/v1beta2
kind: HelmChart
spec:
  values:
    image:
      repository: '{{repl ReplicatedImageName (HelmValue ".image.repository") }}'
      tag: 1.4.0

The image.tag field is not templated and renders as 1.4.0. The rendered value of image.repository for each install type:

Install type	Rendered repository
Online	<proxy-registry-domain>/proxy/<app-slug>/ghcr.io/myorg/init
Air gap	<local-registry>/myorg/init

Public image (noProxy)

For public images that do not go through the Replicated proxy registry, set noProxy to true so that ReplicatedImageName leaves the reference unchanged in online installations. In air gap installations, ReplicatedImageName still rewrites the image to the local image registry.

# values.yaml
publicImage: docker.io/library/busybox:1.36

# HelmChart custom resource
apiVersion: kots.io/v1beta2
kind: HelmChart
spec:
  values:
    publicImage: '{{repl ReplicatedImageName (HelmValue ".publicImage") true }}'

Install type	Rendered value
Online	docker.io/library/busybox:1.36
Air gap	<local-registry>/library/busybox:1.36

ReplicatedImageRegistry

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

Returns the registry host, prefixed with the Replicated proxy registry path (online) or replaced with the local image registry address (air gap).

Use this template function when the chart uses separate registry, repository, and tag fields (for example, registry: ghcr.io, repository: myorg/init, tag: 1.4.0). Template only the registry field. Leave the repository and tag fields unchanged.

If the registry host is part of the repository field instead of in a separate registry field, use ReplicatedImageName on the repository field.

For more information, see Add support for air gap installations in Configure Embedded Cluster.

note

You do not need to template the repository field. When you template the registry field, ReplicatedImageRegistry returns the full proxy registry path required to pull the image through the proxy registry.

Parameters

registry

The registry host to rewrite (for example, ghcr.io or docker.io). Use the HelmValue function to return the value from the chart's values.yaml at the given dotted path.

noProxy

The following table describes the value returned by ReplicatedImageRegistry in online or air gap installations when the noProxy field is omitted or set to true:

Install type	noProxy	Result
Online	Omitted	Returns the proxy registry path in the format: <proxy-registry-domain>/proxy/<app-slug>/<image>. The proxy registry domain is either proxy.replicated.com or your custom domain. If the registry is already using the proxy registry URL, then ReplicatedImageRegistry returns the registry value unchanged.
Online	true	Returns the registry value with no changes
Air gap	true or omitted	Returns the local registry address

Examples

Separate registry, repository, and tag fields

# values.yaml
image:
  registry: ghcr.io
  repository: myorg/init
  tag: 1.4.0

# HelmChart custom resource
apiVersion: kots.io/v1beta2
kind: HelmChart
spec:
  values:
    image:
      registry: '{{repl ReplicatedImageRegistry (HelmValue ".image.registry") }}'
      repository: myorg/init
      tag: 1.4.0

The image.repository and image.tag fields are not templated and render as myorg/init and 1.4.0. The rendered value of image.registry for each install type:

Install type	Rendered registry
Online	<proxy-registry-domain>/proxy/<app-slug>/ghcr.io
Air gap	<local-registry>

Rewrite upstream image references for third-party Helm extensions

# Embedded Cluster Config
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" }}'

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 the ReplicatedImageName or ReplicatedImageRegistry template functions.

Examples

Return a top-level value

# HelmChart custom resource
values:
  initImage: '{{repl ReplicatedImageName (HelmValue ".initImage") true }}'

Return a value from a subchart

# HelmChart custom resource
values:
  my-subchart:
    image:
      registry: '{{repl ReplicatedImageRegistry (HelmValue ".my-subchart.image.registry") }}'