From 800290a949d51d3892270eb5eeabfa5a01fba0c7 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Wed, 16 Oct 2024 14:33:44 -0600 Subject: [PATCH 01/20] Clarify local registry template funtions for EC/kURL installs --- docs/vendor/helm-native-v2-using.md | 143 ++++++++++++++++------------ 1 file changed, 83 insertions(+), 60 deletions(-) diff --git a/docs/vendor/helm-native-v2-using.md b/docs/vendor/helm-native-v2-using.md index d9e7af0dcf..1bc5962dfa 100644 --- a/docs/vendor/helm-native-v2-using.md +++ b/docs/vendor/helm-native-v2-using.md @@ -12,61 +12,43 @@ For more information about the HelmChart custom resource, including the unique r After you complete the tasks in this topic to configure the `kots.io/v1beta2` HelmChart custom resource, you can migrate any existing installations that were deployed with `kots.io/v1beta1` with `useHelmInstall: true` to use `kots.io/v1beta2` instead. For more information, see [Migrating Existing Installations to HelmChart v2](helm-v2-migrate). -## HelmChart v1 and v2 Differences +## Workflow -The `kots.io/v1beta2` HelmChart custom resource has the following differences from `kots.io/v1beta1`: +To support installations with the `kots.io/v1beta2` HelmChart custom resource, do the following: +1. Rewrite image names so that images can be located in your private registry or in the user's local private registry. See [Rewrite Image Names](#rewrite-image-names). +1. Inject a KOTS-generated image pull secret that grants access to private images. 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. 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 backup and restore for Embedded Cluster, see [Disaster Recovery for Embedded Cluster](/vendor/embedded-disaster-recovery). + ::: +1. Configure the `builder` key to allow your users to push images to local private registries. The `builder` key is required to support air gap installations. See [Support Local Image Registries](#local-registries). - - - - - - - - - - - - - - - - - - - - - - - - - - -
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
+## Task 1: Rewrite Image Names -## Workflow +Configure the KOTS HelmChart custom resource `values` key so that application image names are rewritten in your Helm chart values during deployment. This allows the images to be accessed through the [Replicated proxy service](private-images-about) at `proxy.replicated.com`, your customer's registry, or the built-in registry used in Embedded Cluster or kURL installations. -To support installations with the `kots.io/v1beta2` HelmChart custom resource, do the following: -* Rewrite image names so that images can be located in your private registry or in the user's local private registry. See [Rewrite Image Names](#rewrite-image-names). -* Inject a KOTS-generated image pull secret that grants access to private images. See [Inject Image Pull Secrets](#inject-image-pull-secrets). -* 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). -* Add backup labels to your resources to support backup and restore with the snapshots feature. See [Add Backup Labels for Snapshots](#add-backup-labels-for-snapshots). -* Configure the `builder` key to allow your users to push images to local private registries. The `builder` key is required to support air gap installations. See [Support Local Image Registries](#local-registries). +During installation or upgrade with KOTS, application images are accessed from one of the following locations: +* The [Replicated proxy registry](private-images-about) at `proxy.replicated.com` +* The enterprise user's registry +* The built-in registry for Replicated Embedded Cluster or kURL installations + +You will use the following KOTS template functions in the HelmChart custom resource to rewrite image names: +* [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry): Returns true if the environment is configured to rewrite images to a local registry. HasLocalRegistry is always true for air gap installations and optionally true for online installations. You can use HasLocalRegistry to conditionally rewrite images depending on if your user configured a local registry or not. +* [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost): Returns the host of the local registry that the user configured. +* [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace): Returns the namespace of the local registry that the user configured. The registry namespace is the path between the registry and the image name. For example, `my.registry.com/namespace/image:tag`. -### Rewrite Image Names +### Rewrite Private Image Names {#local-proxy-example} -During installation or upgrade with KOTS, any application images in the software vendor's private registry are accessed through the [Replicated proxy registry](private-images-about) at `proxy.replicated.com`. Additionally, KOTS allows enterprise users to push images to their own registry. +For any private images, configure the HelmChart custom resource so that image names are rewritten to `proxy.replicated.com/proxy//`, where `` is the unique application slug in the Vendor Portal and `` is the path to the image in the registry. -To ensure that images are discovered in either your registry or in the enterprise user's local registry, you must configure the HelmChart custom resource so that image names are rewritten in your Helm chart during deployment. 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: -* **HasLocalRegistry**: Returns true if the environment is configured to rewrite images to a local registry. HasLocalRegistry is always true for air gapped installations and optionally true for online installations. -* **LocalRegistryHost**: Returns the host of the local registry that the user configured. -* **LocalRegistryNamespace**: Returns the namespace of the local registry that the user configured. +For example, if the private image is `quay.io/my-org/nginx:v1.0.1`, then the image name should be rewritten to `proxy.replicated.com/proxy/my-app-slug/quay.io/my-org/nginx:v1.0.1`. -These template functions can be used to conditionally rewrite images names so that KOTS uses the host and namespace of the enterprise user's local registry _only_ when a local registry is configured. For example, if the user configured a local registry and used the namespace `example-namespace`, then the template function `'{{repl HasLocalRegistry | ternary LocalRegistryNamespace "my-org" }}/mariadb'` evaluates to `example-namespace/mariadb`. If the user did _not_ configure a local registry, then the template function evaluates to `my-org/maridb`. For examples, see [Example: Rewrite private image names](#local-proxy-example) or [Example: Rewrite public images names](#local-public-example) below. +#### Example -#### Example: Rewrite private image names {#local-proxy-example} +The following example shows how to configure the KOTS HelmChart `values` key to rewrite the registry hostname and namespace for a private image. -The following example shows a field in the `values` key that rewrites the registry domain to `proxy.replicated.com` unless the user configured a local registry. Similarly, it shows a field that rewrites the image repository to the path of the image on `proxy.replicated.com` or in the user's local registry: +This example uses [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry) to conditionally update the registry hostname and namespace for the image depending on if the user configured a local registry. It also uses [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost) and [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace) to render the user-supplied hostname and namespace for the image on the local registry, if one was configured. ```yaml # kots.io/v1beta2 HelmChart custom resource @@ -79,12 +61,17 @@ spec: ... values: image: + # If the user configured a registry, use that registry's hostname + # Else, use proxy.replicated.com registry: '{{repl HasLocalRegistry | ternary LocalRegistryHost "proxy.replicated.com" }}' + # If the user configured a registry, use the registry namespace they provided + # Else if Embedded Cluster/kURL install, use the buit-in Embedded Cluster/kURL registry + # Else use the image's namespace at proxy.replicated.com repository: '{{repl HasLocalRegistry | ternary LocalRegistryNamespace "proxy/my-app/quay.io/my-org" }}/nginx' tag: v1.0.1 ``` -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: +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 @@ -95,7 +82,9 @@ image: tag: v1.0.1 ``` -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: +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 @@ -108,7 +97,7 @@ spec: image: {{ .Values.image.registry }}/{{ .Values.image.repository }}:{{ .Values.image.tag }} ``` -#### Example: Rewrite public image names {#local-public-example} +### Rewrite Public Image Names {#local-public-example} The following example shows a field in the `values` key that rewrites the registry domain to `docker.io` unless the user configured a local registry. Similarly, it shows a field that rewrites the image repository to the path of the public image on `docker.io` or in the user's local registry: @@ -152,7 +141,7 @@ spec: image: {{ .Values.image.registry }}/{{ .Values.image.repository }}:{{ .Values.image.tag }} ``` -### Inject Image Pull Secrets +## Task 2: Inject Image Pull Secrets 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. @@ -160,7 +149,7 @@ During installation, KOTS creates a `kubernetes.io/dockerconfigjson` type Secret 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** +#### 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: @@ -192,7 +181,9 @@ image: - 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: +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 @@ -209,7 +200,7 @@ spec: {{- end }} ``` -### Add Pull Secret for Rate-Limited Docker Hub Images {#docker-secret} +## Task 3: 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). @@ -219,7 +210,7 @@ You can do this by adding the `-kotsadm-dockerhub` pull secret to a fi 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** +#### Example The following Helm chart `values.yaml` file includes `image.registry`, `image.repository`, and `image.pullSecrets` for a rate-limited Docker Hub image: @@ -269,7 +260,11 @@ spec: {{- end }} ``` -### Add Backup Labels for Snapshots +## Task 4: Add Backup Labels for Snapshots (KOTS Existing Cluster Installations Only) + +:::note +Snapshots is not supported for installations with Replicated Embedded Cluster. For more information about configuring backup and restore for Embedded Cluster, see [Disaster Recovery for Embedded Cluster](/vendor/embedded-disaster-recovery). +::: The Replicated 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` @@ -281,7 +276,7 @@ To support backup and restore with snapshots, add the `kots.io/backup: velero` a 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_. -**Example** +#### Example The following example shows how to add backup labels for snapshots in the `optionalValues` key of the HelmChart custom resource: @@ -308,14 +303,42 @@ spec: kots.io/app-slug: repl{{ LicenseFieldValue "appSlug" }} ``` -### Support Local Image Registries for Online Installations {#local-registries} +## Task 5: Support the Use of Local Image Registries {#local-registries} -Local image registries are required for KOTS installations in air gapped environments. Also, users in online environments can optionally push images to a local registry. For more information about how users configure a local image registry with KOTS, see [Using Private Registries](/enterprise/image-registry-settings). +Local image registries are required for KOTS installations in air-gapped (disconnected) environments. Also, users in online environments can optionally push images to a local registry. For more information about how users configure a local image registry with KOTS, see [Using Private Registries](/enterprise/image-registry-settings). To support the use of local registries for online installations with version `kots.io/v1beta2` of the HelmChart custom resource, you must 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 [`builder`](/reference/custom-resource-helmchart-v2#builder) in _HelmChart v2_. -:::note -If you already configured the `builder` key previously to support air gap installations, then you can use the same configuration in your HelmChart custom resource to support the use of local registries for online installations. No additional configuration is required. -::: \ No newline at end of file +## HelmChart v1 and v2 Differences + +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
\ No newline at end of file From 9a8749196dd72d34d564725429888f68a14490d3 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Thu, 17 Oct 2024 09:41:15 -0600 Subject: [PATCH 02/20] edits --- docs/vendor/helm-native-v2-using.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/vendor/helm-native-v2-using.md b/docs/vendor/helm-native-v2-using.md index 1bc5962dfa..b520ec9c62 100644 --- a/docs/vendor/helm-native-v2-using.md +++ b/docs/vendor/helm-native-v2-using.md @@ -263,10 +263,10 @@ spec: ## Task 4: Add Backup Labels for Snapshots (KOTS Existing Cluster Installations Only) :::note -Snapshots is not supported for installations with Replicated Embedded Cluster. For more information about configuring backup and restore for Embedded Cluster, see [Disaster Recovery for Embedded Cluster](/vendor/embedded-disaster-recovery). +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 feature requires the following labels on all resources in your Helm chart that you want to be included in the backup: +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. @@ -305,7 +305,7 @@ spec: ## Task 5: Support the Use of Local Image Registries {#local-registries} -Local image registries are required for KOTS installations in air-gapped (disconnected) environments. Also, users in online environments can optionally push images to a local registry. For more information about how users configure a local image registry with KOTS, see [Using Private 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 push images to a local registry. For more information about how users configure a local image registry with KOTS, see [Using Private Registries](/enterprise/image-registry-settings). To support the use of local registries for online installations with version `kots.io/v1beta2` of the HelmChart custom resource, you must 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. From 6cc1a0461ce10cb985d45869722ef2703b7c2167 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Thu, 17 Oct 2024 11:27:59 -0600 Subject: [PATCH 03/20] edits --- docs/vendor/helm-native-v2-using.md | 59 +++++++++++++++-------------- 1 file changed, 30 insertions(+), 29 deletions(-) diff --git a/docs/vendor/helm-native-v2-using.md b/docs/vendor/helm-native-v2-using.md index b520ec9c62..5dc16bfffe 100644 --- a/docs/vendor/helm-native-v2-using.md +++ b/docs/vendor/helm-native-v2-using.md @@ -2,45 +2,34 @@ import KotsHelmCrDescription from "../partials/helm/_kots-helm-cr-description.md # Configuring the HelmChart Custom Resource v2 -This topic describes how to configure the Replicated HelmChart custom resource version `kots.io/v1beta2` to support Helm chart installations with Replicated KOTS. - -## Overview - - - -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). - -After you complete the tasks in this topic to configure the `kots.io/v1beta2` HelmChart custom resource, you can migrate any existing installations that were deployed with `kots.io/v1beta1` with `useHelmInstall: true` to use `kots.io/v1beta2` instead. For more information, see [Migrating Existing Installations to HelmChart v2](helm-v2-migrate). +This topic describes how to configure the Replicated HelmChart custom resource version `kots.io/v1beta2`. Complete the workflow in this topic to support Helm chart installations with Replicated KOTS. ## Workflow -To support installations with the `kots.io/v1beta2` HelmChart custom resource, do the following: -1. Rewrite image names so that images can be located in your private registry or in the user's local private registry. See [Rewrite Image Names](#rewrite-image-names). -1. Inject a KOTS-generated image pull secret that grants access to private images. See [Inject Image Pull Secrets](#inject-image-pull-secrets). +Do the following to configure the `kots.io/v1beta2` HelmChart custom resource: +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). 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. 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). +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. (KOTS Existing Cluster Instalaltions 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 backup and restore for Embedded Cluster, see [Disaster Recovery for Embedded Cluster](/vendor/embedded-disaster-recovery). ::: -1. Configure the `builder` key to allow your users to push images to local private registries. The `builder` key is required to support air gap installations. See [Support Local Image Registries](#local-registries). ## Task 1: Rewrite Image Names -Configure the KOTS HelmChart custom resource `values` key so that application image names are rewritten in your Helm chart values during deployment. This allows the images to be accessed through the [Replicated proxy service](private-images-about) at `proxy.replicated.com`, your customer's registry, or the built-in registry used in Embedded Cluster or kURL installations. +Configure the KOTS HelmChart custom resource `values` key so that KOTS can rewrite application image names in your Helm values during deployment. This allows images to be accessed through the [Replicated proxy service](private-images-about) at `proxy.replicated.com`, your customer's local registry, or the built-in registry used in Replicated Embedded Cluster or Replicated kURL installations. -During installation or upgrade with KOTS, application images are accessed from one of the following locations: -* The [Replicated proxy registry](private-images-about) at `proxy.replicated.com` -* The enterprise user's registry -* The built-in registry for Replicated Embedded Cluster or kURL installations - -You will use the following KOTS template functions in the HelmChart custom resource to rewrite image names: -* [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry): Returns true if the environment is configured to rewrite images to a local registry. HasLocalRegistry is always true for air gap installations and optionally true for online installations. You can use HasLocalRegistry to conditionally rewrite images depending on if your user configured a local registry or not. -* [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost): Returns the host of the local registry that the user configured. -* [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace): Returns the namespace of the local registry that the user configured. The registry namespace is the path between the registry and the image name. For example, `my.registry.com/namespace/image:tag`. +You will use the following KOTS template functions to rewrite image names: +* [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry): Returns true if the installation environment is configured to use a local registry. HasLocalRegistry is always true for air gap installations and optionally true for online installations. HasLocalRegistry is also true in installations with Replicated Embedded Cluster or Replicated kURL. +* [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost): Returns the host of the local registry that the user configured. Alternatively, for Embedded Cluster or kURL installations, LocalRegistryHost returns the host of the built-in registry used by Embedded Cluster or kURL. +* [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace): Returns the namespace of the local registry that the user configured. The registry namespace is the path between the registry and the image name. For example, `my.registry.com/namespace/image:tag`. Alternatively, for Embedded Cluster or kURL installations, LocalRegistryNamespace returns the namespace of the built-in registry used by Embedded Cluster or kURL. ### Rewrite Private Image Names {#local-proxy-example} -For any private images, configure the HelmChart custom resource so that image names are rewritten to `proxy.replicated.com/proxy//`, where `` is the unique application slug in the Vendor Portal and `` is the path to the image in the registry. +For any private images used by your application, configure the HelmChart custom resource so that image names are rewritten to `proxy.replicated.com/proxy//`, where: +* `` is the unique application slug in the Vendor Portal +* `` is the path to the image in your registry For example, if the private image is `quay.io/my-org/nginx:v1.0.1`, then the image name should be rewritten to `proxy.replicated.com/proxy/my-app-slug/quay.io/my-org/nginx:v1.0.1`. @@ -48,7 +37,7 @@ For example, if the private image is `quay.io/my-org/nginx:v1.0.1`, then the ima The following example shows how to configure the KOTS HelmChart `values` key to rewrite the registry hostname and namespace for a private image. -This example uses [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry) to conditionally update the registry hostname and namespace for the image depending on if the user configured a local registry. It also uses [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost) and [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace) to render the user-supplied hostname and namespace for the image on the local registry, if one was configured. +This example uses [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry) to conditionally update the registry hostname and namespace for the image. It also uses [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost) and [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace) to render the user-supplied hostname and namespace for the image on the local registry, if one was configured. ```yaml # kots.io/v1beta2 HelmChart custom resource @@ -99,7 +88,7 @@ spec: ### Rewrite Public Image Names {#local-public-example} -The following example shows a field in the `values` key that rewrites the registry domain to `docker.io` unless the user configured a local registry. Similarly, it shows a field that rewrites the image repository to the path of the public image on `docker.io` or in the user's local registry: +The following example shows a field in the `values` key that rewrites the registry domain to `docker.io` unless a local registry is used. Similarly, it shows a field that rewrites the image repository to the path of the public image on `docker.io` or in the user's local registry: ```yaml # kots.io/v1beta2 HelmChart custom resource @@ -311,7 +300,15 @@ To support the use of local registries for online installations with version `ko For more information about how to configure the `builder` key, see [`builder`](/reference/custom-resource-helmchart-v2#builder) in _HelmChart v2_. -## HelmChart v1 and v2 Differences +## 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 The `kots.io/v1beta2` HelmChart custom resource has the following differences from `kots.io/v1beta1`: @@ -341,4 +338,8 @@ The `kots.io/v1beta2` HelmChart custom resource has the following differences fr useHelmInstall useHelmInstall field is removed - \ No newline at end of file + + +### Migrate Existing HelmChart v1 Installations to v2 + +After you complete the tasks in this topic to configure the `kots.io/v1beta2` HelmChart custom resource, you can migrate any existing installations that were deployed with `kots.io/v1beta1` with `useHelmInstall: true` to use `kots.io/v1beta2` instead. For more information, see [Migrating Existing Installations to HelmChart v2](helm-v2-migrate). \ No newline at end of file From e4e8a58d84972b50e325dface8fc724bdcc5e510 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Thu, 17 Oct 2024 13:05:21 -0600 Subject: [PATCH 04/20] edits --- docs/vendor/helm-native-v2-using.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/docs/vendor/helm-native-v2-using.md b/docs/vendor/helm-native-v2-using.md index 5dc16bfffe..833b40ce14 100644 --- a/docs/vendor/helm-native-v2-using.md +++ b/docs/vendor/helm-native-v2-using.md @@ -21,11 +21,20 @@ Do the following to configure the `kots.io/v1beta2` HelmChart custom resource: Configure the KOTS HelmChart custom resource `values` key so that KOTS can rewrite application image names in your Helm values during deployment. This allows images to be accessed through the [Replicated proxy service](private-images-about) at `proxy.replicated.com`, your customer's local registry, or the built-in registry used in Replicated Embedded Cluster or Replicated kURL installations. You will use the following KOTS template functions to rewrite image names: -* [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry): Returns true if the installation environment is configured to use a local registry. HasLocalRegistry is always true for air gap installations and optionally true for online installations. HasLocalRegistry is also true in installations with Replicated Embedded Cluster or Replicated kURL. -* [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost): Returns the host of the local registry that the user configured. Alternatively, for Embedded Cluster or kURL installations, LocalRegistryHost returns the host of the built-in registry used by Embedded Cluster or kURL. -* [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace): Returns the namespace of the local registry that the user configured. The registry namespace is the path between the registry and the image name. For example, `my.registry.com/namespace/image:tag`. Alternatively, for Embedded Cluster or kURL installations, LocalRegistryNamespace returns the namespace of the built-in registry used by Embedded Cluster or kURL. +* [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry): Returns true if the installation environment is configured to use a local image registry. HasLocalRegistry is true in the following situations: + * Air gap installations + * Online installations if the user pushed images to their own registry + * Installations with Replicated Embedded Cluster or Replicated kURL where the built-in registry is used +* [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost): Returns the host of the local registry that the user configured. Alternatively, LocalRegistryHost returns the host of the built-in registry used by Embedded Cluster or kURL. +* [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace): Returns the namespace of the local registry that the user configured. Alternatively, LocalRegistryNamespace returns the namespace of the built-in registry used by Embedded Cluster or kURL. -### Rewrite Private Image Names {#local-proxy-example} +
+ What is the registry namespace? + + The registry namespace is the path between the registry and the image name. For example, `my.registry.com/namespace/image:tag`. +
+ +### Task 1a: Rewrite Private Image Names {#local-proxy-example} For any private images used by your application, configure the HelmChart custom resource so that image names are rewritten to `proxy.replicated.com/proxy//`, where: * `` is the unique application slug in the Vendor Portal @@ -86,7 +95,7 @@ spec: image: {{ .Values.image.registry }}/{{ .Values.image.repository }}:{{ .Values.image.tag }} ``` -### Rewrite Public Image Names {#local-public-example} +### Task 1b: Rewrite Public Image Names {#local-public-example} The following example shows a field in the `values` key that rewrites the registry domain to `docker.io` unless a local registry is used. Similarly, it shows a field that rewrites the image repository to the path of the public image on `docker.io` or in the user's local registry: From c331e0e4f32a1154fcf2c0896d817d721b75935a Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Thu, 17 Oct 2024 13:51:37 -0600 Subject: [PATCH 05/20] edits --- docs/vendor/helm-native-v2-using.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/docs/vendor/helm-native-v2-using.md b/docs/vendor/helm-native-v2-using.md index 833b40ce14..d76229a65a 100644 --- a/docs/vendor/helm-native-v2-using.md +++ b/docs/vendor/helm-native-v2-using.md @@ -18,15 +18,16 @@ Do the following to configure the `kots.io/v1beta2` HelmChart custom resource: ## Task 1: Rewrite Image Names -Configure the KOTS HelmChart custom resource `values` key so that KOTS can rewrite application image names in your Helm values during deployment. This allows images to be accessed through the [Replicated proxy service](private-images-about) at `proxy.replicated.com`, your customer's local registry, or the built-in registry used in Replicated Embedded Cluster or Replicated kURL installations. - -You will use the following KOTS template functions to rewrite image names: -* [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry): Returns true if the installation environment is configured to use a local image registry. HasLocalRegistry is true in the following situations: - * Air gap installations - * Online installations if the user pushed images to their own registry - * Installations with Replicated Embedded Cluster or Replicated kURL where the built-in registry is used -* [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost): Returns the host of the local registry that the user configured. Alternatively, LocalRegistryHost returns the host of the built-in registry used by Embedded Cluster or kURL. -* [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace): Returns the namespace of the local registry that the user configured. Alternatively, LocalRegistryNamespace returns the namespace of the built-in registry used by Embedded Cluster or kURL. +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: +* The [Replicated proxy registry](private-images-about) at `proxy.replicated.com` +* 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 pushed images to their own 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? From f2354b4beb3c7fd8c166a586e6dc9c8856b365be Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Thu, 17 Oct 2024 14:19:24 -0600 Subject: [PATCH 06/20] edits --- docs/vendor/helm-native-v2-using.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/docs/vendor/helm-native-v2-using.md b/docs/vendor/helm-native-v2-using.md index d76229a65a..8aad947965 100644 --- a/docs/vendor/helm-native-v2-using.md +++ b/docs/vendor/helm-native-v2-using.md @@ -43,11 +43,11 @@ For any private images used by your application, configure the HelmChart custom For example, if the private image is `quay.io/my-org/nginx:v1.0.1`, then the image name should be rewritten to `proxy.replicated.com/proxy/my-app-slug/quay.io/my-org/nginx:v1.0.1`. -#### Example +Additionally, 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 along with a ternary operator to conditionally render the registry hostname and namespace if a local registry is used (such as in air gap installations). See the example below for more information. -The following example shows how to configure the KOTS HelmChart `values` key to rewrite the registry hostname and namespace for a private image. +#### Example -This example uses [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry) to conditionally update the registry hostname and namespace for the image. It also uses [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost) and [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace) to render the user-supplied hostname and namespace for the image on the local registry, if one was configured. +The following HelmChart custom resource uses KOTS 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 @@ -61,10 +61,11 @@ spec: values: image: # If the user configured a registry, use that registry's hostname - # Else, use proxy.replicated.com + # If air gap Embedded Cluster/kURL install, use the buit-in registry's hostname + # Else use proxy.replicated.com registry: '{{repl HasLocalRegistry | ternary LocalRegistryHost "proxy.replicated.com" }}' # If the user configured a registry, use the registry namespace they provided - # Else if Embedded Cluster/kURL install, use the buit-in Embedded Cluster/kURL registry + # If air gap Embedded Cluster/kURL install, use the buit-in registry's hostname # Else use the image's namespace at proxy.replicated.com repository: '{{repl HasLocalRegistry | ternary LocalRegistryNamespace "proxy/my-app/quay.io/my-org" }}/nginx' tag: v1.0.1 @@ -98,7 +99,11 @@ spec: ### Task 1b: Rewrite Public Image Names {#local-public-example} -The following example shows a field in the `values` key that rewrites the registry domain to `docker.io` unless a local registry is used. Similarly, it shows a field that rewrites the image repository to the path of the public image on `docker.io` or in the user's local registry: +For any private images used by your application, configure the HelmChart custom resource so that image names + +#### Example + +The following HelmChart custom resource includes a field in the `values` key that rewrites the registry domain to `docker.io` unless a local registry is used. Similarly, it shows a field that rewrites the image repository to the path of the public image on `docker.io` or in the local registry: ```yaml # kots.io/v1beta2 HelmChart custom resource From ce2d361b2578ed66dfde955b02b3711d91eb27b9 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Thu, 17 Oct 2024 14:37:13 -0600 Subject: [PATCH 07/20] edits --- docs/vendor/helm-native-v2-using.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/docs/vendor/helm-native-v2-using.md b/docs/vendor/helm-native-v2-using.md index 8aad947965..0c8a475601 100644 --- a/docs/vendor/helm-native-v2-using.md +++ b/docs/vendor/helm-native-v2-using.md @@ -37,17 +37,17 @@ You will use the following KOTS template functions to conditionally rewrite imag ### Task 1a: Rewrite Private Image Names {#local-proxy-example} -For any private images used by your application, configure the HelmChart custom resource so that image names are rewritten to `proxy.replicated.com/proxy//`, where: +For any private images used by your application, configure the HelmChart custom resource so that image names are conditionally rewritten to either the location of the image in the Replicated proxy registry (for online installations) or the local registry (for air gap installations or online installations where images were pushed to a local registry). + +To rewrite images to the proxy registry, use the format `proxy.replicated.com/proxy//`, where: * `` is the unique application slug in the Vendor Portal * `` is the path to the image in your registry For example, if the private image is `quay.io/my-org/nginx:v1.0.1`, then the image name should be rewritten to `proxy.replicated.com/proxy/my-app-slug/quay.io/my-org/nginx:v1.0.1`. -Additionally, 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 along with a ternary operator to conditionally render the registry hostname and namespace if a local registry is used (such as in air gap installations). See the example below for more information. - #### Example -The following HelmChart custom resource uses KOTS template functions to conditionally rewrite an image registry and repository depending on if a local registry is used: +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 @@ -99,7 +99,7 @@ spec: ### Task 1b: Rewrite Public Image Names {#local-public-example} -For any private images used by your application, configure the HelmChart custom resource so that image names +For any public images used by your application, configure the HelmChart custom resource so that image names are conditionally 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 images were pushed to a local registry). #### Example @@ -127,9 +127,9 @@ The `spec.values.image.registry` and `spec.values.image.repository` fields in th # Helm chart values.yaml file image: - registry: docker.io - repository: docker.io/bitnami/mariadb - tag: v1.0.1 + 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: @@ -137,8 +137,6 @@ During installation, KOTS renders the template functions and sets the `image.reg ```yaml apiVersion: v1 kind: Pod -metadata: - name: mariadb spec: containers: - name: From eecf39106ce8e0d58b900aa5089754c711b629c0 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Thu, 17 Oct 2024 15:12:49 -0600 Subject: [PATCH 08/20] edits --- docs/vendor/helm-native-v2-using.md | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/docs/vendor/helm-native-v2-using.md b/docs/vendor/helm-native-v2-using.md index 0c8a475601..d3281e934a 100644 --- a/docs/vendor/helm-native-v2-using.md +++ b/docs/vendor/helm-native-v2-using.md @@ -2,7 +2,7 @@ import KotsHelmCrDescription from "../partials/helm/_kots-helm-cr-description.md # Configuring the HelmChart Custom Resource v2 -This topic describes how to configure the Replicated HelmChart custom resource version `kots.io/v1beta2`. Complete the workflow in this topic to support Helm chart installations with Replicated KOTS. +This topic describes how to configure the Replicated HelmChart custom resource version `kots.io/v1beta2` to support Helm chart installations with Replicated KOTS. ## Workflow @@ -262,6 +262,12 @@ spec: {{- end }} ``` +## Task 4: 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 push images to a local registry. For more information about how users configure a local image registry with KOTS, see [Using Private Registries](/enterprise/image-registry-settings). + +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_. + ## Task 4: Add Backup Labels for Snapshots (KOTS Existing Cluster Installations Only) :::note @@ -305,14 +311,6 @@ spec: kots.io/app-slug: repl{{ LicenseFieldValue "appSlug" }} ``` -## Task 5: 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 push images to a local registry. For more information about how users configure a local image registry with KOTS, see [Using Private Registries](/enterprise/image-registry-settings). - -To support the use of local registries for online installations with version `kots.io/v1beta2` of the HelmChart custom resource, you must 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 [`builder`](/reference/custom-resource-helmchart-v2#builder) in _HelmChart v2_. - ## Additional Information ### About the HelmChart Custom Resource From 52bf0757dde7f18a7c0b7a3d99a9d53f1a12dbb2 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Thu, 17 Oct 2024 15:45:41 -0600 Subject: [PATCH 09/20] edits --- docs/vendor/helm-native-v2-using.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/vendor/helm-native-v2-using.md b/docs/vendor/helm-native-v2-using.md index d3281e934a..df25b41ca1 100644 --- a/docs/vendor/helm-native-v2-using.md +++ b/docs/vendor/helm-native-v2-using.md @@ -16,7 +16,7 @@ Do the following to configure the `kots.io/v1beta2` HelmChart custom resource: Snapshots is not supported for installations with Replicated Embedded Cluster. For more information about configuring backup and restore for Embedded Cluster, see [Disaster Recovery for Embedded Cluster](/vendor/embedded-disaster-recovery). ::: -## Task 1: Rewrite Image Names +## 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: * The [Replicated proxy registry](private-images-about) at `proxy.replicated.com` @@ -35,7 +35,7 @@ You will use the following KOTS template functions to conditionally rewrite imag The registry namespace is the path between the registry and the image name. For example, `my.registry.com/namespace/image:tag`.
-### Task 1a: Rewrite Private Image Names {#local-proxy-example} +### Task 1a: Rewrite Private Image Names For any private images used by your application, configure the HelmChart custom resource so that image names are conditionally rewritten to either the location of the image in the Replicated proxy registry (for online installations) or the local registry (for air gap installations or online installations where images were pushed to a local registry). @@ -97,7 +97,7 @@ spec: image: {{ .Values.image.registry }}/{{ .Values.image.repository }}:{{ .Values.image.tag }} ``` -### Task 1b: Rewrite Public Image Names {#local-public-example} +### Task 1b: Rewrite Public Image Names For any public images used by your application, configure the HelmChart custom resource so that image names are conditionally 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 images were pushed to a local registry). @@ -143,7 +143,7 @@ spec: image: {{ .Values.image.registry }}/{{ .Values.image.repository }}:{{ .Values.image.tag }} ``` -## Task 2: Inject Image Pull Secrets +## Task 2: Inject Image Pull Secrets {#inject-image-pull-secrets} 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. @@ -268,7 +268,7 @@ Local image registries are required for KOTS installations in air-gapped environ 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_. -## Task 4: Add Backup Labels for Snapshots (KOTS Existing Cluster Installations Only) +## Task 5: Add Backup Labels for Snapshots (KOTS Existing Cluster Installations Only) {#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). From b56a7aa90a3cdb44943303260ec075d31532dc14 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Thu, 17 Oct 2024 15:56:36 -0600 Subject: [PATCH 10/20] update reference docs --- docs/reference/template-functions-config-context.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/reference/template-functions-config-context.md b/docs/reference/template-functions-config-context.md index 53ec2f55df..ee877a6ba1 100644 --- a/docs/reference/template-functions-config-context.md +++ b/docs/reference/template-functions-config-context.md @@ -164,8 +164,9 @@ This will always return everything before the image name and tag. func LocalRegistryHost() string ``` -Returns the local registry host that's configured. -This will include port if one is specified. +Returns the host of the local registry that the user configured. Alternatively, for air gap installations with Replicated Embedded Cluster or Replicated kURL, LocalRegistryHost returns the host of the built-in registry. + +Includes the port if one is specified. ## LocalRegistryNamespace @@ -173,7 +174,7 @@ This will include port if one is specified. func LocalRegistryNamespace() string ``` -Returns the local registry namespace that's configured. +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. ## LocalImageName @@ -257,4 +258,4 @@ func HasLocalRegistry() bool ``` Returns true if the environment is configured to rewrite images to a local registry. -This is true for air gapped installations, and optionally true for online installations. \ No newline at end of file +HasLocalRegistry is always true for air gap installations. HasLocalRegistry is true in online installations if the user pushed images to a local registry. \ No newline at end of file From 6003988e5f8b2d7aee24a9bcdcf17159decc5f4e Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Fri, 18 Oct 2024 11:43:18 -0600 Subject: [PATCH 11/20] edit public image example --- docs/vendor/helm-native-v2-using.md | 30 ++++++++++++++++++----------- 1 file changed, 19 insertions(+), 11 deletions(-) diff --git a/docs/vendor/helm-native-v2-using.md b/docs/vendor/helm-native-v2-using.md index df25b41ca1..f32b7c421d 100644 --- a/docs/vendor/helm-native-v2-using.md +++ b/docs/vendor/helm-native-v2-using.md @@ -2,24 +2,24 @@ import KotsHelmCrDescription from "../partials/helm/_kots-helm-cr-description.md # Configuring the HelmChart Custom Resource v2 -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 HelmChart custom resource version `kots.io/v1beta2` to support Helm chart installations with Replicated KOTS. ## Workflow -Do the following to configure the `kots.io/v1beta2` HelmChart custom resource: +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). 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. (KOTS Existing Cluster Instalaltions 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 backup and restore for Embedded Cluster, see [Disaster Recovery for Embedded Cluster](/vendor/embedded-disaster-recovery). + 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} 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: -* The [Replicated proxy registry](private-images-about) at `proxy.replicated.com` +* The [Replicated proxy registry](private-images-about) (`proxy.replicated.com`) * 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 @@ -37,14 +37,16 @@ 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 conditionally rewritten to either the location of the image in the Replicated proxy registry (for online installations) or the local registry (for air gap installations or online installations where images were pushed to a local registry). +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 images were pushed to a local registry). -To rewrite images to the proxy registry, use the format `proxy.replicated.com/proxy//`, where: +To rewrite image names to the location of the image in the proxy registry, use the format `proxy.replicated.com/proxy//`, where: * `` is the unique application slug in the Vendor Portal * `` is the path to the image in your registry For example, if the private image is `quay.io/my-org/nginx:v1.0.1`, then the image name should be rewritten to `proxy.replicated.com/proxy/my-app-slug/quay.io/my-org/nginx:v1.0.1`. +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: @@ -99,11 +101,13 @@ spec: ### Task 1b: Rewrite Public Image Names -For any public images used by your application, configure the HelmChart custom resource so that image names are conditionally 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 images were pushed to a local registry). +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 images were pushed to a local registry). + +For example, if the public image is `ghcr.io/cloudnative-pg/cloudnative-pg:catalog-1.24.0`, then the image name should be rewritten to `proxy.replicated.com/anonymous/ghcr.io/cloudnative-pg/cloudnative-pg:catalog-1.24.0`. #### Example -The following HelmChart custom resource includes a field in the `values` key that rewrites the registry domain to `docker.io` unless a local registry is used. Similarly, it shows a field that rewrites the image repository to the path of the public image on `docker.io` or in the local registry: +The following HelmChart custom resource includes a field in the `values` key that rewrites the registry domain to `ghcr.io` unless a local registry is used. Similarly, it shows a field that rewrites the image repository to the path of the public image on `ghcr.io` or in the local registry: ```yaml # kots.io/v1beta2 HelmChart custom resource @@ -116,9 +120,13 @@ spec: ... values: image: - registry: '{{repl HasLocalRegistry | ternary LocalRegistryHost "docker.io" }}' - repository: '{{repl HasLocalRegistry | ternary LocalRegistryNamespace "bitnami" }}/mariadb' - tag: v1.0.1 + # 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 the user configured a registry, 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: From 81454de9054d80b001034531faafc58abdd921f9 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Fri, 18 Oct 2024 11:49:03 -0600 Subject: [PATCH 12/20] edits --- docs/vendor/helm-native-v2-using.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/vendor/helm-native-v2-using.md b/docs/vendor/helm-native-v2-using.md index f32b7c421d..87af0cb097 100644 --- a/docs/vendor/helm-native-v2-using.md +++ b/docs/vendor/helm-native-v2-using.md @@ -18,7 +18,7 @@ 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: +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: * The [Replicated proxy registry](private-images-about) (`proxy.replicated.com`) * A public image registry * Your customer's local registry @@ -103,11 +103,11 @@ spec: 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 images were pushed to a local registry). -For example, if the public image is `ghcr.io/cloudnative-pg/cloudnative-pg:catalog-1.24.0`, then the image name should be rewritten to `proxy.replicated.com/anonymous/ghcr.io/cloudnative-pg/cloudnative-pg:catalog-1.24.0`. +For more information, see the example below. #### Example -The following HelmChart custom resource includes a field in the `values` key that rewrites the registry domain to `ghcr.io` unless a local registry is used. Similarly, it shows a field that rewrites the image repository to the path of the public image on `ghcr.io` or in the local registry: +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 From 116b54d2bad7640acc7021dc475a02be676d09ed Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Thu, 7 Nov 2024 09:22:56 -0700 Subject: [PATCH 13/20] Remove unsupported characters --- docs/reference/cron-expressions.md | 26 ++++---------------------- 1 file changed, 4 insertions(+), 22 deletions(-) diff --git a/docs/reference/cron-expressions.md b/docs/reference/cron-expressions.md index 1420e06223..85d389676a 100644 --- a/docs/reference/cron-expressions.md +++ b/docs/reference/cron-expressions.md @@ -33,7 +33,7 @@ The following table lists the required cron fields and supported values: Day-of-month 1 through 31 - , - * ? L W + , - * ? Month @@ -43,12 +43,14 @@ The following table lists the required cron fields and supported values: Day-of-week 1 through 7 or SUN through SAT - , - * ? L + , - * ? ## Special Characters +Replicated uses the cron v3 Go library. For more information about usage, see [cron](https://pkg.go.dev/github.com/robfig/cron/v3). + The following table describes the supported special characters: @@ -72,14 +74,6 @@ The following table describes the supported special characters: - - - - - - - -
Question mark (?) Specifies that one or another value can be used. For example, enter 5 for Day-of-the-month and ? for Day-of-the-week to check for updates on the 5th day of the month, regardless of which day of the week it is.
LSpecifies the last day of the month or week respectively for the Day-of-month or Day-of-week fields.
WSpecifies the "N-th" occurrence or given day in the month. For example, the second Friday of the month is specified as 6#2.
## Predefined Schedules @@ -151,18 +145,6 @@ The following examples show valid cron expressions to schedule checking for upda 30 11 * * * ``` -- At 6:00 PM on the fourth Monday of every month: - - ``` - 0 18 ? * 2#4 - ``` - -- At midnight on the last day of every month: - - ``` - 0 0 L * ? - ``` - - After 1 hour and 45 minutes, and then every interval following that: ``` From c2dc332ddfa8e1807ee613f927ed002d766e0595 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Thu, 7 Nov 2024 09:30:09 -0700 Subject: [PATCH 14/20] revert changes to cron expressions topic --- docs/reference/cron-expressions.md | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/docs/reference/cron-expressions.md b/docs/reference/cron-expressions.md index 85d389676a..fa71c34436 100644 --- a/docs/reference/cron-expressions.md +++ b/docs/reference/cron-expressions.md @@ -33,7 +33,7 @@ The following table lists the required cron fields and supported values: Day-of-month 1 through 31 - , - * ? + , - * ? L W Month @@ -43,14 +43,12 @@ The following table lists the required cron fields and supported values: Day-of-week 1 through 7 or SUN through SAT - , - * ? + , - * ? L ## Special Characters -Replicated uses the cron v3 Go library. For more information about usage, see [cron](https://pkg.go.dev/github.com/robfig/cron/v3). - The following table describes the supported special characters: @@ -74,6 +72,14 @@ The following table describes the supported special characters: + + + + + + + +
Question mark (?) Specifies that one or another value can be used. For example, enter 5 for Day-of-the-month and ? for Day-of-the-week to check for updates on the 5th day of the month, regardless of which day of the week it is.
LSpecifies the last day of the month or week respectively for the Day-of-month or Day-of-week fields.
WSpecifies the "N-th" occurrence or given day in the month. For example, the second Friday of the month is specified as 6#2.
## Predefined Schedules @@ -143,11 +149,4 @@ The following examples show valid cron expressions to schedule checking for upda ``` 30 11 * * * - ``` - -- After 1 hour and 45 minutes, and then every interval following that: - - ``` - @every 1h45m - ``` - + ` \ No newline at end of file From 66bcee6b69346730739c438e3b30d954bc4f18ba Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Thu, 7 Nov 2024 09:30:56 -0700 Subject: [PATCH 15/20] revert changes to cron expressions topic --- docs/reference/cron-expressions.md | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/docs/reference/cron-expressions.md b/docs/reference/cron-expressions.md index fa71c34436..a203058180 100644 --- a/docs/reference/cron-expressions.md +++ b/docs/reference/cron-expressions.md @@ -149,4 +149,22 @@ The following examples show valid cron expressions to schedule checking for upda ``` 30 11 * * * - ` \ No newline at end of file + ``` + +- At 6:00 PM on the fourth Monday of every month: + + ``` + 0 18 ? * 2#4 + ``` + +- At midnight on the last day of every month: + + ``` + 0 0 L * ? + ``` + +- After 1 hour and 45 minutes, and then every interval following that: + + ``` + @every 1h45m + ``` \ No newline at end of file From 50b7fdb2dfa543a38036d3ad478ef3d0aa4d0dc3 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Thu, 7 Nov 2024 09:31:17 -0700 Subject: [PATCH 16/20] revert changes to cron expressions topic --- docs/reference/cron-expressions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/cron-expressions.md b/docs/reference/cron-expressions.md index a203058180..5e6bcdfee1 100644 --- a/docs/reference/cron-expressions.md +++ b/docs/reference/cron-expressions.md @@ -149,7 +149,7 @@ The following examples show valid cron expressions to schedule checking for upda ``` 30 11 * * * - ``` + ``` - At 6:00 PM on the fourth Monday of every month: From 5de0300ec6a2428873705e87af517e8969da6a47 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Thu, 7 Nov 2024 09:31:39 -0700 Subject: [PATCH 17/20] revert changes to cron expressions topic --- docs/reference/cron-expressions.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/reference/cron-expressions.md b/docs/reference/cron-expressions.md index 5e6bcdfee1..ef841a7ba4 100644 --- a/docs/reference/cron-expressions.md +++ b/docs/reference/cron-expressions.md @@ -167,4 +167,5 @@ The following examples show valid cron expressions to schedule checking for upda ``` @every 1h45m - ``` \ No newline at end of file + ``` + \ No newline at end of file From f49065b447624636d763242978f0ed62547f9ed2 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Thu, 7 Nov 2024 09:32:05 -0700 Subject: [PATCH 18/20] revert changes to cron expressions topic --- docs/reference/cron-expressions.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/reference/cron-expressions.md b/docs/reference/cron-expressions.md index ef841a7ba4..5e5efd9f89 100644 --- a/docs/reference/cron-expressions.md +++ b/docs/reference/cron-expressions.md @@ -168,4 +168,3 @@ The following examples show valid cron expressions to schedule checking for upda ``` @every 1h45m ``` - \ No newline at end of file From 43c1a57a8813783495e8a7757f8969aafb4ade44 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Wed, 13 Nov 2024 09:36:14 -0700 Subject: [PATCH 19/20] Apply suggestions from code review Co-authored-by: Alex Parker <7272359+ajp-io@users.noreply.github.com> --- docs/vendor/helm-native-v2-using.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/vendor/helm-native-v2-using.md b/docs/vendor/helm-native-v2-using.md index abad59b8b6..72ba134253 100644 --- a/docs/vendor/helm-native-v2-using.md +++ b/docs/vendor/helm-native-v2-using.md @@ -11,7 +11,7 @@ To support Helm chart installations with the KOTS `kots.io/v1beta2` HelmChart cu 1. Inject a KOTS-generated image pull secret that grants proxy access to private images. 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. (KOTS Existing Cluster Instalaltions 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). +1. (KOTS Existing Cluster 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). ::: From 65398bf596ef40e8f44e8cc700333c7b5faf11ad Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Wed, 13 Nov 2024 09:45:02 -0700 Subject: [PATCH 20/20] edits --- docs/vendor/helm-native-v2-using.md | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/docs/vendor/helm-native-v2-using.md b/docs/vendor/helm-native-v2-using.md index 72ba134253..1da7fa0409 100644 --- a/docs/vendor/helm-native-v2-using.md +++ b/docs/vendor/helm-native-v2-using.md @@ -25,7 +25,7 @@ Configure the KOTS HelmChart custom resource `values` key so that KOTS rewrites * 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 pushed images to their own registry. +* [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. @@ -37,7 +37,7 @@ 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 images were pushed to a local registry). +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.replicated.com/proxy//`, where: * `` is the unique application slug in the Vendor Portal @@ -62,12 +62,10 @@ spec: ... values: image: - # If the user configured a registry, use that registry's hostname - # If air gap Embedded Cluster/kURL install, use the buit-in registry's hostname + # If a registry is configured by the user or by Embedded Cluster/kURL, use that registry's hostname # Else use proxy.replicated.com registry: '{{repl HasLocalRegistry | ternary LocalRegistryHost "proxy.replicated.com" }}' - # If the user configured a registry, use the registry namespace they provided - # If air gap Embedded Cluster/kURL install, use the buit-in registry's hostname + # If a registry is configured by the user or by Embedded Cluster/kURL, use that registry namespace # Else use the image's namespace at proxy.replicated.com repository: '{{repl HasLocalRegistry | ternary LocalRegistryNamespace "proxy/my-app/quay.io/my-org" }}/nginx' tag: v1.0.1 @@ -101,7 +99,7 @@ spec: ### 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 images were pushed to a local registry). +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. @@ -123,7 +121,7 @@ spec: # 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 the user configured a registry, use the registry namespace provided + # 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 @@ -272,7 +270,7 @@ spec: ## Task 4: 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 push images to a local registry. For more information about how users configure a local image registry with KOTS, see [Using Private 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. For more information about how users configure a local image registry with KOTS, see [Using Private Registries](/enterprise/image-registry-settings). 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_.