diff --git a/docs/partials/proxy-service/_step-inject-pull-secret.mdx b/docs/partials/proxy-service/_step-inject-pull-secret.mdx index 44d1292b00..8e2e4b6ce3 100644 --- a/docs/partials/proxy-service/_step-inject-pull-secret.mdx +++ b/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.
What is the Replicated image pull secret? @@ -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 }} diff --git a/docs/partials/proxy-service/_step-rewrite-helm-values.mdx b/docs/partials/proxy-service/_step-rewrite-helm-values.mdx index 05cd045907..19cc7aacfb 100644 --- a/docs/partials/proxy-service/_step-rewrite-helm-values.mdx +++ b/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:** diff --git a/docs/reference/template-functions-about.mdx b/docs/reference/template-functions-about.mdx index 3d38caff9d..9afd15f815 100644 --- a/docs/reference/template-functions-about.mdx +++ b/docs/reference/template-functions-about.mdx @@ -12,7 +12,7 @@ This topic describes Replicated template functions, including information about ## Overview -For Kubernetes manifest files for applications deployed by a Replicated installer (Embedded Cluster, KOTS, kURL), Replicated provides a set of custom template functions based on the Go text/template library. +Replicated provides a set of custom template functions based on the Go text/template library. You can use the Replicated template functions in Kubernetes manifest files for applications deployed by a Replicated installer (Embedded Cluster, KOTS, kURL). @@ -26,16 +26,6 @@ You can use Replicated template functions in Kubernetes manifest files for appli * Kubernetes objects like Deployments, Services, Secrets, or ConfigMaps * Kubernetes Operators -### Limitations - -* Not all fields in the Config and Application custom resources support templating. For more information, see [Application](/reference/custom-resource-application) and [Item Properties](/reference/custom-resource-config#item-properties) in _Config_. - -* Templating is not supported in the [Embedded Cluster Config](/embedded-cluster/v3/embedded-config) resource. - -* Replicated template functions are not directly supported in Helm charts. For more information, see [Helm Charts](#helm-charts) below. - -### Helm charts - Replicated template functions are _not_ directly supported in Helm charts. However, the HelmChart custom resource provides a way to map values rendered by Replicated template functions to Helm chart values. This allows you to use Replicated template functions with Helm charts without making changes to those Helm charts. For information about how to map values from the HelmChart custom resource to Helm chart `values.yaml` files, see [Setting Helm Chart Values with KOTS](/vendor/helm-optional-value-keys). @@ -46,6 +36,23 @@ During application installation and upgrade, KOTS templates all Kubernetes manif For the [Config](/reference/custom-resource-config) custom resource, KOTS templates each item separately so that config items can be used in templates for other items. For examples of this, see [Using Conditional Statements in Configuration Fields](/vendor/config-screen-conditional) and [Template Function Examples](/reference/template-functions-examples). +### Limitations + +* Not all fields in the Config and Application custom resources support templating. For more information, see [Application](/reference/custom-resource-application) and [Item Properties](/reference/custom-resource-config#item-properties) in _Config_. + +* Templating is not supported in the [Embedded Cluster Config](/embedded-cluster/v3/embedded-config) resource. + +* Replicated template functions are not directly supported in Helm charts. For more information, see [Helm Charts](#helm-charts) on this page. + +* Embedded Cluster v3 does not support the following template functions: + * HasLocalRegistry + * LocalRegistryAddress + * LocalRegistryHost + * LocalRegistryNamespace + * LocalImageName + + These template functions are typically used to conditionally rewrite image references in air gap installations to reference the local image registry. For Embedded Cluster v3 installations, use the ReplicatedImageName, ReplicatedImageName, and ReplicatedImageName template functions instead. For more information, see [Template Functions for Embedded Cluster (Beta)](/embedded-cluster/v3/template-functions). + ## Syntax {#syntax} The Replicated template function syntax supports the following functionally equivalent delimiters: diff --git a/docs/reference/template-functions-config-context.md b/docs/reference/template-functions-config-context.md index f4e6c4ab84..b20a62b90e 100644 --- a/docs/reference/template-functions-config-context.md +++ b/docs/reference/template-functions-config-context.md @@ -194,6 +194,10 @@ Returns true if the configuration option value is not equal to the supplied valu ## LocalRegistryAddress +:::note +The LocalRegistryAddress template function is not supported for installations with Embedded Cluster v3. See [Template Functions for Embedded Cluster (Beta)](/embedded-cluster/v3/template-functions). +::: + ```go func LocalRegistryAddress() string ``` @@ -203,6 +207,10 @@ This will always return everything before the image name and tag. ## LocalRegistryHost +:::note +The LocalRegistryHost template function is not supported for installations with Embedded Cluster v3. See [Template Functions for Embedded Cluster (Beta)](/embedded-cluster/v3/template-functions). +::: + ```go func LocalRegistryHost() string ``` @@ -236,6 +244,10 @@ For more information, see [Set Helm Values with KOTS](/vendor/helm-optional-valu ## LocalRegistryNamespace +:::note +The LocalRegistryNamespace template function is not supported for installations with Embedded Cluster v3. See [Template Functions for Embedded Cluster (Beta)](/embedded-cluster/v3/template-functions). +::: + ```go func LocalRegistryNamespace() string ``` @@ -267,6 +279,10 @@ For more information, see [Set Helm Values with KOTS](/vendor/helm-optional-valu ## LocalImageName +:::note +The LocalImageName template function is not supported for installations with Embedded Cluster v3. See [Template Functions for Embedded Cluster (Beta)](/embedded-cluster/v3/template-functions). +::: + ```go func LocalImageName(remoteImageName string) string ``` @@ -346,6 +362,10 @@ spec: ## HasLocalRegistry +:::note +The HasLocalRegistry template function is not supported for installations with Embedded Cluster v3. See [Template Functions for Embedded Cluster (Beta)](/embedded-cluster/v3/template-functions). +::: + ```go func HasLocalRegistry() bool ``` diff --git a/docs/vendor/private-images-kots.mdx b/docs/vendor/private-images-kots.mdx index 785c32c8ed..559120dba7 100644 --- a/docs/vendor/private-images-kots.mdx +++ b/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. + +1. + +1. + +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: diff --git a/embedded-cluster/embedded-using.mdx b/embedded-cluster/embedded-using.mdx index 61903d1055..cc5ee5a710 100644 --- a/embedded-cluster/embedded-using.mdx +++ b/embedded-cluster/embedded-using.mdx @@ -1,39 +1,220 @@ import UpdateOverview from "../docs/partials/embedded-cluster/v3/_update-overview.mdx" import EcConfig from "../docs/partials/embedded-cluster/v3/_ec-config.mdx" import ShellCommand from "../docs/partials/embedded-cluster/_shell-command.mdx" +import RewriteHelmValues from "../docs/partials/proxy-service/_step-rewrite-helm-values.mdx" +import DependencyYaml from "../docs//partials/replicated-sdk/_dependency-yaml.mdx" # Configure Embedded Cluster (Beta) -This topic describes how to configure your application releases to support installations with Replicated Embedded Cluster. For an introduction, see [Embedded Cluster Overview](embedded-overview). +This topic describes how to configure and use Replicated Embedded Cluster with your application. +For more information about Embedded Cluster, see [Embedded Cluster Overview](embedded-overview). For information about updating an existing release from Embedded Cluster v2 to v3, see [Migrate from Embedded Cluster v2](embedded-v3-migrate). -## Add the Embedded Cluster Config resource +## Create a release with Embedded Cluster v3 -An [Embedded Cluster Config](embedded-config) must be present in the release to support installation with Embedded Cluster. The Embedded Cluster Config sets the version of Embedded Cluster to install, and lets you define additional characteristics about the cluster. +To create an application release that supports installation with Embedded Cluster v3: -To add the Embedded Cluster Config: +1. If you use the Replicated proxy registry, update all references to private or third-party images to use the Replicated proxy registry domain. See the _Embedded Cluster v3_ steps in [Configure your application to use the proxy registry](/vendor/private-images-kots#configure-v3). -1. Create a new release that includes your application and a unique [HelmChart v2](/reference/custom-resource-helmchart-v2) custom resource for each Helm chart in the release. +1. In your application Helm chart `Chart.yaml` file, add the SDK as a dependency. If your application uses multiple charts, declare the SDK as a dependency of the chart that customers install first. Do not declare the SDK in more than one chart. - If you have not yet configured the HelmChart custom resource for your application, see [Onboard to the Replicated Platform](/vendor/replicated-onboarding). The onboarding guide provides detailed instructions for configuring releases that support installation with a Replicated installer. + -1. In the release, add an [Embedded Cluster Config](embedded-config) manifest that specifies the Embedded Cluster version to use: +1. Package each chart into a `.tgz` chart archive. See [Package a Helm chart for a release](/vendor/helm-install-release). + +1. For each chart archive, add a unique HelmChart v2 custom resource (version `kots.io/v1beta2`). + + ```yaml + # HelmChart custom resource + apiVersion: kots.io/v1beta2 + kind: HelmChart + metadata: + name: samplechart + spec: + # chart identifies a matching chart from a .tgz + chart: + name: samplechart + chartVersion: 3.1.7 + ``` + +1. If you support air gap installations, update all image references so they resolve correctly in both online and air gap installations. See [Add support for air gap installations](#local-image-registry) on this page. + +1. Add an [Embedded Cluster Config](embedded-config) manifest to the release. At minimum, the Config must specify the Embedded Cluster version to use. -1. If your application requires that Embedded Cluster deploy certain components before the application and as part of the cluster itself, update the Embedded Cluster Config to add [extensions](embedded-config#extensions). +1. If you use custom domains for the Replicated proxy registry or Replicated app service, add them to the Embedded Cluster Config `domains` key. See [Configure Embedded Cluster to use custom domains](/vendor/custom-domains-using#ec) in _Use custom domains_. + +1. If you need Embedded Cluster to deploy certain components to the cluster before it deploys your application, add the Helm charts for those components to the Embedded Cluster Config `extensions` key. See [(Optional) Add Helm chart extensions](#add-extensions) on this page. 1. Save the release and promote it to the channel that you use for testing internally. 1. Install with Embedded Cluster in a development environment to test. See [Online installation with Embedded Cluster](installing-embedded) or [Air gap installation with Embedded Cluster](installing-embedded-air-gap). -1. After successfully installing your application with Embedded Cluster, customize the [Embedded Cluster Config](embedded-config) as desired: - * Add your custom domain for the Replicated proxy registry and Replicated app service. See [domains](embedded-config#domains). - * Add custom Helm extensions. Extensions allow you to provide Helm charts that Embedded Cluster deploys before your application. For example, you can add a Helm extension to ship an ingress controller. See [extensions](embedded-config#extensions). - * Define roles to assign workloads to specific nodes in multi-node installations. See [roles](/embedded-cluster/v2/embedded-config#roles). - - Replicated recommends that you work in small iterations and test your changes frequently in your development environment. +## Add support for air gap installations {#local-image-registry} + +To support air gap installations: + +1. Configure each HelmChart custom resource's `builder` key. This ensures that all the required and optional images for your application are available in environments without internet access. See [`builder`](/reference/custom-resource-helmchart-v2#builder) in _HelmChart v2_. + +1. Configure each HelmChart custom resource to ensure that all image reference resolve correctly in online and air gap installations. You do this in the HelmChart custom resource's [`values`](/reference/custom-resource-helmchart-v2#values) key using the [ReplicatedImageName](template-functions#replicatedimagename), [ReplicatedImageRegistry](template-functions#replicatedimageregistry), and [ReplicatedImageRepository](template-functions#replicatedimagerepository) template functions. See the following examples for more information: + +
+ + Example (Single value for full image name) + + For charts that expect the full image reference in a single field, use the [ReplicatedImageName](template-functions#replicatedimagename) template function in the HelmChart custom resource. ReplicatedImageName returns the full image name, including both the repository and registry. + + For example: + + ```yaml + # values.yaml + initImage: proxy.replicated.com/proxy/my-app/docker.io/library/busybox:1.36 + ``` + ```yaml + # HelmChart custom resource + apiVersion: kots.io/v1beta2 + kind: HelmChart + spec: + values: + initImage: '{{repl ReplicatedImageName (HelmValue ".initImage") true }}' + ``` + ReplicatedImageName sets `noProxy` to `true` because the image reference value in `values.yaml` already contains the proxy path prefix (`proxy.replicated.com/proxy/my-app/...`) +
+ +
+ + Example (Separate values for image registry and repository) + + If a chart uses separate registry and repository fields for image references, use the [ReplicatedImageRegistry](template-functions#replicatedimageregistry) and [ReplicatedImageRepository](template-functions#replicatedimagerepository) template functions in the HelmChart custom resource: + + ```yaml + # values.yaml + image: + registry: proxy.replicated.com + repository: proxy/my-app/ghcr.io/my-org/my-image + tag: v1.0.0 + ``` + + ```yaml + # HelmChart custom resource + apiVersion: kots.io/v1beta2 + kind: HelmChart + spec: + values: + image: + registry: '{{repl ReplicatedImageRegistry (HelmValue ".image.registry") }}' + repository: '{{repl ReplicatedImageRepository (HelmValue ".image.repository") true }}' + ``` + ReplicatedImageRepository sets `noProxy` to `true` because the repository value in `values.yaml` already contains the proxy path prefix (`proxy/my-app/...`). ReplicatedImageRegistry omits `noProxy` so the function returns the correct proxy domain for the installation, including any [custom domain](/vendor/custom-domains) configuration. +
+ +
+ Example (References to public images) + + For public images that don't go through the Replicated proxy registry, set the upstream reference directly in the chart's `values.yaml`. Use `noProxy` so the reference remains unchanged in online installations but is still rewritten for air gap. + + ```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 }}' + ``` +
+ +1. In the HelmChart resource that corresponds to the chart where you included the Replicated SDK as a dependency, rewrite the Replicated SDK image reference using the [ReplicatedImageRegistry](template-functions#replicatedimageregistry) and [ReplicatedImageRepository](template-functions#replicatedimagerepository) template functions: + + ```yaml + # HelmChart custom resource + apiVersion: kots.io/v1beta2 + kind: HelmChart + spec: + values: + replicated: + image: + registry: '{{repl ReplicatedImageRegistry (HelmValue ".replicated.image.registry") }}' + # The default location for the SDK image is + # proxy.replicated.com/library/replicated-sdk-image + repository: '{{repl ReplicatedImageRepository (HelmValue ".replicated.image.repository") true }}' + ``` + +1. If you added any Helm chart `extensions` in the Embedded Cluster Config, rewrite image references in each extension using either the [ReplicatedImageName](template-functions#replicatedimagename) template function (if the chart uses a single field for the full image reference) or the [ReplicatedImageRegistry](template-functions#replicatedimageregistry) and [ReplicatedImageRepository](template-functions#replicatedimagerepository) template functions (if the chart uses separate fields for the image registry and repository values). + +
+ Example (Extension for a Helm chart that you own) + + ```yaml + # Embedded Cluster Config + apiVersion: embeddedcluster.replicated.com/v1beta1 + kind: Config + spec: + extensions: + helmCharts: + - chart: + name: ingress + chartVersion: "1.2.3" + releaseName: ingress + namespace: ingress + values: | + controller: + image: + registry: 'repl{{ ReplicatedImageRegistry (HelmValue ".controller.image.registry") }}' + repository: 'repl{{ ReplicatedImageRepository (HelmValue ".controller.image.repository") true }}' + ``` +
+ +
+ Example (Extension for a third-party Helm chart) + + ```yaml + # Embedded Cluster Config + apiVersion: embeddedcluster.replicated.com/v1beta1 + kind: Config + spec: + 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" }}' + ``` + The template functions will add the proxy prefix in online installations and rewrite to the local registry in air gap installations. + + ReplicatedImageRepository requires the full upstream image path including the registry (for example, `registry.k8s.io/ingress-nginx/controller`), not just the repository. +
+ + +1. Save the release and promote it to the channel that you use for testing internally. + +1. Install with Embedded Cluster in a development environment to test. See [Air gap installation with Embedded Cluster](installing-embedded-air-gap). + +## Add Helm chart extensions {#add-extensions} + +If your application requires certain components deployed before the application and as part of the cluster itself, add them as [extensions](embedded-config#extensions) in the Embedded Cluster Config. For example, you can add a Helm extension to deploy an ingress controller. You can add extensions for Helm charts that you own or for third-party charts. + +To add Helm extensions: + +1. In the Embedded Cluster Config, add the Helm chart to the [`extensions`](embedded-config#extensions) key. + +1. If you support air gap installations, configure each of your `extensions` so that they resolve correctly for both online and air gap installations. See [Add support for air gap installations](#local-image-registry) on this page. + +1. Save the release and promote it to the channel that you use for testing internally. + +1. Install with Embedded Cluster in a development environment to test. See [Online installation with Embedded Cluster](installing-embedded) or [Air gap installation with Embedded Cluster](installing-embedded-air-gap). -## (Optional) Serve installation assets using the Vendor API +## Serve installation assets using the Vendor API To install with Embedded Cluster, your end customers need to download the Embedded Cluster installer binary and their license. Air gap installations also require an air gap bundle. End customers can download all these installation assets using a curl command by following the installation steps available in the [Replicated Enterprise Portal](/vendor/enterprise-portal-about). @@ -92,6 +273,6 @@ Using the NVIDIA GPU Operator with Embedded Cluster requires configuring the con When you configure the containerd options as shown earlier on this page, the NVIDIA GPU Operator automatically creates the required configurations in the `/etc/k0s/containerd.d/nvidia.toml` file. It is not necessary to create this file manually, or modify any other configuration on the hosts. -If you include the NVIDIA GPU Operator as a Helm extension, remove any existing containerd services running on the host (such as those deployed by Docker) before installing the release with Embedded Cluster. If any containerd services are present on the host, the NVIDIA GPU Operator will generate an invalid containerd config, causing the installation to fail. For more information, see [Installation failure when NVIDIA GPU Operator is included as Helm extension](#nvidia-gpu-operator) in _Troubleshooting Embedded Cluster_. +If you include the NVIDIA GPU Operator as a Helm extension, remove any existing containerd services from the host before installing with Embedded Cluster. This includes services deployed by Docker. If any containerd services are present on the host, the NVIDIA GPU Operator will generate an invalid containerd config, causing the installation to fail. For more information, see [Installation failure when NVIDIA GPU Operator is included as Helm extension](#nvidia-gpu-operator) in _Troubleshooting Embedded Cluster_. This is the result of a known issue with v24.9.x of the NVIDIA GPU Operator. For more information about the known issue, see [container-toolkit does not modify the containerd config correctly when there are multiple instances of the containerd binary](https://github.com/NVIDIA/nvidia-container-toolkit/issues/982) in the nvidia-container-toolkit repository in GitHub. diff --git a/embedded-cluster/embedded-v3-migrate.mdx b/embedded-cluster/embedded-v3-migrate.mdx index d1b3f81a5a..661465dc98 100644 --- a/embedded-cluster/embedded-v3-migrate.mdx +++ b/embedded-cluster/embedded-v3-migrate.mdx @@ -26,30 +26,43 @@ Because Embedded Cluster v3 removes KOTS, you must include the [Replicated SDK]( ### Troubleshoot Preflight `v1beta3` required Application preflight checks must use Troubleshoot `v1beta3`. `v1beta2` preflight specs are not supported. - For more information, see [v1beta3 overview](https://troubleshoot.sh/docs/preflight/v1beta3-overview) in the Troubleshoot documentation. +### Package your application with Helm + +To use Embedded Cluster v3, package your application as one or more Helm charts. Embedded Cluster v3 does not support Kustomize or Kubernetes manifests. + ### HelmChart v2 required -Embedded Cluster v3 supports installing Helm charts with a corresponding HelmChart v2 custom resource (API version `v1beta2`). +Embedded Cluster v3 supports installing Helm charts with a corresponding HelmChart v2 custom resource (API version `v1beta2`). It does not support HelmChart v1. + +### Automatic authentication to the Replicated proxy registry -Embedded Cluster v3 does not support Kustomize, Kubernetes manifests, or HelmChart v1. +If your application uses the Replicated proxy registry, Embedded Cluster v2 configures the cluster to automatically authenticate to the proxy registry for all pods. This means that it's no longer necessary to manually inject a Replicated pull secret using the ImagePullSecretName template function. ## Update your release to Embedded Cluster v3 -To update your release to support installation with Embedded Cluster v3: +To update a release from Embedded Cluster v2 to v3: -1. Remove any standalone Kubernetes manifests or `kustomization.yaml` files from your release. Embedded Cluster v3 only deploys resources that are managed by Helm charts. If you need to deploy any resources before Embedded Cluster deploys your application, you can use Helm chart [`extensions`](embedded-config#extensions) in the Embedded Cluster Config. +1. Remove any standalone Kubernetes manifests or `kustomization.yaml` files from your release. Embedded Cluster v3 only deploys resources defined in Helm charts. If you need to deploy any resources before Embedded Cluster deploys your application, you can use Helm chart [`extensions`](embedded-config#extensions) in the Embedded Cluster Config. -1. In your application Helm chart `Chart.yaml` file, add the SDK as a dependency. With Embedded Cluster v3, the SDK is required to get instance insights from status informers. +1. In your application Helm chart `Chart.yaml` file, add the SDK as a dependency. With Embedded Cluster v3, you must include the SDK to get instance insights from status informers. - If your application is installed as multiple charts, declare the SDK as a dependency of the chart that customers install first. Do not declare the SDK in more than one chart. + If your application uses multiple charts, declare the SDK as a dependency of the chart that customers install first. Do not declare the SDK in more than one chart. +1. If you use the Replicated proxy registry, update your release to remove the ImagePullSecretName template function from your HelmChart `values` key. Embedded Cluster v3 configures the cluster to automatically authenticate to the proxy registry for all pods, so you don't need to manually inject a pull secret. See the _Embedded Cluster v3_ steps in [Configure your application to use the proxy registry](/vendor/private-images-kots#configure-v3). + +1. If you support air gap installations, update your image references to use the Embedded Cluster ReplicatedImageName, ReplicatedImageRegistry, and ReplicatedImageRepository template functions. This ensures that image references resolve correctly in both online and air gap installations. See [Add support for air gap installations](embedded-using#local-image-registry). + + :::note + In Embedded Cluster v3, these template functions replace the [LocalImageName](/reference/template-functions-config-context#localimagename), [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost), and [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace) template functions. + ::: + 1. Update your application Preflight specs to API version `troubleshoot.sh/v1beta3`. For more information, see [Migrate from v1beta2 to v1beta3](https://troubleshoot.sh/docs/preflight/v1beta3-migration) in the Troubleshoot documentation. -1. Ensure that your release has a corresponding HelmChart v2 custom resource for each of your Helm charts. For information about how to configure the HelmChart v2 custom resource, see [Support installations with HelmChart v2](/vendor/helm-native-v2-using). For information about how to migrate from HelmChart v1 or Kubernetes manifests to HelmChart v2, see [Migrate existing installations to HelmChart v2](/vendor/helm-v2-migrate). +1. Ensure that your release has a corresponding HelmChart v2 custom resource for each of your Helm charts. For information about how to migrate from HelmChart v1 or Kubernetes manifests to HelmChart v2, see [Migrate existing installations to HelmChart v2](/vendor/helm-v2-migrate). 1. In your Embedded Cluster Config, update `version` to the latest version of Embedded Cluster v3. You can also optionally increment the Kubernetes version by one minor version. diff --git a/embedded-cluster/template-functions.mdx b/embedded-cluster/template-functions.mdx new file mode 100644 index 0000000000..c5a19e4bcc --- /dev/null +++ b/embedded-cluster/template-functions.mdx @@ -0,0 +1,204 @@ +--- +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). + +## 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), [ReplicatedImageRegistry](#replicatedimagerepository), 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") }}' + repository: '{{repl ReplicatedImageRepository (HelmValue ".my-subchart.image.repository") true }}' +``` + +## ReplicatedImageName + +```go +func ReplicatedImageName(image string, noProxy ...bool) string +``` + +Returns a full image reference, including the registry, repository, and any tags. + +Use this when a chart expects the entire image reference in a single field. + +### Parameters + +#### image + +The image reference to rewrite. +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.replicated.com/proxy//`, where `app-slug` is the unique application slug | +| 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: `//:` | + +### Examples + +#### Public image (noProxy) + +```yaml +# HelmChart custom resource +values: + publicImage: '{{repl ReplicatedImageName (HelmValue ".publicImage") true }}' +``` + +#### Private image + +```yaml +# HelmChart custom resource +apiVersion: kots.io/v1beta2 +kind: HelmChart +spec: + values: + initImage: '{{repl ReplicatedImageName (HelmValue ".initImage") }}' +``` + +## ReplicatedImageRegistry + +```go +func ReplicatedImageRegistry(registry string, noProxy ...bool) string +``` + +Returns the registry host. + +Use this with the ReplicatedImageRepository template function when the image reference in the Helm chart uses separate `registry` and `repository` fields. + +### Parameters + +#### image + +The image reference to rewrite. +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 domain (either `proxy.replicated.com` or your [custom domain](/vendor/custom-domains-using)) | +| Online | `true` | Returns the image registry value with no changes | +| Air gap | `true` or omitted | Returns the local registry address | + +### Examples + +#### Rewrite image references using HelmValues + +```yaml +# HelmChart custom resource +apiVersion: kots.io/v1beta2 +kind: HelmChart +spec: + values: + image: + registry: '{{repl ReplicatedImageRegistry (HelmValue ".image.registry") }}' + repository: '{{repl ReplicatedImageRepository (HelmValue ".image.repository") true }}' +``` + +#### 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" }}' + repository: 'repl{{ ReplicatedImageRepository "registry.k8s.io/ingress-nginx/controller" }}' +``` + +## ReplicatedImageRepository + +```go +func ReplicatedImageRepository(repository string, noProxy ...bool) string +``` + +Returns the repository path. + +Use this with the ReplicatedImageRegistry template function when the image reference in the Helm chart uses separate `registry` and `repository` fields. + +### Parameters + +#### image + +The image reference to rewrite. +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 image repository in the format: `proxy//`, where `app_slug` is the unique application slug | +| Online | `true` | Returns the image repository value with no changes | +| Air gap | `true` or omitted | Returns the local image repository in the format: `/` | + +### Examples + +#### Rewrite image references using HelmValues + +```yaml +# HelmChart custom resource +apiVersion: kots.io/v1beta2 +kind: HelmChart +spec: + values: + image: + registry: '{{repl ReplicatedImageRegistry (HelmValue ".image.registry") }}' + repository: '{{repl ReplicatedImageRepository (HelmValue ".image.repository") true }}' +``` + +#### 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" }}' + repository: 'repl{{ ReplicatedImageRepository "registry.k8s.io/ingress-nginx/controller" }}' +``` diff --git a/sidebarEmbeddedCluster.js b/sidebarEmbeddedCluster.js index 11bea866dc..d792745624 100644 --- a/sidebarEmbeddedCluster.js +++ b/sidebarEmbeddedCluster.js @@ -1,9 +1,8 @@ module.exports = { embeddedClusterSidebar: [ "embedded-overview", - "embedded-v3-migrate", "embedded-using", - "embedded-config", + "embedded-v3-migrate", { type: "category", @@ -17,6 +16,10 @@ module.exports = { "embedded-manage-nodes", "updating-embedded", "embedded-troubleshooting", + //REFERENCE DOCS + { type: "html", value: "
Reference
", defaultStyle: true }, + "embedded-config", + "template-functions", { type: "category", label: "Embedded Cluster Commands",