---
toc_max_heading_level: 2
---

# 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](/reference/template-functions-about).

## 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](#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](#replicatedimagename) |
| Separate `registry`, `repository`, and `tag` fields (for example, `registry: ghcr.io`, `repository: myorg/init`) | The `registry` field. Leave `repository` and `tag` unchanged. | [ReplicatedImageRegistry](#replicatedimageregistry) |

For concrete input and output examples for each shape, see [ReplicatedImageName](#replicatedimagename) and [ReplicatedImageRegistry](#replicatedimageregistry) below.

## ReplicatedImageName

```go
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](#replicatedimageregistry) on the `registry` field instead.

For more information, see [Add support for air gap installations](embedded-using#local-image-registry) in _Configure Embedded Cluster_.

### Parameters

#### image

The image reference to rewrite (with or without a tag).
Use the [HelmValue](#helmvalue-func) 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](/vendor/custom-domains-using). 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

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

```yaml
# 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`

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

```yaml
# 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.

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

```yaml
# 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

```go
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](#replicatedimagename) on the `repository` field.

For more information, see [Add support for air gap installations](embedded-using#local-image-registry) 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](#helmvalue-func) 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](/vendor/custom-domains-using). 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

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

```yaml
# 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

```yaml
# 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 {#helmvalue-func}

```go
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](#replicatedimagename) or [ReplicatedImageRegistry](#replicatedimageregistry) template functions.

### Examples

#### Return a top-level value

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

#### Return a value from a subchart

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