From 84686646293d3204009ad66dc7d95a49abe855bd Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Mon, 21 Apr 2025 09:37:56 -0600 Subject: [PATCH 01/14] wip --- docs/vendor/helm-native-v2-using.md | 101 +++++++++++----------------- 1 file changed, 38 insertions(+), 63 deletions(-) diff --git a/docs/vendor/helm-native-v2-using.md b/docs/vendor/helm-native-v2-using.md index 11f2dfd1ab..f0c93e39ee 100644 --- a/docs/vendor/helm-native-v2-using.md +++ b/docs/vendor/helm-native-v2-using.md @@ -1,16 +1,19 @@ import KotsHelmCrDescription from "../partials/helm/_kots-helm-cr-description.mdx" -# Configure the HelmChart Custom Resource v2 +# Configure the HelmChart Custom Resource -This topic describes how to configure the Replicated HelmChart custom resource version `kots.io/v1beta2` to support Helm chart installations with Replicated KOTS. +This topic describes how to configure the Replicated KOTS HelmChart custom resource. The information in this topic applies to existing cluster KOTS installations, Replicated Embedded Cluster installations, and Replicated kURL installations for applications packaged with Helm. + +For more information about how KOTS uses the HelmChart custom resource to install Helm charts, see [About Distributing Helm Charts with KOTS](/vendor/helm-native-about). ## Workflow -To support Helm chart installations with the KOTS `kots.io/v1beta2` HelmChart custom resource, do the following: -1. Rewrite image names to use the Replicated proxy registry. See [Rewrite Image Names](#rewrite-image-names). -1. Inject a KOTS-generated image pull secret that grants proxy access to private images. See [Inject Image Pull Secrets](#inject-image-pull-secrets). +To configure the HelmChart custom resource, do the following: + +1. Rewrite image names and Inject a KOTS-generated image pull secret they can be pulled through the Replicated proxy registry. See [Rewrite Image Names](#rewrite-image-names). +1. Inject a KOTS-generated image pull secret that grants proxy access to private images through the Replicated proxy registry. See [Inject Image Pull Secrets](#inject-image-pull-secrets). 1. Add a pull secret for any Docker Hub images that could be rate limited. See [Add Pull Secret for Rate-Limited Docker Hub Images](#docker-secret). -1. Configure the `builder` key to allow your users to push images to their own local registries. See [Support Local Image Registries](#local-registries). +1. Configure the `builder` key to allow your users to push images to their own local registries, such as in air gap installations. See [Configure the `builder` key to Support Local Image Registries](#local-registries). 1. (KOTS Existing Cluster and kURL Installations Only) Add backup labels to your resources to support backup and restore with the KOTS snapshots feature. See [Add Backup Labels for Snapshots](#add-backup-labels-for-snapshots). :::note Snapshots is not supported for installations with Replicated Embedded Cluster. For more information about configuring disaster recovery for Embedded Cluster, see [Disaster Recovery for Embedded Cluster](/vendor/embedded-disaster-recovery). @@ -18,7 +21,11 @@ To support Helm chart installations with the KOTS `kots.io/v1beta2` HelmChart cu ## Task 1: Rewrite Image Names {#rewrite-image-names} -Configure the KOTS HelmChart custom resource `values` key so that KOTS rewrites the names for both private and public images in your Helm values during deployment. This allows images to be accessed at one of the following locations, depending on where they were pushed: +### Overview + +Configure the HelmChart custom resource so that KOTS rewrites the names of images in your Helm values during deployment. + +This allows images to be accessed at one of the following locations, depending on where they were pushed: * The [Replicated proxy registry](private-images-about) (`proxy.replicated.com` or your custom domain) * A public image registry * Your customer's local registry @@ -37,66 +44,34 @@ You will use the following KOTS template functions to conditionally rewrite imag ### Task 1a: Rewrite Private Image Names -For any private images used by your application, configure the HelmChart custom resource so that image names are rewritten to either the Replicated proxy registry (for online installations) or to the local registry in the user's installation environment (for air gap installations or online installations where the user configured a local registry). - -To rewrite image names to the location of the image in the proxy registry, use the format `/proxy//`, where: -* `` is `proxy.replicated.com` or your custom domain. For more information about configuring a custom domain for the proxy registry, see [Use Custom Domains](/vendor/custom-domains-using). -* `` is the unique application slug in the Vendor Portal -* `` is the path to the image in your registry +To rewrite image names to the location of the image in the proxy registry: -For example, if the private image is `quay.io/my-org/nginx:v1.0.1` and `images.yourcompany.com` is the custom proxy registry domain, then the image name should be rewritten to `images.yourcompany.com/proxy/my-app-slug/quay.io/my-org/nginx:v1.0.1`. +1. In the HelmChart custom resource, under the `values` key, rewrite image names using the format `/proxy//`, where: + * `` is `proxy.replicated.com` or your custom domain. For more information about configuring a custom domain for the proxy registry, see [Using Custom Domains](/vendor/custom-domains-using). + * `` is the unique application slug in the Vendor Portal + * `` is the path to the image in your registry -For more information, see the example below. + For example, if the private image is `quay.io/my-org/nginx:v1.0.1` and `images.yourcompany.com` is the custom proxy registry domain, then the image name should be rewritten to `images.yourcompany.com/proxy/my-app-slug/quay.io/my-org/nginx:v1.0.1`. -#### Example - -The following HelmChart custom resource uses the KOTS [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry), [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost), and [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace) template functions to conditionally rewrite an image registry and repository depending on if a local registry is used: - -```yaml -# kots.io/v1beta2 HelmChart custom resource + ```yaml + values: + image: + registry: '{{repl LocalRegistryHost }}' + repository: '{{repl LocalRegistryNamespace }}/gitea' + ``` -apiVersion: kots.io/v1beta2 -kind: HelmChart -metadata: - name: samplechart -spec: - ... - values: - image: - # If a registry is configured by the user or by Embedded Cluster/kURL, use that registry's hostname - # Else use proxy.replicated.com or your custom proxy registry domain - registry: '{{repl HasLocalRegistry | ternary LocalRegistryHost "images.yourcompany.com" }}' - # If a registry is configured by the user or by Embedded Cluster/kURL, use that registry namespace - # Else use the image's namespace at the proxy registry domain - repository: '{{repl HasLocalRegistry | ternary LocalRegistryNamespace "proxy/my-app/quay.io/my-org" }}/nginx' - tag: v1.0.1 -``` +1. Under the `optionalValues` key, use the KOTS [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry), [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost), and [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace) template functions to conditionally rewrite image names. -The `spec.values.image.registry` and `spec.values.image.repository` fields in the HelmChart custom resource above correspond to `image.registry` and `image.repository` fields in the Helm chart `values.yaml` file, as shown below: - -```yaml -# Helm chart values.yaml file - -image: - registry: quay.io - repository: my-org/nginx - tag: v1.0.1 -``` - -During installation, KOTS renders the template functions and sets the `image.registry` and `image.repository` fields in the Helm chart `values.yaml` file based on the value of the corresponding fields in the HelmChart custom resource. - -Any templates in the Helm chart that access the `image.registry` and `image.repository` fields are updated to use the appropriate value, as shown in the example below: - -```yaml -apiVersion: v1 -kind: Pod -metadata: - name: nginx -spec: - containers: - - name: - image: {{ .Values.image.registry }}/{{ .Values.image.repository }}:{{ .Values.image.tag }} -``` + ```yaml + optionalValues: + - when: 'repl{{ HasLocalRegistry }}' + values: + image: + registry: '{{repl LocalRegistryHost }}' + repository: '{{repl LocalRegistryNamespace }}/gitea' + pullSecrets: + - name: '{{repl ImagePullSecretName }}' + ``` ### Task 1b: Rewrite Public Image Names @@ -332,7 +307,7 @@ For more information about the HelmChart custom resource, including the unique r To support the use of local registries with version `kots.io/v1beta2` of the HelmChart custom resource, provide the necessary values in the builder field to render the Helm chart with all of the necessary images so that KOTS knows where to pull the images from to push them into the local registry. -For more information about how to configure the `builder` key, see [Package Air Gap Bundles for Helm Charts](/vendor/helm-packaging-airgap-bundles) and [`builder`](/reference/custom-resource-helmchart-v2#builder) in _HelmChart v2_. +For more information about how to configure the `builder` key, see [Packaging Air Gap Bundles for Helm Charts](/vendor/helm-packaging-airgap-bundles) and [`builder`](/reference/custom-resource-helmchart-v2#builder) in _HelmChart v2_. The `kots.io/v1beta2` HelmChart custom resource has the following differences from `kots.io/v1beta1`: From 6f3daa36fb16f20620121278ef16e019b26fccb3 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Mon, 21 Apr 2025 11:18:55 -0600 Subject: [PATCH 02/14] wip --- docs/vendor/helm-native-v2-using.md | 195 +++++++--------------------- 1 file changed, 49 insertions(+), 146 deletions(-) diff --git a/docs/vendor/helm-native-v2-using.md b/docs/vendor/helm-native-v2-using.md index f0c93e39ee..178015bac5 100644 --- a/docs/vendor/helm-native-v2-using.md +++ b/docs/vendor/helm-native-v2-using.md @@ -10,45 +10,27 @@ For more information about how KOTS uses the HelmChart custom resource to instal To configure the HelmChart custom resource, do the following: -1. Rewrite image names and Inject a KOTS-generated image pull secret they can be pulled through the Replicated proxy registry. See [Rewrite Image Names](#rewrite-image-names). -1. Inject a KOTS-generated image pull secret that grants proxy access to private images through the Replicated proxy registry. See [Inject Image Pull Secrets](#inject-image-pull-secrets). +1. Rewrite image names and inject the KOTS-generated image pull secret. See [Rewrite Image Names](#rewrite-image-names). 1. Add a pull secret for any Docker Hub images that could be rate limited. See [Add Pull Secret for Rate-Limited Docker Hub Images](#docker-secret). -1. Configure the `builder` key to allow your users to push images to their own local registries, such as in air gap installations. See [Configure the `builder` key to Support Local Image Registries](#local-registries). +1. Configure the `builder` key to allow users to push images to their own local registries. See [Configure the `builder` key to Support Local Image Registries](#local-registries). 1. (KOTS Existing Cluster and kURL Installations Only) Add backup labels to your resources to support backup and restore with the KOTS snapshots feature. See [Add Backup Labels for Snapshots](#add-backup-labels-for-snapshots). :::note Snapshots is not supported for installations with Replicated Embedded Cluster. For more information about configuring disaster recovery for Embedded Cluster, see [Disaster Recovery for Embedded Cluster](/vendor/embedded-disaster-recovery). ::: -## Task 1: Rewrite Image Names {#rewrite-image-names} +## Task 1: Rewrite Image Names and Inject the KOTS Pull Secret {#rewrite-image-names} -### Overview - -Configure the HelmChart custom resource so that KOTS rewrites the names of images in your Helm values during deployment. - -This allows images to be accessed at one of the following locations, depending on where they were pushed: +Configure the HelmChart custom resource so that KOTS rewrites the names of images in your Helm values during deployment. Additionally, add the KOTS-generated pull secret for the proxy service. This allows images to be accessed at one of the following locations, depending on where they were pushed: * The [Replicated proxy registry](private-images-about) (`proxy.replicated.com` or your custom domain) * A public image registry * Your customer's local registry * The built-in registry used in Replicated Embedded Cluster or Replicated kURL installations in air-gapped environments -You will use the following KOTS template functions to conditionally rewrite image names depending on where the given image should be accessed: -* [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry): Returns true if the installation environment is configured to use a local image registry. HasLocalRegistry is always true in air gap installations. HasLocalRegistry is also true in online installations if the user configured a local private registry. -* [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost): Returns the host of the local registry that the user configured. Alternatively, for air gap installations with Embedded Cluster or kURL, LocalRegistryHost returns the host of the built-in registry. -* [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace): Returns the namespace of the local registry that the user configured. Alternatively, for air gap installations with Embedded Cluster or kURL, LocalRegistryNamespace returns the namespace of the built-in registry. - -
- What is the registry namespace? - - The registry namespace is the path between the registry and the image name. For example, `images.yourcompany.com/namespace/image:tag`. -
- -### Task 1a: Rewrite Private Image Names - To rewrite image names to the location of the image in the proxy registry: 1. In the HelmChart custom resource, under the `values` key, rewrite image names using the format `/proxy//`, where: * `` is `proxy.replicated.com` or your custom domain. For more information about configuring a custom domain for the proxy registry, see [Using Custom Domains](/vendor/custom-domains-using). - * `` is the unique application slug in the Vendor Portal + * `` is the unique application slug in the Vendor Portal. For more information, see [Get the Application Slug](/vendor/vendor-portal-manage-app#slug). * `` is the path to the image in your registry For example, if the private image is `quay.io/my-org/nginx:v1.0.1` and `images.yourcompany.com` is the custom proxy registry domain, then the image name should be rewritten to `images.yourcompany.com/proxy/my-app-slug/quay.io/my-org/nginx:v1.0.1`. @@ -60,7 +42,7 @@ To rewrite image names to the location of the image in the proxy registry: repository: '{{repl LocalRegistryNamespace }}/gitea' ``` -1. Under the `optionalValues` key, use the KOTS [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry), [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost), and [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace) template functions to conditionally rewrite image names. +1. Under the `optionalValues` key, use the KOTS [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry), [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost), and [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace) template functions to conditionally rewrite private image names. ```yaml optionalValues: @@ -73,123 +55,62 @@ To rewrite image names to the location of the image in the proxy registry: - name: '{{repl ImagePullSecretName }}' ``` -### Task 1b: Rewrite Public Image Names - -For any public images used by your application, configure the HelmChart custom resource so that image names are rewritten to either the location of the image in the public registry (for online installations) or the local registry (for air gap installations or online installations where the user configured a local registry. - -For more information, see the example below. - -#### Example - -The following HelmChart custom resource uses the KOTS [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry), [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost), and [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace) template functions to conditionally rewrite an image registry and repository depending on if a local registry is used: - -```yaml -# kots.io/v1beta2 HelmChart custom resource - -apiVersion: kots.io/v1beta2 -kind: HelmChart -metadata: - name: samplechart -spec: - ... - values: - image: - # If a local registry is used, use that registry's hostname - # Else, use the public registry host (ghcr.io) - registry: '{{repl HasLocalRegistry | ternary LocalRegistryHost "ghcr.io" }}' - # If a local registry is used, use the registry namespace provided - # Else, use the path to the image in the public registry - repository: '{{repl HasLocalRegistry | ternary LocalRegistryNamespace "cloudnative-pg" }}/cloudnative-pg' - tag: catalog-1.24.0 -``` - -The `spec.values.image.registry` and `spec.values.image.repository` fields in the HelmChart custom resource correspond to `image.registry` and `image.repository` fields in the Helm chart `values.yaml` file, as shown in the example below: - -```yaml -# Helm chart values.yaml file - -image: - registry: ghcr.io - repository: cloudnative-pg/cloudnative-pg - tag: catalog-1.24.0 -``` - -During installation, KOTS renders the template functions and sets the `image.registry` and `image.repository` fields in your Helm chart `values.yaml` file based on the value of the corresponding fields in the HelmChart custom resource. Any templates in the Helm chart that access the `image.registry` and `image.repository` fields are updated to use the appropriate value, as shown in the example below: - -```yaml -apiVersion: v1 -kind: Pod -spec: - containers: - - name: - image: {{ .Values.image.registry }}/{{ .Values.image.repository }}:{{ .Values.image.tag }} -``` +1. Under the `optionalValues` key, use the KOTS [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry), [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost), and [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace) template functions to conditionally rewrite public image names. -## Task 2: Inject Image Pull Secrets {#inject-image-pull-secrets} + For any public images used by your application, configure the HelmChart custom resource so that image names are rewritten to either the location of the image in the public registry (for online installations) or the local registry (for air gap installations or online installations where the user configured a local registry. -Kubernetes requires a Secret of type `kubernetes.io/dockerconfigjson` to authenticate with a registry and pull a private image. When you reference a private image in a Pod definition, you also provide the name of the Secret in a `imagePullSecrets` key in the Pod definition. For more information, see [Specifying imagePullSecrets on a Pod](https://kubernetes.io/docs/concepts/containers/images/#specifying-imagepullsecrets-on-a-pod) in the Kubernetes documentation. + ```yaml + # kots.io/v1beta2 HelmChart custom resource -During installation, KOTS creates a `kubernetes.io/dockerconfigjson` type Secret that is based on the customer license. This pull secret grants access to the private image through the Replicated proxy registry or in the Replicated registry. Additionally, if the user configured a local image registry, then the pull secret contains the credentials for the local registry. You must provide the name of this KOTS-generated pull secret in any Pod definitions that reference the private image. + apiVersion: kots.io/v1beta2 + kind: HelmChart + metadata: + name: samplechart + spec: + ... + values: + image: + # If a local registry is used, use that registry's hostname + # Else, use the public registry host (ghcr.io) + registry: '{{repl HasLocalRegistry | ternary LocalRegistryHost "ghcr.io" }}' + # If a local registry is used, use the registry namespace provided + # Else, use the path to the image in the public registry + repository: '{{repl HasLocalRegistry | ternary LocalRegistryNamespace "cloudnative-pg" }}/cloudnative-pg' + tag: catalog-1.24.0 + ``` -You can inject the name of this pull secret into a field in the HelmChart custom resource using the Replicated ImagePullSecretName template function. During installation, KOTS sets the value of the corresponding field in your Helm chart `values.yaml` file with the rendered value of the ImagePullSecretName template function. +1. Add the pull secret. -#### Example + Kubernetes requires a Secret of type `kubernetes.io/dockerconfigjson` to authenticate with a registry and pull a private image. For more information, see [Specifying imagePullSecrets on a Pod](https://kubernetes.io/docs/concepts/containers/images/#specifying-imagepullsecrets-on-a-pod) in the Kubernetes documentation. -The following example shows a `spec.values.image.pullSecrets` array in the HelmChart custom resource that uses the ImagePullSecretName template function to inject the name of the KOTS-generated pull secret: + During installation, KOTS creates a `kubernetes.io/dockerconfigjson` type Secret that is based on the customer license. This pull secret grants access to the private image through the Replicated proxy registry or in the Replicated registry. Additionally, if the user configured a local image registry, then the pull secret contains the credentials for the local registry. You must provide the name of this KOTS-generated pull secret in any Pod definitions that reference the private image. -```yaml -# kots.io/v1beta2 HelmChart custom resource + You can inject the name of this pull secret into a field in the HelmChart custom resource using the Replicated ImagePullSecretName template function. During installation, KOTS sets the value of the corresponding field in your Helm chart `values.yaml` file with the rendered value of the ImagePullSecretName template function. -apiVersion: kots.io/v1beta2 -kind: HelmChart -metadata: - name: samplechart -spec: - values: - image: - # Note: Use proxy.replicated.com or your custom domain - registry: '{{repl HasLocalRegistry | ternary LocalRegistryHost "proxy.replicated.com" }}' - repository: '{{repl HasLocalRegistry | ternary LocalRegistryNamespace "proxy/my-app/ecr.us-east-1.amazonaws.com/my-org" }}/api' - pullSecrets: - - name: '{{repl ImagePullSecretName }}' -``` - -The `spec.values.image.pullSecrets` array in the HelmChart custom resource corresponds to a `image.pullSecrets` array in the Helm chart `values.yaml` file, as shown in the example below: + The following example shows a `spec.values.image.pullSecrets` array in the HelmChart custom resource that uses the ImagePullSecretName template function to inject the name of the KOTS-generated pull secret: -```yaml -# Helm chart values.yaml file + ```yaml + # kots.io/v1beta2 HelmChart custom resource -image: - registry: ecr.us-east-1.amazonaws.com - repository: my-org/api/nginx - pullSecrets: - - name: my-org-secret -``` - -During installation, KOTS renders the ImagePullSecretName template function and adds the rendered pull secret name to the `image.pullSecrets` array in the Helm chart `values.yaml` file. - -Any templates in the Helm chart that access the `image.pullSecrets` field are updated to use the name of the KOTS-generated pull secret, as shown in the example below: - -```yaml -apiVersion: v1 -kind: Pod -metadata: - name: nginx -spec: - containers: - - name: nginx - image: {{ .Values.image.registry }}/{{ .Values.image.repository }} - {{- with .Values.image.pullSecrets }} - imagePullSecrets: - {{- toYaml . | nindent 2 }} - {{- end }} -``` + apiVersion: kots.io/v1beta2 + kind: HelmChart + metadata: + name: samplechart + spec: + values: + image: + # Note: Use proxy.replicated.com or your custom domain + registry: '{{repl HasLocalRegistry | ternary LocalRegistryHost "proxy.replicated.com" }}' + repository: '{{repl HasLocalRegistry | ternary LocalRegistryNamespace "proxy/my-app/ecr.us-east-1.amazonaws.com/my-org" }}/api' + pullSecrets: + - name: '{{repl ImagePullSecretName }}' + ``` -## Task 3: Add Pull Secret for Rate-Limited Docker Hub Images {#docker-secret} +## Task 2: Add Pull Secret for Rate-Limited Docker Hub Images {#docker-secret} Docker Hub enforces rate limits for Anonymous and Free users. To avoid errors caused by reaching the rate limit, your users can run the `kots docker ensure-secret` command, which creates an `-kotsadm-dockerhub` secret for pulling Docker Hub images and applies the secret to Kubernetes manifests that have images. For more information, see [Avoiding Docker Hub Rate Limits](/enterprise/image-registry-rate-limits). -If you are deploying a Helm chart with Docker Hub images that could be rate limited, to support the use of the `kots docker ensure-secret` command, any Pod definitions in your Helm chart templates that reference the rate-limited image must be updated to access the `-kotsadm-dockerhub` pull secret, where `` is your application slug. For more information, see [Get the Application Slug](/vendor/vendor-portal-manage-app#slug). +If you are deploying a Helm chart with Docker Hub images that could be rate limited, to support the use of the `kots docker ensure-secret` command, any Pod definitions in your Helm chart templates that reference the rate-limited image must be updated to access the `-kotsadm-dockerhub` pull secret, where `` is your application slug. You can do this by adding the `-kotsadm-dockerhub` pull secret to a field in the `values` key of the HelmChart custom resource, along with a matching field in your Helm chart `values.yaml` file. During installation, KOTS sets the value of the matching field in the `values.yaml` file with the `-kotsadm-dockerhub` pull secret, and any Helm chart templates that access the value are updated. @@ -228,24 +149,7 @@ spec: - name: example-app-slug-kotsadm-dockerhub ``` -During installation, KOTS adds the `example-app-slug-kotsadm-dockerhub` secret to the `image.pullSecrets` array in the Helm chart `values.yaml` file. Any templates in the Helm chart that access `image.pullSecrets` are updated to use `example-app-slug-kotsadm-dockerhub`: - -```yaml -apiVersion: v1 -kind: Pod -metadata: - name: example -spec: - containers: - - name: example - image: {{ .Values.image.registry }}/{{ .Values.image.repository }} - {{- with .Values.image.pullSecrets }} - imagePullSecrets: - {{- toYaml . | nindent 2 }} - {{- end }} -``` - -## Task 4: Support the Use of Local Image Registries {#local-registries} +## Task 3: Support the Use of Local Image Registries {#local-registries} Local image registries are required for KOTS installations in air-gapped environments with no outbound internet connection. Also, users in online environments can optionally use a local registry. For more information about how users configure a local image registry with KOTS, see [Configuring Local Image Registries](/enterprise/image-registry-settings). @@ -298,7 +202,6 @@ spec: ### About the HelmChart Custom Resource - For more information about the HelmChart custom resource, including the unique requirements and limitations for the keys described in this topic, see [HelmChart v2](/reference/custom-resource-helmchart-v2). From f46f001822acb6eba370d6bf9a8d79db8695275e Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Mon, 21 Apr 2025 11:55:25 -0600 Subject: [PATCH 03/14] wip --- docs/vendor/helm-native-v2-using.md | 101 ++++++++++------------------ 1 file changed, 37 insertions(+), 64 deletions(-) diff --git a/docs/vendor/helm-native-v2-using.md b/docs/vendor/helm-native-v2-using.md index 178015bac5..cf220fa2cf 100644 --- a/docs/vendor/helm-native-v2-using.md +++ b/docs/vendor/helm-native-v2-using.md @@ -18,74 +18,33 @@ To configure the HelmChart custom resource, do the following: Snapshots is not supported for installations with Replicated Embedded Cluster. For more information about configuring disaster recovery for Embedded Cluster, see [Disaster Recovery for Embedded Cluster](/vendor/embedded-disaster-recovery). ::: -## Task 1: Rewrite Image Names and Inject the KOTS Pull Secret {#rewrite-image-names} +## Task 1: Rewrite Image Names and Inject the KOTS Image Pull Secret {#rewrite-image-names} -Configure the HelmChart custom resource so that KOTS rewrites the names of images in your Helm values during deployment. Additionally, add the KOTS-generated pull secret for the proxy service. This allows images to be accessed at one of the following locations, depending on where they were pushed: -* The [Replicated proxy registry](private-images-about) (`proxy.replicated.com` or your custom domain) -* A public image registry -* Your customer's local registry -* The built-in registry used in Replicated Embedded Cluster or Replicated kURL installations in air-gapped environments +Rewriting image names and injecting the KOTS pull secret allows your application images to be accessed at one of the following locations, depending on the installation type and where the given image is available: +* The [Replicated proxy registry](private-images-about) at `proxy.replicated.com` or your custom domain. Private images are pulled through the proxy registry in online installations. +* A public image registry. Any public images that your application uses can be access directly from the public image registry in online installations. +* Your customer's local registry. The most common use case for configuring a local image registry is in KOTS existing cluster installations in air-gapped environments. +* The built-in registry that is used in Replicated Embedded Cluster or Replicated kURL installations in air-gapped environments. -To rewrite image names to the location of the image in the proxy registry: +To rewrite image names and inject the KOTS image pull secret: -1. In the HelmChart custom resource, under the `values` key, rewrite image names using the format `/proxy//`, where: - * `` is `proxy.replicated.com` or your custom domain. For more information about configuring a custom domain for the proxy registry, see [Using Custom Domains](/vendor/custom-domains-using). - * `` is the unique application slug in the Vendor Portal. For more information, see [Get the Application Slug](/vendor/vendor-portal-manage-app#slug). - * `` is the path to the image in your registry +1. In the HelmChart custom resource, under the `values` key, rewrite _private_ image names using the format `PROXY_DOMAIN/proxy/APP_SLUG/IMAGE`, where: - For example, if the private image is `quay.io/my-org/nginx:v1.0.1` and `images.yourcompany.com` is the custom proxy registry domain, then the image name should be rewritten to `images.yourcompany.com/proxy/my-app-slug/quay.io/my-org/nginx:v1.0.1`. + * `PROXY_DOMAIN` is `proxy.replicated.com` or your custom domain. For more information about configuring a custom domain for the proxy registry, see [Using Custom Domains](/vendor/custom-domains-using). - ```yaml - values: - image: - registry: '{{repl LocalRegistryHost }}' - repository: '{{repl LocalRegistryNamespace }}/gitea' - ``` + * `APP_SLUG` is the unique application slug in the Vendor Portal. For more information, see [Get the Application Slug](/vendor/vendor-portal-manage-app#slug). -1. Under the `optionalValues` key, use the KOTS [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry), [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost), and [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace) template functions to conditionally rewrite private image names. + * `IMAGE` is the path to the image in your registry - ```yaml - optionalValues: - - when: 'repl{{ HasLocalRegistry }}' - values: - image: - registry: '{{repl LocalRegistryHost }}' - repository: '{{repl LocalRegistryNamespace }}/gitea' - pullSecrets: - - name: '{{repl ImagePullSecretName }}' - ``` - -1. Under the `optionalValues` key, use the KOTS [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry), [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost), and [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace) template functions to conditionally rewrite public image names. - - For any public images used by your application, configure the HelmChart custom resource so that image names are rewritten to either the location of the image in the public registry (for online installations) or the local registry (for air gap installations or online installations where the user configured a local registry. - - ```yaml - # kots.io/v1beta2 HelmChart custom resource - - apiVersion: kots.io/v1beta2 - kind: HelmChart - metadata: - name: samplechart - spec: - ... - values: - image: - # If a local registry is used, use that registry's hostname - # Else, use the public registry host (ghcr.io) - registry: '{{repl HasLocalRegistry | ternary LocalRegistryHost "ghcr.io" }}' - # If a local registry is used, use the registry namespace provided - # Else, use the path to the image in the public registry - repository: '{{repl HasLocalRegistry | ternary LocalRegistryNamespace "cloudnative-pg" }}/cloudnative-pg' - tag: catalog-1.24.0 - ``` + For example, if the private image is `quay.io/my-org/nginx:v1.0.1` and `images.yourcompany.com` is the custom proxy registry domain, then the image name should be rewritten to `images.yourcompany.com/proxy/your-app-slug/quay.io/my-org/nginx:v1.0.1`. -1. Add the pull secret. - - Kubernetes requires a Secret of type `kubernetes.io/dockerconfigjson` to authenticate with a registry and pull a private image. For more information, see [Specifying imagePullSecrets on a Pod](https://kubernetes.io/docs/concepts/containers/images/#specifying-imagepullsecrets-on-a-pod) in the Kubernetes documentation. +1. Add the KOTS-generated pull secret to provide authentication for the proxy registry. During installation, KOTS creates a `kubernetes.io/dockerconfigjson` type Secret that is based on the customer license. This pull secret grants access to the private image through the Replicated proxy registry or in the Replicated registry. Additionally, if the user configured a local image registry, then the pull secret contains the credentials for the local registry. You must provide the name of this KOTS-generated pull secret in any Pod definitions that reference the private image. + + For more information about the `kubernetes.io/dockerconfigjson` type Secret required by Kubernetes to authenticate with a registry and pull a private image, see [Specifying imagePullSecrets on a Pod](https://kubernetes.io/docs/concepts/containers/images/#specifying-imagepullsecrets-on-a-pod) in the Kubernetes documentation. - You can inject the name of this pull secret into a field in the HelmChart custom resource using the Replicated ImagePullSecretName template function. During installation, KOTS sets the value of the corresponding field in your Helm chart `values.yaml` file with the rendered value of the ImagePullSecretName template function. + **Example:** The following example shows a `spec.values.image.pullSecrets` array in the HelmChart custom resource that uses the ImagePullSecretName template function to inject the name of the KOTS-generated pull secret: @@ -99,13 +58,25 @@ To rewrite image names to the location of the image in the proxy registry: spec: values: image: - # Note: Use proxy.replicated.com or your custom domain - registry: '{{repl HasLocalRegistry | ternary LocalRegistryHost "proxy.replicated.com" }}' - repository: '{{repl HasLocalRegistry | ternary LocalRegistryNamespace "proxy/my-app/ecr.us-east-1.amazonaws.com/my-org" }}/api' + registry: + repository: pullSecrets: - name: '{{repl ImagePullSecretName }}' ``` +1. Configure the `optionalValues` key so that KOTS conditionally rewrites private _and_ public image names only when there is a local image registry configured in the installation environment. You can do this using the KOTS [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry), [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost), and [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace) template functions. + + **Example:** + + ```yaml + optionalValues: + - when: 'repl{{ HasLocalRegistry }}' + values: + image: + registry: '{{repl LocalRegistryHost }}' + repository: '{{repl LocalRegistryNamespace }}/gitea' + ``` + ## Task 2: Add Pull Secret for Rate-Limited Docker Hub Images {#docker-secret} Docker Hub enforces rate limits for Anonymous and Free users. To avoid errors caused by reaching the rate limit, your users can run the `kots docker ensure-secret` command, which creates an `-kotsadm-dockerhub` secret for pulling Docker Hub images and applies the secret to Kubernetes manifests that have images. For more information, see [Avoiding Docker Hub Rate Limits](/enterprise/image-registry-rate-limits). @@ -151,14 +122,16 @@ spec: ## Task 3: Support the Use of Local Image Registries {#local-registries} -Local image registries are required for KOTS installations in air-gapped environments with no outbound internet connection. Also, users in online environments can optionally use a local registry. For more information about how users configure a local image registry with KOTS, see [Configuring Local Image Registries](/enterprise/image-registry-settings). +Local image registries are required for KOTS installations in air-gapped environments with no outbound internet connection. Also, users in online environments can optionally use a local registry. + +To support the use of local registries, configure the `builder` key. For information about how to configure the `builder` key, see [`builder`](/reference/custom-resource-helmchart-v2#builder) in _HelmChart v2_. -To support the use of local registries, configure the `builder` key. For more information about how to configure the `builder` key, see [`builder`](/reference/custom-resource-helmchart-v2#builder) in _HelmChart v2_. +For more information about how users configure a local image registry with KOTS, see [Configuring Local Image Registries](/enterprise/image-registry-settings). -## Task 5: Add Backup Labels for Snapshots (KOTS Existing Cluster and kURL Installations Only) {#add-backup-labels-for-snapshots} +## (KOTS Existing Cluster and kURL Installations Only) Task 4: Add Backup Labels for Snapshots {#add-backup-labels-for-snapshots} :::note -The Replicated [snapshots](snapshots-overview) feature for backup and restsore is supported only for existing cluster installations with KOTS. Snapshots are not support for installations with Embedded Cluster. For more information about disaster recovery for installations with Embedded Cluster, see [Disaster Recovery for Embedded Cluster](/vendor/embedded-disaster-recovery.mdx). +The Replicated [snapshots](snapshots-overview) feature for backup and restsore is supported only for KOTS existing cluster and kURL installations. Snapshots are not support for installations with Embedded Cluster. For more information about disaster recovery for installations with Embedded Cluster, see [Disaster Recovery for Embedded Cluster](/vendor/embedded-disaster-recovery.mdx). ::: The snapshots feature requires the following labels on all resources in your Helm chart that you want to be included in the backup: From abb52c086e5c19b82881d6701303926bf4cf8ccd Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Mon, 21 Apr 2025 13:57:21 -0600 Subject: [PATCH 04/14] wip --- docs/vendor/helm-native-v2-using.md | 45 ++++++++++++++++++++++++----- 1 file changed, 37 insertions(+), 8 deletions(-) diff --git a/docs/vendor/helm-native-v2-using.md b/docs/vendor/helm-native-v2-using.md index cf220fa2cf..4cacc65275 100644 --- a/docs/vendor/helm-native-v2-using.md +++ b/docs/vendor/helm-native-v2-using.md @@ -36,20 +36,41 @@ To rewrite image names and inject the KOTS image pull secret: * `IMAGE` is the path to the image in your registry - For example, if the private image is `quay.io/my-org/nginx:v1.0.1` and `images.yourcompany.com` is the custom proxy registry domain, then the image name should be rewritten to `images.yourcompany.com/proxy/your-app-slug/quay.io/my-org/nginx:v1.0.1`. + **Example:** + + ```yaml + # KOTS HelmChart custom resource + + apiVersion: kots.io/v1beta2 + kind: HelmChart + metadata: + name: samplechart + spec: + values: + api: + image: + # proxy.registry.com or your custom domain + registry: proxy.yourcompany.com + repository: proxy/app/ghcr.io/cloudnative-pg/cloudnative-pg + tag: catalog-1.24.0 + ``` 1. Add the KOTS-generated pull secret to provide authentication for the proxy registry. - During installation, KOTS creates a `kubernetes.io/dockerconfigjson` type Secret that is based on the customer license. This pull secret grants access to the private image through the Replicated proxy registry or in the Replicated registry. Additionally, if the user configured a local image registry, then the pull secret contains the credentials for the local registry. You must provide the name of this KOTS-generated pull secret in any Pod definitions that reference the private image. +
+ What is the KOTS-generated pull secret? + + During installation, KOTS creates a `kubernetes.io/dockerconfigjson` type Secret that is based on the customer license. This pull secret grants access to the private image through the Replicated proxy registry or in the Replicated registry. Additionally, if the user configured a local image registry, then the pull secret contains the credentials for the local registry. You must provide the name of this KOTS-generated pull secret in any Pod definitions that reference the private image. For more information about the `kubernetes.io/dockerconfigjson` type Secret required by Kubernetes to authenticate with a registry and pull a private image, see [Specifying imagePullSecrets on a Pod](https://kubernetes.io/docs/concepts/containers/images/#specifying-imagepullsecrets-on-a-pod) in the Kubernetes documentation. +
**Example:** The following example shows a `spec.values.image.pullSecrets` array in the HelmChart custom resource that uses the ImagePullSecretName template function to inject the name of the KOTS-generated pull secret: ```yaml - # kots.io/v1beta2 HelmChart custom resource + # KOTS HelmChart custom resource apiVersion: kots.io/v1beta2 kind: HelmChart @@ -57,11 +78,14 @@ To rewrite image names and inject the KOTS image pull secret: name: samplechart spec: values: - image: - registry: - repository: - pullSecrets: - - name: '{{repl ImagePullSecretName }}' + api: + image: + # proxy.registry.com or your custom domain + registry: proxy.yourcompany.com + repository: proxy/app/ghcr.io/cloudnative-pg/cloudnative-pg + tag: catalog-1.24.0 + pullSecrets: + - name: '{{repl ImagePullSecretName }}' ``` 1. Configure the `optionalValues` key so that KOTS conditionally rewrites private _and_ public image names only when there is a local image registry configured in the installation environment. You can do this using the KOTS [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry), [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost), and [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace) template functions. @@ -76,6 +100,11 @@ To rewrite image names and inject the KOTS image pull secret: registry: '{{repl LocalRegistryHost }}' repository: '{{repl LocalRegistryNamespace }}/gitea' ``` +
+ What is the registry namespace? + + The registry namespace is the path between the registry and the image name. For example, `images.yourcompany.com/namespace/image:tag`. +
## Task 2: Add Pull Secret for Rate-Limited Docker Hub Images {#docker-secret} From 41ae3f456918f2a2ae1b0a498c934ba620294072 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Mon, 21 Apr 2025 14:36:54 -0600 Subject: [PATCH 05/14] wip --- docs/vendor/helm-native-v2-using.md | 24 ++++++++---------------- 1 file changed, 8 insertions(+), 16 deletions(-) diff --git a/docs/vendor/helm-native-v2-using.md b/docs/vendor/helm-native-v2-using.md index 4cacc65275..50cd9ad86a 100644 --- a/docs/vendor/helm-native-v2-using.md +++ b/docs/vendor/helm-native-v2-using.md @@ -6,19 +6,7 @@ This topic describes how to configure the Replicated KOTS HelmChart custom resou For more information about how KOTS uses the HelmChart custom resource to install Helm charts, see [About Distributing Helm Charts with KOTS](/vendor/helm-native-about). -## Workflow - -To configure the HelmChart custom resource, do the following: - -1. Rewrite image names and inject the KOTS-generated image pull secret. See [Rewrite Image Names](#rewrite-image-names). -1. Add a pull secret for any Docker Hub images that could be rate limited. See [Add Pull Secret for Rate-Limited Docker Hub Images](#docker-secret). -1. Configure the `builder` key to allow users to push images to their own local registries. See [Configure the `builder` key to Support Local Image Registries](#local-registries). -1. (KOTS Existing Cluster and kURL Installations Only) Add backup labels to your resources to support backup and restore with the KOTS snapshots feature. See [Add Backup Labels for Snapshots](#add-backup-labels-for-snapshots). - :::note - Snapshots is not supported for installations with Replicated Embedded Cluster. For more information about configuring disaster recovery for Embedded Cluster, see [Disaster Recovery for Embedded Cluster](/vendor/embedded-disaster-recovery). - ::: - -## Task 1: Rewrite Image Names and Inject the KOTS Image Pull Secret {#rewrite-image-names} +## Overview Rewriting image names and injecting the KOTS pull secret allows your application images to be accessed at one of the following locations, depending on the installation type and where the given image is available: * The [Replicated proxy registry](private-images-about) at `proxy.replicated.com` or your custom domain. Private images are pulled through the proxy registry in online installations. @@ -26,6 +14,10 @@ Rewriting image names and injecting the KOTS pull secret allows your application * Your customer's local registry. The most common use case for configuring a local image registry is in KOTS existing cluster installations in air-gapped environments. * The built-in registry that is used in Replicated Embedded Cluster or Replicated kURL installations in air-gapped environments. +## Workflow + +### Task 1: Rewrite Image Names and Inject the KOTS Image Pull Secret {#rewrite-image-names} + To rewrite image names and inject the KOTS image pull secret: 1. In the HelmChart custom resource, under the `values` key, rewrite _private_ image names using the format `PROXY_DOMAIN/proxy/APP_SLUG/IMAGE`, where: @@ -106,7 +98,7 @@ To rewrite image names and inject the KOTS image pull secret: The registry namespace is the path between the registry and the image name. For example, `images.yourcompany.com/namespace/image:tag`. -## Task 2: Add Pull Secret for Rate-Limited Docker Hub Images {#docker-secret} +### Task 2: Add Pull Secret for Rate-Limited Docker Hub Images {#docker-secret} Docker Hub enforces rate limits for Anonymous and Free users. To avoid errors caused by reaching the rate limit, your users can run the `kots docker ensure-secret` command, which creates an `-kotsadm-dockerhub` secret for pulling Docker Hub images and applies the secret to Kubernetes manifests that have images. For more information, see [Avoiding Docker Hub Rate Limits](/enterprise/image-registry-rate-limits). @@ -149,7 +141,7 @@ spec: - name: example-app-slug-kotsadm-dockerhub ``` -## Task 3: Support the Use of Local Image Registries {#local-registries} +### Task 3: Support the Use of Local Image Registries {#local-registries} Local image registries are required for KOTS installations in air-gapped environments with no outbound internet connection. Also, users in online environments can optionally use a local registry. @@ -157,7 +149,7 @@ To support the use of local registries, configure the `builder` key. For informa For more information about how users configure a local image registry with KOTS, see [Configuring Local Image Registries](/enterprise/image-registry-settings). -## (KOTS Existing Cluster and kURL Installations Only) Task 4: Add Backup Labels for Snapshots {#add-backup-labels-for-snapshots} +### Task 4: Add Backup Labels for Snapshots {#add-backup-labels-for-snapshots} :::note The Replicated [snapshots](snapshots-overview) feature for backup and restsore is supported only for KOTS existing cluster and kURL installations. Snapshots are not support for installations with Embedded Cluster. For more information about disaster recovery for installations with Embedded Cluster, see [Disaster Recovery for Embedded Cluster](/vendor/embedded-disaster-recovery.mdx). From 8bf11fb7ed4d57a86c2861ca98b5f9d52667d3e7 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Mon, 21 Apr 2025 15:23:10 -0600 Subject: [PATCH 06/14] wip --- docs/vendor/helm-native-v2-using.md | 55 ++++++++++++----------------- 1 file changed, 23 insertions(+), 32 deletions(-) diff --git a/docs/vendor/helm-native-v2-using.md b/docs/vendor/helm-native-v2-using.md index 50cd9ad86a..598477a7e8 100644 --- a/docs/vendor/helm-native-v2-using.md +++ b/docs/vendor/helm-native-v2-using.md @@ -16,11 +16,20 @@ Rewriting image names and injecting the KOTS pull secret allows your application ## Workflow +Complete the tasks in this workflow to configure the HelmChart v2 custom resource. + ### Task 1: Rewrite Image Names and Inject the KOTS Image Pull Secret {#rewrite-image-names} To rewrite image names and inject the KOTS image pull secret: -1. In the HelmChart custom resource, under the `values` key, rewrite _private_ image names using the format `PROXY_DOMAIN/proxy/APP_SLUG/IMAGE`, where: +1. In the HelmChart custom resource, under the `values` key, rewrite the names of any _private_ images used by your application so that they can be accessed through the Replicated proxy registry. + + Use the following format: + + ```yaml + PROXY_DOMAIN/proxy/APP_SLUG/IMAGE + ``` + Where: * `PROXY_DOMAIN` is `proxy.replicated.com` or your custom domain. For more information about configuring a custom domain for the proxy registry, see [Using Custom Domains](/vendor/custom-domains-using). @@ -47,20 +56,18 @@ To rewrite image names and inject the KOTS image pull secret: tag: catalog-1.24.0 ``` -1. Add the KOTS-generated pull secret to provide authentication for the proxy registry. +1. For each image that you included under the `values` key, use the KOTS [ImagePullSecretName](/reference/template-functions-config-context#imagepullsecretname) template function to inject the KOTS-generated image pull secret.
- What is the KOTS-generated pull secret? + What is the KOTS-generated image pull secret? - During installation, KOTS creates a `kubernetes.io/dockerconfigjson` type Secret that is based on the customer license. This pull secret grants access to the private image through the Replicated proxy registry or in the Replicated registry. Additionally, if the user configured a local image registry, then the pull secret contains the credentials for the local registry. You must provide the name of this KOTS-generated pull secret in any Pod definitions that reference the private image. + During installation, KOTS creates a `kubernetes.io/dockerconfigjson` type Secret that is based on the customer license. This pull secret grants access to the images through the Replicated proxy registry. Additionally, if the user configured a local image registry, then the pull secret contains the credentials for the local registry. - For more information about the `kubernetes.io/dockerconfigjson` type Secret required by Kubernetes to authenticate with a registry and pull a private image, see [Specifying imagePullSecrets on a Pod](https://kubernetes.io/docs/concepts/containers/images/#specifying-imagepullsecrets-on-a-pod) in the Kubernetes documentation. + Kubernetes requires a Secret with the type `kubernetes.io/dockerconfigjson` to authenticate with a registry and pull a private image. For more information, see [Specifying imagePullSecrets on a Pod](https://kubernetes.io/docs/concepts/containers/images/#specifying-imagepullsecrets-on-a-pod) in the Kubernetes documentation.
**Example:** - The following example shows a `spec.values.image.pullSecrets` array in the HelmChart custom resource that uses the ImagePullSecretName template function to inject the name of the KOTS-generated pull secret: - ```yaml # KOTS HelmChart custom resource @@ -72,15 +79,15 @@ To rewrite image names and inject the KOTS image pull secret: values: api: image: - # proxy.registry.com or your custom domain registry: proxy.yourcompany.com repository: proxy/app/ghcr.io/cloudnative-pg/cloudnative-pg tag: catalog-1.24.0 + # Inject the pull secret with ImagePullSecretName pullSecrets: - name: '{{repl ImagePullSecretName }}' ``` -1. Configure the `optionalValues` key so that KOTS conditionally rewrites private _and_ public image names only when there is a local image registry configured in the installation environment. You can do this using the KOTS [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry), [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost), and [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace) template functions. +1. In the HelmChart `optionalValues` key, use the KOTS [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry), [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost), and [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace) template functions to conditionally rewrite any private or public images to the location of the image in the user's local image registry, only when a local registry was configured. **Example:** @@ -100,30 +107,13 @@ To rewrite image names and inject the KOTS image pull secret: ### Task 2: Add Pull Secret for Rate-Limited Docker Hub Images {#docker-secret} -Docker Hub enforces rate limits for Anonymous and Free users. To avoid errors caused by reaching the rate limit, your users can run the `kots docker ensure-secret` command, which creates an `-kotsadm-dockerhub` secret for pulling Docker Hub images and applies the secret to Kubernetes manifests that have images. For more information, see [Avoiding Docker Hub Rate Limits](/enterprise/image-registry-rate-limits). - -If you are deploying a Helm chart with Docker Hub images that could be rate limited, to support the use of the `kots docker ensure-secret` command, any Pod definitions in your Helm chart templates that reference the rate-limited image must be updated to access the `-kotsadm-dockerhub` pull secret, where `` is your application slug. - -You can do this by adding the `-kotsadm-dockerhub` pull secret to a field in the `values` key of the HelmChart custom resource, along with a matching field in your Helm chart `values.yaml` file. During installation, KOTS sets the value of the matching field in the `values.yaml` file with the `-kotsadm-dockerhub` pull secret, and any Helm chart templates that access the value are updated. +Docker Hub enforces rate limits for Anonymous and Free users. For more information about Docker Hub rate limiting, see [Understanding Docker Hub rate limiting](https://www.docker.com/increase-rate-limits) on the Docker website. -For more information about Docker Hub rate limiting, see [Understanding Docker Hub rate limiting](https://www.docker.com/increase-rate-limits) on the Docker website. - -#### Example - -The following Helm chart `values.yaml` file includes `image.registry`, `image.repository`, and `image.pullSecrets` for a rate-limited Docker Hub image: - -```yaml -# Helm chart values.yaml file - -image: - registry: docker.io - repository: my-org/example-docker-hub-image - pullSecrets: [] -``` +To avoid errors caused by reaching the rate limit, your users can run the `kots docker ensure-secret` command, which creates an `APP_SLUG-kotsadm-dockerhub` secret for pulling Docker Hub images and applies the secret to Kubernetes manifests that have images. For more information, see [Avoiding Docker Hub Rate Limits](/enterprise/image-registry-rate-limits). -The following HelmChart custom resource includes `spec.values.image.registry`, `spec.values.image.repository`, and `spec.values.image.pullSecrets`, which correspond to those in the Helm chart `values.yaml` file above. +To support the use of the `kots docker ensure-secret` command, add the `APP_SLUG-kotsadm-dockerhub` pull secret (where `APP_SLUG` is your application slug) to any Docker images that could be rate-limited. -The `spec.values.image.pullSecrets` array lists the `-kotsadm-dockerhub` pull secret, where the slug for the application is `example-app-slug`: +**Example:** ```yaml # kots.io/v1beta2 HelmChart custom resource @@ -136,9 +126,10 @@ spec: values: image: registry: docker.io - repository: my-org/example-docker-hub-image + repository: org-name/example-docker-hub-image + # Add the dockerhub secret pullSecrets: - - name: example-app-slug-kotsadm-dockerhub + - name: gitea-kotsadm-dockerhub ``` ### Task 3: Support the Use of Local Image Registries {#local-registries} From aed836cfb278987de6719be2c5689447e7544913 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Mon, 21 Apr 2025 17:54:34 -0600 Subject: [PATCH 07/14] wip --- docs/vendor/helm-native-v2-using.md | 59 +++++++++++++++++++---------- 1 file changed, 38 insertions(+), 21 deletions(-) diff --git a/docs/vendor/helm-native-v2-using.md b/docs/vendor/helm-native-v2-using.md index 598477a7e8..34f97298b4 100644 --- a/docs/vendor/helm-native-v2-using.md +++ b/docs/vendor/helm-native-v2-using.md @@ -1,18 +1,14 @@ import KotsHelmCrDescription from "../partials/helm/_kots-helm-cr-description.mdx" -# Configure the HelmChart Custom Resource +# Configure the HelmChart v2 Custom Resource -This topic describes how to configure the Replicated KOTS HelmChart custom resource. The information in this topic applies to existing cluster KOTS installations, Replicated Embedded Cluster installations, and Replicated kURL installations for applications packaged with Helm. +This topic describes how to configure the Replicated KOTS HelmChart v2 custom resource. The information in this topic applies to existing cluster KOTS installations, Replicated Embedded Cluster installations, and Replicated kURL installations for applications packaged with Helm. For more information about how KOTS uses the HelmChart custom resource to install Helm charts, see [About Distributing Helm Charts with KOTS](/vendor/helm-native-about). ## Overview -Rewriting image names and injecting the KOTS pull secret allows your application images to be accessed at one of the following locations, depending on the installation type and where the given image is available: -* The [Replicated proxy registry](private-images-about) at `proxy.replicated.com` or your custom domain. Private images are pulled through the proxy registry in online installations. -* A public image registry. Any public images that your application uses can be access directly from the public image registry in online installations. -* Your customer's local registry. The most common use case for configuring a local image registry is in KOTS existing cluster installations in air-gapped environments. -* The built-in registry that is used in Replicated Embedded Cluster or Replicated kURL installations in air-gapped environments. +The tasks in this topic involve editing the HelmChart `values` and `optionalValues` keys in order to set Helm values during deployment. For more information about working with these fields, see [`values`](/reference/custom-resource-helmchart-v2#values) and [`optionalValues`](/reference/custom-resource-helmchart-v2#optionalvalues) in _HelmChart v2_. ## Workflow @@ -20,6 +16,12 @@ Complete the tasks in this workflow to configure the HelmChart v2 custom resourc ### Task 1: Rewrite Image Names and Inject the KOTS Image Pull Secret {#rewrite-image-names} +Rewriting image names and injecting the KOTS pull secret allows your application images to be accessed at one of the following locations, depending on the installation type and where the given image is available: +* The [Replicated proxy registry](private-images-about) at `proxy.replicated.com` or your custom domain. Private images are pulled through the proxy registry in online installations. +* A public image registry. Any public images that your application uses can be access directly from the public image registry in online installations. +* Your customer's local registry. The most common use case for configuring a local image registry is in KOTS existing cluster installations in air-gapped environments. +* The built-in registry that is used in Replicated Embedded Cluster or Replicated kURL installations in air-gapped environments. + To rewrite image names and inject the KOTS image pull secret: 1. In the HelmChart custom resource, under the `values` key, rewrite the names of any _private_ images used by your application so that they can be accessed through the Replicated proxy registry. @@ -56,7 +58,7 @@ To rewrite image names and inject the KOTS image pull secret: tag: catalog-1.24.0 ``` -1. For each image that you included under the `values` key, use the KOTS [ImagePullSecretName](/reference/template-functions-config-context#imagepullsecretname) template function to inject the KOTS-generated image pull secret. +1. For each image that you included under the `values` key, use the KOTS [ImagePullSecretName](/reference/template-functions-config-context#imagepullsecretname) template function to inject the KOTS-generated image pull secret, which is used to authenticate with the proxy registry.
What is the KOTS-generated image pull secret? @@ -87,17 +89,34 @@ To rewrite image names and inject the KOTS image pull secret: - name: '{{repl ImagePullSecretName }}' ``` -1. In the HelmChart `optionalValues` key, use the KOTS [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry), [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost), and [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace) template functions to conditionally rewrite any private or public images to the location of the image in the user's local image registry, only when a local registry was configured. +1. In the HelmChart `optionalValues` key, use the KOTS [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry), [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost), and [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace) template functions to conditionally rewrite any private or public images to the location of the image in the user's local image registry. **Example:** ```yaml - optionalValues: - - when: 'repl{{ HasLocalRegistry }}' + # KOTS HelmChart custom resource + + apiVersion: kots.io/v1beta2 + kind: HelmChart + metadata: + name: samplechart + spec: values: - image: - registry: '{{repl LocalRegistryHost }}' - repository: '{{repl LocalRegistryNamespace }}/gitea' + api: + image: + registry: proxy.yourcompany.com + repository: proxy/app/ghcr.io/cloudnative-pg/cloudnative-pg + tag: catalog-1.24.0 + pullSecrets: + - name: '{{repl ImagePullSecretName }}' + optionalValues: + # Define the conditional statement in the when field + - when: 'repl{{ HasLocalRegistry }}' + values: + api: + image: + registry: '{{repl LocalRegistryHost }}' + repository: '{{repl LocalRegistryNamespace }}/cloudnative-pg/cloudnative-pg' ```
What is the registry namespace? @@ -136,14 +155,14 @@ spec: Local image registries are required for KOTS installations in air-gapped environments with no outbound internet connection. Also, users in online environments can optionally use a local registry. -To support the use of local registries, configure the `builder` key. For information about how to configure the `builder` key, see [`builder`](/reference/custom-resource-helmchart-v2#builder) in _HelmChart v2_. +To support the use of local registries, configure the `builder` key in the HelmChart custom resource. For information about how to configure the `builder` key, see [`builder`](/reference/custom-resource-helmchart-v2#builder) in _HelmChart v2_. -For more information about how users configure a local image registry with KOTS, see [Configuring Local Image Registries](/enterprise/image-registry-settings). +For more information about how users can configure and push images to a local registry with KOTS, see [Configuring Local Image Registries](/enterprise/image-registry-settings). -### Task 4: Add Backup Labels for Snapshots {#add-backup-labels-for-snapshots} +### Task 4: (KOTS Existing Cluster and kURL Only) Add Backup Labels for Snapshots {#add-backup-labels-for-snapshots} :::note -The Replicated [snapshots](snapshots-overview) feature for backup and restsore is supported only for KOTS existing cluster and kURL installations. Snapshots are not support for installations with Embedded Cluster. For more information about disaster recovery for installations with Embedded Cluster, see [Disaster Recovery for Embedded Cluster](/vendor/embedded-disaster-recovery.mdx). +The Replicated [snapshots](snapshots-overview) feature for backup and restore is supported only for KOTS existing cluster and kURL installations. Snapshots are not support for installations with Embedded Cluster. For more information about disaster recovery for installations with Embedded Cluster, see [Disaster Recovery for Embedded Cluster](/vendor/embedded-disaster-recovery.mdx). ::: The snapshots feature requires the following labels on all resources in your Helm chart that you want to be included in the backup: @@ -152,9 +171,7 @@ The snapshots feature requires the following labels on all resources in your Hel For more information about snapshots, see [Understanding Backup and Restore](snapshots-overview). -To support backup and restore with snapshots, add the `kots.io/backup: velero` and `kots.io/app-slug: APP_SLUG` labels to fields under the HelmChart custom resource `optionalValues` key. Add a `when` statement that evaluates to true only when the customer license has the `isSnapshotSupported` entitlement. - -The fields that you create under the `optionalValues` key must map to fields in your Helm chart `values.yaml` file. For more information about working with the `optionalValues` key, see [optionalValues](/reference/custom-resource-helmchart-v2#optionalvalues) in _HelmChart v2_. +To support backup and restore with snapshots, edit the the HelmChart custom resource `optionalValues` key to add `kots.io/backup: velero` and `kots.io/app-slug: APP_SLUG` labels to the resources you want backed up. Add a `when` statement that evaluates to true only when the customer license has the `isSnapshotSupported` entitlement. #### Example From ac1d9fe0d20db88f853257154a97b7ec4c1e9c68 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Tue, 22 Apr 2025 10:23:39 -0600 Subject: [PATCH 08/14] wip --- docs/vendor/helm-native-v2-using.md | 48 +++++++++++++++++------------ 1 file changed, 28 insertions(+), 20 deletions(-) diff --git a/docs/vendor/helm-native-v2-using.md b/docs/vendor/helm-native-v2-using.md index 34f97298b4..0a7de0d503 100644 --- a/docs/vendor/helm-native-v2-using.md +++ b/docs/vendor/helm-native-v2-using.md @@ -2,12 +2,14 @@ import KotsHelmCrDescription from "../partials/helm/_kots-helm-cr-description.md # Configure the HelmChart v2 Custom Resource -This topic describes how to configure the Replicated KOTS HelmChart v2 custom resource. The information in this topic applies to existing cluster KOTS installations, Replicated Embedded Cluster installations, and Replicated kURL installations for applications packaged with Helm. +This topic describes how to configure the Replicated KOTS HelmChart v2 custom resource. The information in this topic applies to Replicated KOTS installations in existing clusters, Replicated Embedded Cluster installations, and Replicated kURL installations for applications packaged with Helm. For more information about how KOTS uses the HelmChart custom resource to install Helm charts, see [About Distributing Helm Charts with KOTS](/vendor/helm-native-about). ## Overview + + The tasks in this topic involve editing the HelmChart `values` and `optionalValues` keys in order to set Helm values during deployment. For more information about working with these fields, see [`values`](/reference/custom-resource-helmchart-v2#values) and [`optionalValues`](/reference/custom-resource-helmchart-v2#optionalvalues) in _HelmChart v2_. ## Workflow @@ -24,7 +26,7 @@ Rewriting image names and injecting the KOTS pull secret allows your application To rewrite image names and inject the KOTS image pull secret: -1. In the HelmChart custom resource, under the `values` key, rewrite the names of any _private_ images used by your application so that they can be accessed through the Replicated proxy registry. +1. In your Helm chart `values.yaml` file, rewrite private image names to use the Replicated proxy registry domain. Use the following format: @@ -33,7 +35,7 @@ To rewrite image names and inject the KOTS image pull secret: ``` Where: - * `PROXY_DOMAIN` is `proxy.replicated.com` or your custom domain. For more information about configuring a custom domain for the proxy registry, see [Using Custom Domains](/vendor/custom-domains-using). + * `PROXY_DOMAIN` is `proxy.replicated.com` or your custom domain. For more information about setting a custom domain for the proxy registry, see [Using Custom Domains](/vendor/custom-domains-using). * `APP_SLUG` is the unique application slug in the Vendor Portal. For more information, see [Get the Application Slug](/vendor/vendor-portal-manage-app#slug). @@ -42,6 +44,13 @@ To rewrite image names and inject the KOTS image pull secret: **Example:** ```yaml + # values.yaml + + global: + imageRegistry: proxy.yourcompany.com/proxy/your-app-slug/docker.io + ``` + + -1. For each image that you included under the `values` key, use the KOTS [ImagePullSecretName](/reference/template-functions-config-context#imagepullsecretname) template function to inject the KOTS-generated image pull secret, which is used to authenticate with the proxy registry. +1. In the KOTS HelmChart custom resource, under the `values` key, use the KOTS [ImagePullSecretName](/reference/template-functions-config-context#imagepullsecretname) template function to inject the KOTS-generated image pull secret. This pull secret is used to authenticate with the Replicated proxy registry.
What is the KOTS-generated image pull secret? @@ -79,13 +88,9 @@ To rewrite image names and inject the KOTS image pull secret: name: samplechart spec: values: - api: - image: - registry: proxy.yourcompany.com - repository: proxy/app/ghcr.io/cloudnative-pg/cloudnative-pg - tag: catalog-1.24.0 - # Inject the pull secret with ImagePullSecretName - pullSecrets: + global: + # Inject the pull secret with ImagePullSecretName + imagePullSecrets: - name: '{{repl ImagePullSecretName }}' ``` @@ -101,14 +106,6 @@ To rewrite image names and inject the KOTS image pull secret: metadata: name: samplechart spec: - values: - api: - image: - registry: proxy.yourcompany.com - repository: proxy/app/ghcr.io/cloudnative-pg/cloudnative-pg - tag: catalog-1.24.0 - pullSecrets: - - name: '{{repl ImagePullSecretName }}' optionalValues: # Define the conditional statement in the when field - when: 'repl{{ HasLocalRegistry }}' @@ -124,6 +121,17 @@ To rewrite image names and inject the KOTS image pull secret: The registry namespace is the path between the registry and the image name. For example, `images.yourcompany.com/namespace/image:tag`.
+1. Under the `optionalValues` key, use the same template functions as above to conditionally rewrite the image for the Replicated SDK: + + ```yaml + - when: 'repl{{ HasLocalRegistry }}' + values: + replicated: + image: + registry: '{{repl LocalRegistryHost }}' + repository: '{{repl LocalRegistryNamespace }}/replicated-sdk' + ``` + ### Task 2: Add Pull Secret for Rate-Limited Docker Hub Images {#docker-secret} Docker Hub enforces rate limits for Anonymous and Free users. For more information about Docker Hub rate limiting, see [Understanding Docker Hub rate limiting](https://www.docker.com/increase-rate-limits) on the Docker website. From c607e0cab6162c6ecd3ec466aed626aff9723e37 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Tue, 22 Apr 2025 13:37:31 -0600 Subject: [PATCH 09/14] wip --- docs/vendor/helm-native-v2-using.md | 48 +++++++++++++++++++++-------- 1 file changed, 35 insertions(+), 13 deletions(-) diff --git a/docs/vendor/helm-native-v2-using.md b/docs/vendor/helm-native-v2-using.md index 0a7de0d503..b1fa51e899 100644 --- a/docs/vendor/helm-native-v2-using.md +++ b/docs/vendor/helm-native-v2-using.md @@ -46,8 +46,14 @@ To rewrite image names and inject the KOTS image pull secret: ```yaml # values.yaml - global: - imageRegistry: proxy.yourcompany.com/proxy/your-app-slug/docker.io + postgres: + image: + # proxy.registry.com or your custom domain + registry: proxy.yourcompany.com + repository: proxy/app/ghcr.io/cloudnative-pg/cloudnative-pg + tag: catalog-1.24.0 + imagePullSecrets: + - name: replicated-pull-secret ``` -1. In the KOTS HelmChart custom resource, under the `values` key, use the KOTS [ImagePullSecretName](/reference/template-functions-config-context#imagepullsecretname) template function to inject the KOTS-generated image pull secret. This pull secret is used to authenticate with the Replicated proxy registry. +1. In the KOTS HelmChart custom resource, under the `values` key, use the KOTS [ImagePullSecretName](/reference/template-functions-config-context#imagepullsecretname) template function to set the image pull secret to the KOTS-generated image pull secret. This pull secret is used to authenticate with the Replicated proxy registry.
What is the KOTS-generated image pull secret? @@ -103,6 +102,12 @@ To rewrite image names and inject the KOTS image pull secret: 1. In the HelmChart `optionalValues` key, use the KOTS [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry), [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost), and [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace) template functions so that any private or public images are conditionally rewritten to the location of the image in the user's local image registry, only when a local registry is configured. +
+ What is the registry namespace? + + The registry namespace is the path between the registry and the image name. For example, `images.yourcompany.com/namespace/image:tag`. +
+ **Example:** ```yaml @@ -117,16 +122,11 @@ To rewrite image names and inject the KOTS image pull secret: # Define the conditional statement in the when field - when: 'repl{{ HasLocalRegistry }}' values: - api: + postgres: image: - registry: '{{repl LocalRegistryHost }}' - repository: '{{repl LocalRegistryNamespace }}/cloudnative-pg/cloudnative-pg' - ``` -
- What is the registry namespace? - - The registry namespace is the path between the registry and the image name. For example, `images.yourcompany.com/namespace/image:tag`. -
+ registry: '{{repl LocalRegistryHost }}' + repository: '{{repl LocalRegistryNamespace }}/cloudnative-pg/cloudnative-pg + ``` 1. Under the `optionalValues` key, use the same template functions as above to conditionally rewrite the image for the Replicated SDK: From 98e051651d682417c6ab6269319a242251abfb8d Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Thu, 24 Apr 2025 11:06:11 -0600 Subject: [PATCH 11/14] splitting up workflow topic --- docs/vendor/helm-native-about.mdx | 52 ++++++++- docs/vendor/helm-native-v2-using.md | 153 +++++-------------------- docs/vendor/helmchart-v2-snapshots.mdx | 48 ++++++++ docs/vendor/private-images-about.md | 4 +- docs/vendor/private-images-kots.mdx | 106 ++++++++++++++--- 5 files changed, 217 insertions(+), 146 deletions(-) create mode 100644 docs/vendor/helmchart-v2-snapshots.mdx diff --git a/docs/vendor/helm-native-about.mdx b/docs/vendor/helm-native-about.mdx index 8a5502663d..171bf60dbb 100644 --- a/docs/vendor/helm-native-about.mdx +++ b/docs/vendor/helm-native-about.mdx @@ -109,7 +109,51 @@ When installing an application that includes one or more Helm charts, KOTS alway For information about how to set the deployment order for Helm charts with KOTS, see [Orchestrate Resource Deployment](/vendor/orchestrating-resource-deployment). -## Deprecated HelmChart kots.io/v1beta1 Installation Methods +## Comparison to HelmChart v1 + +### HelmChart v1 and v2 Differences + +To support the use of local registries with version `kots.io/v1beta2` of the HelmChart custom resource, provide the necessary values in the builder field to render the Helm chart with all of the necessary images so that KOTS knows where to pull the images from to push them into the local registry. + +For more information about how to configure the `builder` key, see [Packaging Air Gap Bundles for Helm Charts](/vendor/helm-packaging-airgap-bundles) and [`builder`](/reference/custom-resource-helmchart-v2#builder) in _HelmChart v2_. + +The `kots.io/v1beta2` HelmChart custom resource has the following differences from `kots.io/v1beta1`: + + + + + + + + + + + + + + + + + + + + + + + + + + + +
HelmChart v1beta2HelmChart v1beta1Description
apiVersion: kots.io/v1beta2apiVersion: kots.io/v1beta1apiVersion is updated to kots.io/v1beta2
releaseNamechart.releaseNamereleaseName is a top level field under spec
N/AhelmVersionhelmVersion field is removed
N/AuseHelmInstalluseHelmInstall field is removed
+ +### About Migrating Existing KOTS Installations to HelmChart v2 + +Existing KOTS installations can be migrated to use the KOTS HelmChart v2 method, without having to reinstall the application. + +There are different steps for migrating to HelmChart v2 depending on the application deployment method used previously. For more information, see [Migrating Existing Installations to HelmChart v2](helm-v2-migrate). + +### Additional Information About HelmChart v1 This section describes the deprecated Helm chart installation methods that use the HelmChart custom resource `apiVersion: kots.io/v1beta1`. @@ -117,7 +161,7 @@ This section describes the deprecated Helm chart installation methods that use t ::: -### useHelmInstall: true {#v1beta1} +#### useHelmInstall: true {#v1beta1} :::note This method was previously referred to as _Native Helm_. @@ -208,7 +252,7 @@ To deploy Helm charts with version `kots.io/v1beta1` of the HelmChart custom res Finally, KOTS runs `helm upgrade -i --timeout 3600s -n `. The Helm binary processes hooks and weights, applies manifests to the Kubernetes cluster, and saves a release secret similar to `sh.helm.release.v1.chart-name.v1`. Helm uses this secret to track upgrades and rollbacks of applications. -### useHelmInstall: false {#v1beta1-false} +#### useHelmInstall: false {#v1beta1-false} :::note This method was previously referred to as _Replicated Helm_. @@ -218,7 +262,7 @@ When you use version `kots.io/v1beta1` of HelmChart custom resource with `useHel The resulting deployment is comprised of standard Kubernetes manifests. Therefore, cluster operators can view the exact differences between what is currently deployed and what an update will deploy. -### Limitations {#replicated-helm-limitations} +### HelmChart v1 Limitations {#replicated-helm-limitations} This section lists the limitations for version `kots.io/v1beta1` of the HelmChart custom resource. #### kots.io/v1beta1 (useHelmInstall: true) Limitations diff --git a/docs/vendor/helm-native-v2-using.md b/docs/vendor/helm-native-v2-using.md index 4352dddd5b..7b19cb5f43 100644 --- a/docs/vendor/helm-native-v2-using.md +++ b/docs/vendor/helm-native-v2-using.md @@ -1,20 +1,20 @@ import KotsHelmCrDescription from "../partials/helm/_kots-helm-cr-description.mdx" -# Configure the HelmChart v2 Custom Resource +# Rewrite Images to Local Registries with HelmChart v2 -This topic describes how to configure the Replicated KOTS HelmChart v2 custom resource. The information in this topic applies to Replicated KOTS installations in existing clusters, Replicated Embedded Cluster installations, and Replicated kURL installations for applications packaged with Helm. +This topic describes how to configure the Replicated KOTS HelmChart v2 custom resource to allow users to configure and push images to a local image registry. The main use case for local image registries is air gap installations with Replicated KOTS in existing clusters. -For more information about how KOTS uses the HelmChart custom resource to install Helm charts, see [About Distributing Helm Charts with KOTS](/vendor/helm-native-about). + -## Overview + -The tasks in this topic involve editing the HelmChart `values` and `optionalValues` keys in order to set Helm values during deployment. For more information about working with these fields, see [`values`](/reference/custom-resource-helmchart-v2#values) and [`optionalValues`](/reference/custom-resource-helmchart-v2#optionalvalues) in _HelmChart v2_. + -### Task 1: Rewrite Image Names and Inject the KOTS Image Pull Secret {#rewrite-image-names} + -1. In your Helm chart `values.yaml` file, set the value or values for any private images to the URL where the image can be access through the Replicated proxy service. + - + + +## Rewrite Application Images 1. In the HelmChart `optionalValues` key, use the KOTS [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry), [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost), and [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace) template functions so that any private or public images are conditionally rewritten to the location of the image in the user's local image registry, only when a local registry is configured. @@ -126,9 +130,17 @@ To rewrite image names and inject the KOTS image pull secret: image: registry: '{{repl LocalRegistryHost }}' repository: '{{repl LocalRegistryNamespace }}/cloudnative-pg/cloudnative-pg - ``` + ``` + +## Rewrite the Replicated SDK Image + +This section describes how to rewrite the image for the Replicated SDK for KOTS HelmChart v2 installations. + +To rewrite the image for the Replicated SDK: -1. Under the `optionalValues` key, use the same template functions as above to conditionally rewrite the image for the Replicated SDK: +1. In your Helm chart `values.yaml` file, + +1. In the KOTS HelmChart custom resource, under the `optionalValues` key, rewrite the image for the Replicated SDK so that it can be accessed from the user's local registry, if a local registry was configured: ```yaml # KOTS HelmChart custom resource @@ -139,12 +151,6 @@ To rewrite image names and inject the KOTS image pull secret: name: samplechart spec: optionalValues: - - when: 'repl{{ HasLocalRegistry }}' - values: - api: - image: - registry: '{{repl LocalRegistryHost }}' - repository: '{{repl LocalRegistryNamespace }}/cloudnative-pg/cloudnative-pg' # Rewrite Replicated SDK image to local registry - when: 'repl{{ HasLocalRegistry }}' values: @@ -152,9 +158,9 @@ To rewrite image names and inject the KOTS image pull secret: image: registry: '{{repl LocalRegistryHost }}' repository: '{{repl LocalRegistryNamespace }}/replicated-sdk' - ``` + ``` -### Task 2: Add Pull Secret for Rate-Limited Docker Hub Images {#docker-secret} +## Add a Pull Secret for Rate-Limited Docker Hub Images {#docker-secret} Docker Hub enforces rate limits for Anonymous and Free users. For more information about Docker Hub rate limiting, see [Understanding Docker Hub rate limiting](https://www.docker.com/increase-rate-limits) on the Docker website. @@ -179,103 +185,4 @@ spec: # Add the dockerhub secret pullSecrets: - name: gitea-kotsadm-dockerhub -``` - -### Task 3: Support the Use of Local Image Registries {#local-registries} - -Local image registries are required for KOTS installations in air-gapped environments with no outbound internet connection. Also, users in online environments can optionally use a local registry. - -To support the use of local registries, configure the `builder` key in the HelmChart custom resource. For information about how to configure the `builder` key, see [`builder`](/reference/custom-resource-helmchart-v2#builder) in _HelmChart v2_. - -For more information about how users can configure and push images to a local registry with KOTS, see [Configuring Local Image Registries](/enterprise/image-registry-settings). - -### Task 4: (KOTS Existing Cluster and kURL Only) Add Backup Labels for Snapshots {#add-backup-labels-for-snapshots} - -:::note -The Replicated [snapshots](snapshots-overview) feature for backup and restore is supported only for KOTS existing cluster and kURL installations. Snapshots are not support for installations with Embedded Cluster. For more information about disaster recovery for installations with Embedded Cluster, see [Disaster Recovery for Embedded Cluster](/vendor/embedded-disaster-recovery.mdx). -::: - -The snapshots feature requires the following labels on all resources in your Helm chart that you want to be included in the backup: -* `kots.io/backup: velero` -* `kots.io/app-slug: APP_SLUG`, where `APP_SLUG` is the slug of your Replicated application. - -For more information about snapshots, see [Understanding Backup and Restore](snapshots-overview). - -To support backup and restore with snapshots, edit the the HelmChart custom resource `optionalValues` key to add `kots.io/backup: velero` and `kots.io/app-slug: APP_SLUG` labels to the resources you want backed up. Add a `when` statement that evaluates to true only when the customer license has the `isSnapshotSupported` entitlement. - -#### Example - -The following example shows how to add backup labels for snapshots in the `optionalValues` key of the HelmChart custom resource: - -```yaml -# kots.io/v1beta2 HelmChart custom resource - -apiVersion: kots.io/v1beta2 -kind: HelmChart -metadata: - name: samplechart -spec: - ... - optionalValues: - # add backup labels only if the license supports snapshots - - when: "repl{{ LicenseFieldValue `isSnapshotSupported` }}" - recursiveMerge: true - values: - mariadb: - commonLabels: - kots.io/backup: velero - kots.io/app-slug: repl{{ LicenseFieldValue "appSlug" }} - podLabels: - kots.io/backup: velero - kots.io/app-slug: repl{{ LicenseFieldValue "appSlug" }} -``` - -## Additional Information - -### About the HelmChart Custom Resource - - - -For more information about the HelmChart custom resource, including the unique requirements and limitations for the keys described in this topic, see [HelmChart v2](/reference/custom-resource-helmchart-v2). - -### HelmChart v1 and v2 Differences - -To support the use of local registries with version `kots.io/v1beta2` of the HelmChart custom resource, provide the necessary values in the builder field to render the Helm chart with all of the necessary images so that KOTS knows where to pull the images from to push them into the local registry. - -For more information about how to configure the `builder` key, see [Packaging Air Gap Bundles for Helm Charts](/vendor/helm-packaging-airgap-bundles) and [`builder`](/reference/custom-resource-helmchart-v2#builder) in _HelmChart v2_. - -The `kots.io/v1beta2` HelmChart custom resource has the following differences from `kots.io/v1beta1`: - - - - - - - - - - - - - - - - - - - - - - - - - - - -
HelmChart v1beta2HelmChart v1beta1Description
apiVersion: kots.io/v1beta2apiVersion: kots.io/v1beta1apiVersion is updated to kots.io/v1beta2
releaseNamechart.releaseNamereleaseName is a top level field under spec
N/AhelmVersionhelmVersion field is removed
N/AuseHelmInstalluseHelmInstall field is removed
- -### Migrate Existing KOTS Installations to HelmChart v2 - -Existing KOTS installations can be migrated to use the KOTS HelmChart v2 method, without having to reinstall the application. - -There are different steps for migrating to HelmChart v2 depending on the application deployment method used previously. For more information, see [Migrating Existing Installations to HelmChart v2](helm-v2-migrate). +``` \ No newline at end of file diff --git a/docs/vendor/helmchart-v2-snapshots.mdx b/docs/vendor/helmchart-v2-snapshots.mdx new file mode 100644 index 0000000000..0d44fd7707 --- /dev/null +++ b/docs/vendor/helmchart-v2-snapshots.mdx @@ -0,0 +1,48 @@ +# Add Backup Labels for Snapshots with HelmChart v2 + +This topic describes how to configure the Replicated KOTS HelmChart v2 custom resource to add labels to resources in your Helm chart that you want to be included in backups taken with the Replicated snapshots feature. The information in this topic applies to Replicated KOTS installations in existing clusters and Replicated kURL installations. + +:::note +The Replicated snapshots feature for backup and restore is supported only for KOTS existing cluster and kURL installations. Snapshots are not supported for installations with Replicated Embedded Cluster. For more information about disaster recovery for installations with Embedded Cluster, see [Disaster Recovery for Embedded Cluster](/vendor/embedded-disaster-recovery.mdx). +::: + +## Overview + +The snapshots feature requires the following labels on all resources in your Helm chart that you want to be included in the backup: +* `kots.io/backup: velero` +* `kots.io/app-slug: APP_SLUG`, where `APP_SLUG` is the slug of your Replicated application. + +For more information about snapshots, see [Understanding Backup and Restore](snapshots-overview). + +## Add Backup Labels for Snapshots + +To support backup and restore with snapshots: + +1. In the HelmChart v2 custom resource for your Helm chart, under the `optionalValues` key, add a `when` statement that evaluates to true only when the customer license has the `isSnapshotSupported` entitlement. This ensures that the labels are only added to resources when the customer license supports snapshots. Then, add `values` that assign the following labels to the resources you want backed up: + * `kots.io/backup: velero` + * `kots.io/app-slug: APP_SLUG`, where `APP_SLUG` is the unique slug of your application. You can use the KOTS [LicenseFieldValue](/reference/template-functions-license-context#licensefieldvalue) function to get the application slug from the license. + + ```yaml + # kots.io/v1beta2 HelmChart custom resource + + apiVersion: kots.io/v1beta2 + kind: HelmChart + metadata: + name: samplechart + spec: + optionalValues: + # add backup labels only if the license supports snapshots + - when: "repl{{ LicenseFieldValue `isSnapshotSupported` }}" + recursiveMerge: true + values: + mariadb: + commonLabels: + kots.io/backup: velero + # use the LicenseFieldValue function to get the app slug from the license + kots.io/app-slug: repl{{ LicenseFieldValue "appSlug" }} + podLabels: + kots.io/backup: velero + kots.io/app-slug: repl{{ LicenseFieldValue "appSlug" }} + ``` + +1. Save and promote the release to the channel that you use for testing. Install in a development environment using KOTS or kURL to test your changes. \ No newline at end of file diff --git a/docs/vendor/private-images-about.md b/docs/vendor/private-images-about.md index 8d0e2dec83..e72286d7d4 100644 --- a/docs/vendor/private-images-about.md +++ b/docs/vendor/private-images-about.md @@ -14,12 +14,12 @@ The following diagram demonstrates how the proxy registry pulls images from your [View a larger version of this image](/images/private-registry-diagram-large.png) -## About Enabling the Proxy Registry +## About Using the Proxy Registry The proxy registry requires read-only credentials to your private registry to access your application images. See [Connect to an External Registry](/vendor/packaging-private-images). After connecting your registry, the steps the enable the proxy registry vary depending on your application deployment method. For more information, see: -* [Using the Proxy Registry with KOTS Installations](/vendor/private-images-kots) +* [Using the Proxy Registry with Replicated Installers](/vendor/private-images-kots) * [Using the Proxy Registry with Helm Installations](/vendor/helm-image-registry) ## About Allowing Pull-Through Access of Public Images diff --git a/docs/vendor/private-images-kots.mdx b/docs/vendor/private-images-kots.mdx index 9527486115..8ec3a63a75 100644 --- a/docs/vendor/private-images-kots.mdx +++ b/docs/vendor/private-images-kots.mdx @@ -2,23 +2,23 @@ import Deprecated from "../partials/helm/_replicated-deprecated.mdx" import StepCreds from "../partials/proxy-service/_step-creds.mdx" import StepCustomDomain from "../partials/proxy-service/_step-custom-domain.mdx" -# Use the Proxy Registry with KOTS Installations +# Use the Proxy Registry with Replicated Installers -This topic describes how to use the Replicated proxy registry with applications deployed with Replicated KOTS. +This topic describes how to use the Replicated proxy registry with applications deployed with Replicated installers (KOTS, kURL, and Embedded Cluster). ## Overview -Replicated KOTS automatically creates the required image pull secret for accessing the Replicated proxy registry during application deployment. When possible, KOTS also automatically rewrites image names in the application manifests to the location of the image at `proxy.replicated.com` or your custom domain. +For applications installed with a Replicated installer, Replicated KOTS automatically creates the required image pull secret for accessing the Replicated proxy registry during application deployment. When possible, KOTS also automatically rewrites image names in the application manifests to the location of the image at `proxy.replicated.com` or your custom domain. -### Image Pull Secret +### About the Image Pull Secret During application deployment, KOTS automatically creates an `imagePullSecret` with `type: kubernetes.io/dockerconfigjson` that is based on the customer license. This secret is used to authenticate with the proxy registry and grant proxy access to private images. For information about how Kubernetes uses the `kubernetes.io/dockerconfigjson` Secret type to authenticate to a private image registry, see [Pull an Image from a Private Registry](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/) in the Kubernetes documentation. -### Image Location Patching (Standard Manifests and HelmChart v1) +### About Image Location Patching (HelmChart v1 and Standard Manifests) -For applications packaged with standard Kubernetes manifests (or Helm charts deployed with the [HelmChart v1](/reference/custom-resource-helmchart) custom resource), KOTS automatically patches image names to the location of the image at at `proxy.replicated.com` or your custom domain during deployment. If KOTS receives a 401 response when attempting to load image manifests using the image reference from the PodSpec, it assumes that this is a private image that must be proxied through the proxy registry. +For applications packaged with the [HelmChart v1](/reference/custom-resource-helmchart) custom resource or with standard Kubernetes manifests, KOTS automatically patches image names to the location of the image at `proxy.replicated.com` or your custom domain during deployment. If KOTS receives a 401 response when attempting to load image manifests using the image reference from the PodSpec, it assumes that this is a private image that must be proxied through the proxy registry. KOTS uses Kustomize to patch the `midstream/kustomization.yaml` file to change the image name during deployment to reference the proxy registry. For example, a PodSpec for a Deployment references a private image hosted at `quay.io/my-org/api:v1.0.1`: @@ -48,28 +48,100 @@ images: newName: proxy.replicated.com/proxy/my-kots-app/quay.io/my-org/api ``` -## Enable the Proxy Registry +## Use the Proxy Registry -This section describes how to enable the proxy registry for applications deployed with KOTS, including how to ensure that image names are rewritten and that the required image pull secret is provided. +This section describes how to configure your application to use the proxy registry. -To enable the proxy registry: +### HelmChart v2 + +To enable the proxy registry with applications deployed with HelmChart v2: 1. 1. -1. Rewrite images names to the location of the image at `proxy.replicated.com` or your custom domain. Also, ensure that the correct image pull secret is provided for all private images. The steps required to configure image names and add the image pull secret vary depending on your application type: +1. In your Helm chart values file, set your image repository URL to the location of the image on the proxy registry. If you added a custom domain, use your custom domain. Otherwise, use `proxy.replicated.com`. + + 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. + + **Example:** + + ```yaml + # values.yaml + api: + image: + # proxy.registry.com or your custom domain + registry: ghcr.io + repository: proxy/app/ghcr.io/cloudnative-pg/cloudnative-pg + tag: catalog-1.24.0 + ``` + +1. Ensure that any references to the image in your Helm chart access the field from your values file. + + **Example**: + + ```yaml + apiVersion: v1 + kind: Pod + spec: + containers: + - name: api + # Access the registry, repository, and tag fields from the values file + image: {{ .Values.images.api.registry }}/{{ .Values.images.api.repository }}:{{ .Values.images.api.tag }} + ``` + +1. In the KOTS HelmChart custom resource, under the `values` key, use the KOTS [ImagePullSecretName](/reference/template-functions-config-context#imagepullsecretname) template function to set the image pull secret for any private images to the KOTS-generated image pull secret. + + **Example:** + + ```yaml + # KOTS HelmChart custom resource - * **HelmChart v2**: For Helm charts deployed with the[ HelmChart v2](/reference/custom-resource-helmchart-v2) custom resource, configure the HelmChart v2 custom resource to dynamically update image names in your Helm chart and to inject the image pull secret that is automatically created by KOTS. For instructions, see [Configure the HelmChart Custom Resource v2](/vendor/helm-native-v2-using). + apiVersion: kots.io/v1beta2 + kind: HelmChart + metadata: + name: samplechart + spec: + values: + postgres: + image: + # Inject the pull secret with ImagePullSecretName + imagePullSecrets: + - name: '{{repl ImagePullSecretName }}' + ``` + +1. If you are deploying Pods to namespaces other than the application namespace, add the namespace to the `additionalNamespaces` attribute of the KOTS Application custom resource. This ensures that KOTS can provision the `imagePullSecret` in the namespace to allow the Pod to pull the image. For instructions, see [Define Additional Namespaces](operator-defining-additional-namespaces). - * **Standard Manifests or HelmChart v1**: For standard manifest-based applications or Helm charts deployed with the [HelmChart v1](/reference/custom-resource-helmchart) custom resource, no additional configuration is required. KOTS automatically rewrites image names and injects image pull secrets during deployment for these application types. - :::note - - ::: +### HelmChart v1 or Standard Manifests - * **Kubernetes Operators**: For applications packaged with Kubernetes Operators, KOTS cannot modify pods that are created at runtime by the Operator. To support the use of private images in all environments, the Operator code should use KOTS functionality to determine the image name and image pull secrets for all pods when they are created. For instructions, see [Reference Images](/vendor/operator-referencing-images) in the _Packaging Kubernetes Operators_ section. +:::note + +::: + +To use the proxy registry with applications deployed with HelmChart v1 or packed with standard manifests: + +1. + +1. + +1. If you are deploying Pods to namespaces other than the application namespace, add the namespace to the `additionalNamespaces` attribute of the KOTS Application custom resource. This ensures that KOTS can provision the `imagePullSecret` in the namespace to allow the Pod to pull the image. For instructions, see [Define Additional Namespaces](operator-defining-additional-namespaces). + +For standard manifest-based applications or Helm charts deployed with the [HelmChart v1](/reference/custom-resource-helmchart), KOTS automatically rewrites image names and injects image pull secrets during deployment for these application types. No additional configuration is required. + +### Kubernetes Operators + +To use the proxy registry with applications packaged with Kubernetes Operators: + +1. + +1. 1. If you are deploying Pods to namespaces other than the application namespace, add the namespace to the `additionalNamespaces` attribute of the KOTS Application custom resource. This ensures that KOTS can provision the `imagePullSecret` in the namespace to allow the Pod to pull the image. For instructions, see [Define Additional Namespaces](operator-defining-additional-namespaces). -1. (Optional) Add a custom domain for the proxy registry instead of `proxy.replicated.com`. See [Use Custom Domains](custom-domains-using). \ No newline at end of file +1. For applications packaged with Kubernetes Operators, KOTS cannot modify pods that are created at runtime by the Operator. To support the use of private images in all environments, the Operator code should use KOTS functionality to determine the image name and image pull secrets for all pods when they are created. For instructions, see [Reference Images](/vendor/operator-referencing-images) in the _Packaging Kubernetes Operators_ section. \ No newline at end of file From cb2bbe28e861608ac64fd2e6b05773cf76a4e78f Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Thu, 24 Apr 2025 17:11:55 -0600 Subject: [PATCH 12/14] wip --- docs/vendor/helm-native-v2-using.md | 188 ------------------ docs/vendor/helm-packaging-airgap-bundles.mdx | 2 +- 2 files changed, 1 insertion(+), 189 deletions(-) delete mode 100644 docs/vendor/helm-native-v2-using.md diff --git a/docs/vendor/helm-native-v2-using.md b/docs/vendor/helm-native-v2-using.md deleted file mode 100644 index 7b19cb5f43..0000000000 --- a/docs/vendor/helm-native-v2-using.md +++ /dev/null @@ -1,188 +0,0 @@ -import KotsHelmCrDescription from "../partials/helm/_kots-helm-cr-description.mdx" - -# Rewrite Images to Local Registries with HelmChart v2 - -This topic describes how to configure the Replicated KOTS HelmChart v2 custom resource to allow users to configure and push images to a local image registry. The main use case for local image registries is air gap installations with Replicated KOTS in existing clusters. - - - - - - - - - - - - - - -## Rewrite Application Images - -1. In the HelmChart `optionalValues` key, use the KOTS [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry), [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost), and [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace) template functions so that any private or public images are conditionally rewritten to the location of the image in the user's local image registry, only when a local registry is configured. - -
- What is the registry namespace? - - The registry namespace is the path between the registry and the image name. For example, `images.yourcompany.com/namespace/image:tag`. -
- - **Example:** - - ```yaml - # KOTS HelmChart custom resource - - apiVersion: kots.io/v1beta2 - kind: HelmChart - metadata: - name: samplechart - spec: - optionalValues: - # Define the conditional statement in the when field - - when: 'repl{{ HasLocalRegistry }}' - values: - postgres: - image: - registry: '{{repl LocalRegistryHost }}' - repository: '{{repl LocalRegistryNamespace }}/cloudnative-pg/cloudnative-pg - ``` - -## Rewrite the Replicated SDK Image - -This section describes how to rewrite the image for the Replicated SDK for KOTS HelmChart v2 installations. - -To rewrite the image for the Replicated SDK: - -1. In your Helm chart `values.yaml` file, - -1. In the KOTS HelmChart custom resource, under the `optionalValues` key, rewrite the image for the Replicated SDK so that it can be accessed from the user's local registry, if a local registry was configured: - - ```yaml - # KOTS HelmChart custom resource - - apiVersion: kots.io/v1beta2 - kind: HelmChart - metadata: - name: samplechart - spec: - optionalValues: - # Rewrite Replicated SDK image to local registry - - when: 'repl{{ HasLocalRegistry }}' - values: - replicated: - image: - registry: '{{repl LocalRegistryHost }}' - repository: '{{repl LocalRegistryNamespace }}/replicated-sdk' - ``` - -## Add a Pull Secret for Rate-Limited Docker Hub Images {#docker-secret} - -Docker Hub enforces rate limits for Anonymous and Free users. For more information about Docker Hub rate limiting, see [Understanding Docker Hub rate limiting](https://www.docker.com/increase-rate-limits) on the Docker website. - -To avoid errors caused by reaching the rate limit, your users can run the `kots docker ensure-secret` command, which creates an `APP_SLUG-kotsadm-dockerhub` secret for pulling Docker Hub images and applies the secret to Kubernetes manifests that have images. For more information, see [Avoiding Docker Hub Rate Limits](/enterprise/image-registry-rate-limits). - -To support the use of the `kots docker ensure-secret` command, add the `APP_SLUG-kotsadm-dockerhub` pull secret (where `APP_SLUG` is your application slug) to any Docker images that could be rate-limited. - -**Example:** - -```yaml -# kots.io/v1beta2 HelmChart custom resource - -apiVersion: kots.io/v1beta2 -kind: HelmChart -metadata: - name: samplechart -spec: - values: - image: - registry: docker.io - repository: org-name/example-docker-hub-image - # Add the dockerhub secret - pullSecrets: - - name: gitea-kotsadm-dockerhub -``` \ No newline at end of file diff --git a/docs/vendor/helm-packaging-airgap-bundles.mdx b/docs/vendor/helm-packaging-airgap-bundles.mdx index 9a0b57cfd7..8d20e26af2 100644 --- a/docs/vendor/helm-packaging-airgap-bundles.mdx +++ b/docs/vendor/helm-packaging-airgap-bundles.mdx @@ -5,7 +5,7 @@ import AirGapBundle from "../partials/airgap/_airgap-bundle.mdx" # Package Air Gap Bundles for Helm Charts -This topic describes how to package and build air gap bundles for releases that contain one or more Helm charts. This topic applies to applications deployed with Replicated KOTS. +This topic describes how to package and build air gap bundles for releases that contain one or more Helm charts. This topic applies to applications deployed with a Replicated installer (Embedded Cluster, KOTS, or kURL). ## Overview From d3ecfb86b5e6891342b6e0c2505b67450e652a78 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Thu, 24 Apr 2025 17:23:32 -0600 Subject: [PATCH 13/14] wip --- docs/vendor/helm-native-v2-using.mdx | 100 +++++++++++++++++++++++++++ docs/vendor/private-images-kots.mdx | 84 +++++++++++----------- 2 files changed, 143 insertions(+), 41 deletions(-) create mode 100644 docs/vendor/helm-native-v2-using.mdx diff --git a/docs/vendor/helm-native-v2-using.mdx b/docs/vendor/helm-native-v2-using.mdx new file mode 100644 index 0000000000..608f0f6dd4 --- /dev/null +++ b/docs/vendor/helm-native-v2-using.mdx @@ -0,0 +1,100 @@ +import KotsHelmCrDescription from "../partials/helm/_kots-helm-cr-description.mdx" + +# Rewrite Images to Local Registries with HelmChart + +This topic describes how to configure the Replicated KOTS HelmChart custom resource so that KOTS rewrites the images used by your application to the location of the image in the user's local image registry. The main use case for local image registries is air gap installations with Replicated KOTS in existing clusters. + +## Overview + +The HelmChart custom resource `optionalValues` key can be used to set values in the Helm chart `values.yaml` file when a given conditional statement evaluates to true. For more information, see [optionalValues](/reference/custom-resource-helmchart-v2#optionalvalues) in _HelmChart v2_. + +If you have customers that will push images to their own local image registry (such as customers performing air gap installations with KOTS in existing clusters), you can configure the HelmChart `optionalValues` key so that KOTS rewrites the images for your application to the location of the image in user's local image registry during deployment. + +## Prerequisite + +Before configuring the HelmChart custom resource to conditionally rewrite images to the user's local registry, you first need to configure the HelmChart `builder` key to support the use of local registries. For more information, see [Package Air Gap Bundles for Helm Charts](/vendor/helm-packaging-airgap-bundles). + +## Rewrite Application Images + +To configure the HelmChart `optionalValues` key so that KOTS conditionally rewrites images to the user's local registry: + +1. In the HelmChart custom resource `optionalValues` key, use the following KOTS template functions: + * [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry) + * [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost) + * [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace) +
+ What is the registry namespace? +

The registry namespace is the path between the registry and the image name. For example, `images.yourcompany.com/namespace/image:tag`.

+
+ + **Example:** + + ```yaml + # KOTS HelmChart custom resource + + apiVersion: kots.io/v1beta2 + kind: HelmChart + metadata: + name: samplechart + spec: + optionalValues: + # Define the conditional statement in the when field + - when: 'repl{{ HasLocalRegistry }}' + values: + postgres: + image: + registry: '{{repl LocalRegistryHost }}' + repository: '{{repl LocalRegistryNamespace }}'/cloudnative-pg/cloudnative-pg + ``` +1. + +## Rewrite the Replicated SDK Image + +To configure the HelmChart `optionalValues` key so that KOTS conditionally rewrites the SDK image to the user's local registry: + +1. In the KOTS HelmChart custom resource, under the `optionalValues` key, rewrite the image for the Replicated SDK so that it can be accessed from the user's local registry, if a local registry was configured: + + ```yaml + # KOTS HelmChart custom resource + + apiVersion: kots.io/v1beta2 + kind: HelmChart + metadata: + name: samplechart + spec: + optionalValues: + # Rewrite Replicated SDK image to local registry + - when: 'repl{{ HasLocalRegistry }}' + values: + replicated: + image: + registry: '{{repl LocalRegistryHost }}' + repository: '{{repl LocalRegistryNamespace }}/replicated-sdk' + ``` + +## Add a Pull Secret for Rate-Limited Docker Hub Images {#docker-secret} + +Docker Hub enforces rate limits for Anonymous and Free users. For more information about Docker Hub rate limiting, see [Understanding Docker Hub rate limiting](https://www.docker.com/increase-rate-limits) on the Docker website. + +To avoid errors caused by reaching the rate limit, your users can run the `kots docker ensure-secret` command, which creates an `APP_SLUG-kotsadm-dockerhub` secret for pulling Docker Hub images and applies the secret to Kubernetes manifests that have images. For more information, see [Avoiding Docker Hub Rate Limits](/enterprise/image-registry-rate-limits). + +To support the use of the `kots docker ensure-secret` command, add the `APP_SLUG-kotsadm-dockerhub` pull secret (where `APP_SLUG` is your application slug) to any Docker images that could be rate-limited. + +**Example:** + +```yaml +# kots.io/v1beta2 HelmChart custom resource + +apiVersion: kots.io/v1beta2 +kind: HelmChart +metadata: + name: samplechart +spec: + values: + image: + registry: docker.io + repository: org-name/example-docker-hub-image + # Add the dockerhub secret + pullSecrets: + - name: gitea-kotsadm-dockerhub +``` \ No newline at end of file diff --git a/docs/vendor/private-images-kots.mdx b/docs/vendor/private-images-kots.mdx index 8ec3a63a75..727dba05be 100644 --- a/docs/vendor/private-images-kots.mdx +++ b/docs/vendor/private-images-kots.mdx @@ -8,53 +8,17 @@ This topic describes how to use the Replicated proxy registry with applications ## Overview -For applications installed with a Replicated installer, Replicated KOTS automatically creates the required image pull secret for accessing the Replicated proxy registry during application deployment. When possible, KOTS also automatically rewrites image names in the application manifests to the location of the image at `proxy.replicated.com` or your custom domain. +For applications installed with a Replicated installer, Replicated KOTS automatically creates the required image pull secret for accessing the Replicated proxy registry during application deployment. When possible, KOTS also automatically rewrites image names in the application manifests to the location of the image at `proxy.replicated.com` or your custom domain. -### About the Image Pull Secret - -During application deployment, KOTS automatically creates an `imagePullSecret` with `type: kubernetes.io/dockerconfigjson` that is based on the customer license. This secret is used to authenticate with the proxy registry and grant proxy access to private images. - -For information about how Kubernetes uses the `kubernetes.io/dockerconfigjson` Secret type to authenticate to a private image registry, see [Pull an Image from a Private Registry](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/) in the Kubernetes documentation. - -### About Image Location Patching (HelmChart v1 and Standard Manifests) - -For applications packaged with the [HelmChart v1](/reference/custom-resource-helmchart) custom resource or with standard Kubernetes manifests, KOTS automatically patches image names to the location of the image at `proxy.replicated.com` or your custom domain during deployment. If KOTS receives a 401 response when attempting to load image manifests using the image reference from the PodSpec, it assumes that this is a private image that must be proxied through the proxy registry. - -KOTS uses Kustomize to patch the `midstream/kustomization.yaml` file to change the image name during deployment to reference the proxy registry. For example, a PodSpec for a Deployment references a private image hosted at `quay.io/my-org/api:v1.0.1`: - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: example -spec: - template: - spec: - containers: - - name: api - image: quay.io/my-org/api:v1.0.1 -``` - -When this application is deployed, KOTS detects that it cannot access -the image at quay.io. So, it creates a patch in the `midstream/kustomization.yaml` -file that changes the image name in all manifest files for the application. This causes the container runtime in the cluster to use the proxy registry to pull the images, using the license information provided to KOTS for authentication. - -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -bases: -- ../../base -images: -- name: quay.io/my-org/api:v1.0.1 - newName: proxy.replicated.com/proxy/my-kots-app/quay.io/my-org/api -``` +There are different steps to configure your application to use the proxy registry depending on the installation method and how your application is packaged. ## Use the Proxy Registry This section describes how to configure your application to use the proxy registry. -### HelmChart v2 +### Helm Charts Deployed with HelmChart v2 -To enable the proxy registry with applications deployed with HelmChart v2: +To use the proxy registry for Helm charts deployed with HelmChart v2: 1. @@ -96,6 +60,11 @@ To enable the proxy registry with applications deployed with HelmChart v2: ``` 1. In the KOTS HelmChart custom resource, under the `values` key, use the KOTS [ImagePullSecretName](/reference/template-functions-config-context#imagepullsecretname) template function to set the image pull secret for any private images to the KOTS-generated image pull secret. +
+ What is the image pull secret? +

During application deployment, KOTS automatically creates an `imagePullSecret` with `type: kubernetes.io/dockerconfigjson` that is based on the customer license. This secret is used to authenticate with the proxy registry and grant proxy access to private images.

+

For information about how Kubernetes uses the `kubernetes.io/dockerconfigjson` Secret type to authenticate to a private image registry, see [Pull an Image from a Private Registry](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/) in the Kubernetes documentation.

+
**Example:** @@ -118,7 +87,7 @@ To enable the proxy registry with applications deployed with HelmChart v2: 1. If you are deploying Pods to namespaces other than the application namespace, add the namespace to the `additionalNamespaces` attribute of the KOTS Application custom resource. This ensures that KOTS can provision the `imagePullSecret` in the namespace to allow the Pod to pull the image. For instructions, see [Define Additional Namespaces](operator-defining-additional-namespaces). -### HelmChart v1 or Standard Manifests +### Helm Charts Deployed with HelmChart v1 or Standard Manifests :::note @@ -134,6 +103,39 @@ To use the proxy registry with applications deployed with HelmChart v1 or packed For standard manifest-based applications or Helm charts deployed with the [HelmChart v1](/reference/custom-resource-helmchart), KOTS automatically rewrites image names and injects image pull secrets during deployment for these application types. No additional configuration is required. +
+How does KOTS rewrite image names and inject image pull secrets? + +

For applications packaged with the [HelmChart v1](/reference/custom-resource-helmchart) custom resource or with standard Kubernetes manifests, KOTS automatically patches image names to the location of the image at `proxy.replicated.com` or your custom domain during deployment. If KOTS receives a 401 response when attempting to load image manifests using the image reference from the PodSpec, it assumes that this is a private image that must be proxied through the proxy registry.

+

KOTS uses Kustomize to patch the `midstream/kustomization.yaml` file to change the image name during deployment to reference the proxy registry. For example, a PodSpec for a Deployment references a private image hosted at `quay.io/my-org/api:v1.0.1`:

+ +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: example +spec: + template: + spec: + containers: + - name: api + image: quay.io/my-org/api:v1.0.1 +``` + +

When this application is deployed, KOTS detects that it cannot access +the image at quay.io. So, it creates a patch in the `midstream/kustomization.yaml` +file that changes the image name in all manifest files for the application. This causes the container runtime in the cluster to use the proxy registry to pull the images, using the license information provided to KOTS for authentication.

+ +```yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +bases: +- ../../base +images: +- name: quay.io/my-org/api:v1.0.1 + newName: proxy.replicated.com/proxy/my-kots-app/quay.io/my-org/api +``` +
+ ### Kubernetes Operators To use the proxy registry with applications packaged with Kubernetes Operators: From 9bebf867ac2969a7f5e706d8239e13df4f50d000 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Fri, 25 Apr 2025 10:11:56 -0600 Subject: [PATCH 14/14] rename file --- .../vendor/{helm-v2-migrate.md => helm-v2-migrate.mdx} | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) rename docs/vendor/{helm-v2-migrate.md => helm-v2-migrate.mdx} (94%) diff --git a/docs/vendor/helm-v2-migrate.md b/docs/vendor/helm-v2-migrate.mdx similarity index 94% rename from docs/vendor/helm-v2-migrate.md rename to docs/vendor/helm-v2-migrate.mdx index a606be9f2e..b370f23d8a 100644 --- a/docs/vendor/helm-v2-migrate.md +++ b/docs/vendor/helm-v2-migrate.mdx @@ -18,11 +18,15 @@ To migrate existing installations from HelmChart v1 with `useHelmInstall: true` 1. In a development environment, install an application release using the KOTS HelmChart v1 with `useHelmInstall: true` method. You will use this installation to test the migration to HelmChart v2. -1. Create a new release containing your application files. +1. Update your Helm values file or files to rewrite image names to use the proxy registry. -1. For each Helm chart in the release, find the corresponding HelmChart custom resource and update `apiVersion` to `kots.io/v1beta2`. Then update it to rewrite images, inject image pull secrets, and add backup labels. See [Configure the HelmChart Custom Resource v2](helm-native-v2-using). +1. For each of your application's Helm charts, update the corresponding HelmChart custom resource: + 1. Update `apiVersion` to `kots.io/v1beta2` + 1. Update the `values` key to inject the KOTS image pull secret to provide authentication to the proxy registry + 1. Update the `optionalValues` key to rewrite images to support local registries + 1. Add backup labels to support the snapshots feature for KOTS existing cluster and kURL installations -1. Promote the release to an internal-only channel that your team uses for testing. +1. Create and promote a new release with your changes to an internal-only channel that your team uses for testing. 1. In your development environment, log in to the Admin Console and confirm that you can upgrade to the new HelmChart v2 release.