Add image template functions docs for EC v3 #3940
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -11,9 +11,29 @@ This topic describes how to use the Replicated proxy registry for applications d | |
|
|
||
| ## Configure your application to use the proxy registry | ||
|
|
||
| These steps assume that you package your application with Helm and that you install with the [HelmChart v2](/reference/custom-resource-helmchart-v2) custom resource. | ||
|
|
||
| If you are installing with the HelmChart v1 custom resource, or if your application is not packaged with Helm, there are different steps for configuring your application to use the proxy registry. See [Configure other application types](#other) below. | ||
|
Contributor
There was a problem hiding this comment. 📝 [vale] reported by reviewdog 🐶
Contributor
There was a problem hiding this comment.
|
||
|
|
||
| ### Embedded Cluster v3 (Beta) {#configure-v3} | ||
|
Contributor
There was a problem hiding this comment.
Contributor
There was a problem hiding this comment. Added these new steps for ECv3. The main difference is that you don't need to inject the image pull secret anymore since EC v3 automatically configures the cluster to authenticate to the proxy registry for all pods |
||
|
|
||
| Follow these steps to use the proxy registry with applications installed with [Embedded Cluster v3 (Beta)](/embedded-cluster/v3/embedded-overview). | ||
|
|
||
| Embedded Cluster v3 configures the cluster to automatically authenticate to the Replicated proxy registry for all pods. | ||
|
|
||
| For installations Embedded Cluster v3, | ||
|
|
||
| 1. <StepCreds/> | ||
|
|
||
| 1. <StepCustomDomain/> | ||
|
|
||
| 1. <RewriteHelmValues/> | ||
|
|
||
| 1. Create a new release with your changes. Promote the release to a development channel. See [Managing Releases with Vendor Portal](releases-creating-releases). | ||
|
|
||
| 1. Install in a development environment to test your changes. See [Online installation with Embedded Cluster](/embedded-cluster/v3/installing-embedded). | ||
|
|
||
| ### Embedded Cluster v2, KOTS, or kURL | ||
|
|
||
| To configure your application to use the proxy registry for installations with a Replicated installer: | ||
|
|
||
|
|
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,212 @@ | ||
| # Image Template Functions for Embedded Cluster (Beta) | ||
|
Contributor
There was a problem hiding this comment.
Contributor
There was a problem hiding this comment. This is Salah's original doc. Leaving it here for now for reference. We can remove when we're ready to merge |
||
|
|
||
| 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](embedded-config#extensions) in _Embedded Cluster Config_. For information about the HelmChart custom resource, see [HelmChart v2](/reference/custom-resource-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. | ||
|
Contributor
There was a problem hiding this comment. 📝 [vale] reported by reviewdog 🐶
Contributor
There was a problem hiding this comment. 📝 [vale] reported by reviewdog 🐶
Contributor
There was a problem hiding this comment.
|
||
| - **Air gap**: All images are rewritten to the local registry regardless of the `noProxy` parameter. | ||
|
Contributor
There was a problem hiding this comment.
Does this refer to the Embedded Cluster built-in local registry? Or are there cases where the user is able to bring their own local registry? |
||
|
|
||
| ## Recommended Setup | ||
|
Contributor
There was a problem hiding this comment.
|
||
|
|
||
| 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](/vendor/custom-domains). | ||
| - `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: | ||
|
|
||
| ```yaml | ||
| # values.yaml | ||
| image: | ||
| registry: proxy.replicated.com | ||
| repository: proxy/my-app/ghcr.io/my-org/my-image | ||
| tag: v1.0.0 | ||
| ``` | ||
|
|
||
| ```yaml | ||
| # helmchart.yaml | ||
| apiVersion: kots.io/v1beta2 | ||
| kind: HelmChart | ||
| spec: | ||
| values: | ||
| image: | ||
| registry: '{{repl ReplicatedImageRegistry (HelmValue ".image.registry") }}' | ||
| repository: '{{repl ReplicatedImageRepository (HelmValue ".image.repository") true }}' | ||
| ``` | ||
|
|
||
| `ReplicatedImageRegistry` omits `noProxy` so the function returns the correct proxy domain for the installation, including any [custom domain](/vendor/custom-domains) 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`. | ||
|
Contributor
There was a problem hiding this comment.
Want to make sure I understand the use of noProxy here... Since the repository value in |
||
|
|
||
| ### 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`: | ||
|
|
||
| ```yaml | ||
| # values.yaml | ||
| initImage: proxy.replicated.com/proxy/my-app/docker.io/library/busybox:1.36 | ||
| ``` | ||
|
|
||
| ```yaml | ||
| # helmchart.yaml | ||
| values: | ||
| initImage: '{{repl ReplicatedImageName (HelmValue ".initImage") true }}' | ||
| ``` | ||
|
|
||
| ## Additional Use Cases | ||
|
Contributor
There was a problem hiding this comment.
|
||
|
|
||
| ### 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: | ||
|
Contributor
There was a problem hiding this comment. 📝 [vale] reported by reviewdog 🐶
Contributor
There was a problem hiding this comment. 📝 [vale] reported by reviewdog 🐶
Contributor
There was a problem hiding this comment.
|
||
|
|
||
| ```yaml | ||
| # values.yaml | ||
| publicImage: docker.io/library/busybox:1.36 | ||
| ``` | ||
|
|
||
| ```yaml | ||
| # helmchart.yaml | ||
| values: | ||
| publicImage: '{{repl ReplicatedImageName (HelmValue ".publicImage") true }}' | ||
| ``` | ||
|
|
||
| ### Subchart images | ||
|
Contributor
There was a problem hiding this comment. 🚫 [vale] reported by reviewdog 🐶 |
||
|
|
||
| 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`: | ||
|
Contributor
There was a problem hiding this comment. 🚫 [vale] reported by reviewdog 🐶
Contributor
There was a problem hiding this comment. 🚫 [vale] reported by reviewdog 🐶
Contributor
There was a problem hiding this comment.
Contributor
There was a problem hiding this comment. 🚫 [vale] reported by reviewdog 🐶 |
||
|
|
||
| ```yaml | ||
| # values.yaml | ||
| my-subchart: | ||
| image: | ||
| registry: proxy.replicated.com | ||
| repository: proxy/my-app/docker.io/some-org/some-image | ||
| tag: "1.0.0" | ||
| ``` | ||
|
|
||
| ```yaml | ||
| # helmchart.yaml | ||
| values: | ||
| my-subchart: | ||
| image: | ||
| registry: '{{repl ReplicatedImageRegistry (HelmValue ".my-subchart.image.registry") }}' | ||
| repository: '{{repl ReplicatedImageRepository (HelmValue ".my-subchart.image.repository") true }}' | ||
| ``` | ||
|
|
||
| ### Embedded Cluster extension images | ||
|
|
||
| For Helm extensions in the [Embedded Cluster Config](embedded-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](#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: | ||
|
|
||
| ```yaml | ||
| # 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" }}' | ||
| ``` | ||
|
|
||
| **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: | ||
|
|
||
| ```yaml | ||
| values: | | ||
| image: | ||
| repository: 'repl{{ ReplicatedImageName "docker.io/some-org/some-image" }}' | ||
| ``` | ||
|
|
||
| ## Tips | ||
|
|
||
| - When referencing Docker Hub images through the Replicated proxy registry, use the full path including `docker.io` and the namespace. For official images, this means including `library`. For example, to proxy the `nginx` image, use `proxy.replicated.com/proxy/my-app/docker.io/library/nginx` (not `proxy.replicated.com/proxy/my-app/nginx`). For other Docker Hub images, include the organization (for example, `proxy.replicated.com/proxy/my-app/docker.io/bitnami/postgresql`). | ||
|
|
||
| ## Function Reference | ||
|
Contributor
There was a problem hiding this comment.
|
||
|
|
||
| ### ReplicatedImageName | ||
|
|
||
| ```go | ||
| 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. The optional `noProxy` parameter, when set to `true`, leaves the image unchanged in online mode. | ||
|
|
||
| | Mode | noProxy | Result | | ||
|
Contributor
There was a problem hiding this comment. 🚫 [vale] reported by reviewdog 🐶 |
||
| |------|---------|--------| | ||
| | Online | omitted | `proxy.replicated.com/proxy/<app-slug>/<image>` | | ||
| | Online | `true` | `<image>` (unchanged) | | ||
| | Air gap | any | `<local-registry>/<app-slug>/<name>:<tag>` | | ||
|
|
||
| ### ReplicatedImageRegistry | ||
|
|
||
| ```go | ||
| 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. The optional `noProxy` parameter, when set to `true`, returns the input registry unchanged in online mode. | ||
|
|
||
| | Mode | noProxy | Result | | ||
|
Contributor
There was a problem hiding this comment. 🚫 [vale] reported by reviewdog 🐶 |
||
| |------|---------|--------| | ||
| | Online | omitted | `proxy.replicated.com` (or custom domain) | | ||
| | Online | `true` | `<registry>` (unchanged) | | ||
| | Air gap | any | `<local-registry-address>` | | ||
|
|
||
| ### ReplicatedImageRepository | ||
|
|
||
| ```go | ||
| func ReplicatedImageRepository(repository string, noProxy ...bool) string | ||
|
Member
There was a problem hiding this comment. its awkward reading go code here. its not obvious that noProxy is optional or what the intention of the ... is
Member
Author
There was a problem hiding this comment. this matches our docs elsewhere for template functions... |
||
| ``` | ||
|
|
||
| Returns the repository path. Use this together with `ReplicatedImageRegistry`. The optional `noProxy` parameter, when set to `true`, returns the input repository unchanged in online mode. | ||
|
|
||
| | Mode | noProxy | Result | | ||
|
Contributor
There was a problem hiding this comment. 🚫 [vale] reported by reviewdog 🐶 |
||
| |------|---------|--------| | ||
| | Online | omitted | `proxy/<app-slug>/<repository>` | | ||
| | Online | `true` | `<repository>` (unchanged) | | ||
| | Air gap | any | `<app-slug>/<name>` | | ||
|
|
||
| ### HelmValue | ||
|
|
||
| ```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 image template functions. | ||
|
|
||
| ## KOTS-Compatible Aliases | ||
|
Contributor
There was a problem hiding this comment.
|
||
|
|
||
| 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. | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
📝 [vale] reported by reviewdog 🐶
[Replicated.SentenceLength] Try to keep your sentence length to 26 words or fewer.