Add image template functions docs for EC v3

docs/partials/proxy-service/_step-inject-pull-secret.mdx

@@ -1,4 +1,4 @@
-In the HelmChart v2 custom resource, configure the `values` key to inject the Replicated image pull secret into your Helm values. This provides authentication for the proxy registry. Use the KOTS [ImagePullSecretName](/reference/template-functions-config-context#imagepullsecretname) template function to get the pull secret name.
+In the HelmChart v2 custom resource, configure the `values` key to inject the Replicated image pull secret into your Helm values. This provides authentication for the proxy registry. Use the [ImagePullSecretName](/reference/template-functions-config-context#imagepullsecretname) template function to get the pull secret name.
 
     <details>
     <summary>What is the Replicated image pull secret?</summary>
@@ -34,7 +34,7 @@ In the HelmChart v2 custom resource, configure the `values` key to inject the Re
       containers:
       - name: nginx
         image: {{ .Values.image.registry }}/{{ .Values.image.repository }}
-      # Access the value to provide the KOTS pull secret
+      # Access the value to provide the pull secret
       {{- with .Values.image.pullSecrets }}
       imagePullSecrets:
       {{- toYaml . | nindent 2 }}

docs/partials/proxy-service/_step-rewrite-helm-values.mdx

@@ -1,11 +1,11 @@
-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.
+For each Helm chart used by your application, in the Helm chart's `values.yaml` file, update all references to private or third-party images to use the Replicated proxy registry domain.
+
+    The proxy registry URL has the following format: `DOMAIN/proxy/APP_SLUG/UPSTREAM_REGISTRY/IMAGE_PATH`
 
-    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.
+    - `DOMAIN` is either `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`.
 
     **Example:**
 

docs/vendor/private-images-kots.mdx

@@ -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 KOTS [HelmChart v2](/reference/custom-resource-helmchart-v2) custom resource.
+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.
+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.
+
+### Embedded Cluster v3 (Beta) {#configure-v3}
+
+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:
 

embedded-cluster/embedded-image-template-functions.mdx

@@ -0,0 +1,212 @@
+# 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](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.
+- **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](/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`.
+
+### 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
+
+### 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:
+
+```yaml
+# values.yaml
+publicImage: docker.io/library/busybox:1.36
+```
+
+```yaml
+# 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`:
+
+```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
+
+### 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 |
+|------|---------|--------|
+| 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 |
+|------|---------|--------|
+| 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
+```
+
+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 |
+|------|---------|--------|
+| 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
+
+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.