diff --git a/docs/reference/cron-expressions.md b/docs/reference/cron-expressions.md index b60ef756bf..0f243d7f37 100644 --- a/docs/reference/cron-expressions.md +++ b/docs/reference/cron-expressions.md @@ -149,4 +149,4 @@ The following examples show valid cron expressions to schedule checking for upda ``` @every 1h45m - ``` \ No newline at end of file + ``` 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 diff --git a/docs/vendor/helm-native-v2-using.md b/docs/vendor/helm-native-v2-using.md index 3134d26738..1da7fa0409 100644 --- a/docs/vendor/helm-native-v2-using.md +++ b/docs/vendor/helm-native-v2-using.md @@ -4,37 +4,52 @@ import KotsHelmCrDescription from "../partials/helm/_kots-helm-cr-description.md This topic describes how to configure the Replicated HelmChart custom resource version `kots.io/v1beta2` to support Helm chart installations with Replicated KOTS. -## Overview +## 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). +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 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). + ::: -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). +## Task 1: Rewrite Image Names {#rewrite-image-names} -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). +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 +* The built-in registry used in Replicated Embedded Cluster or Replicated kURL installations in air-gapped environments -## Workflow +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, `my.registry.com/namespace/image:tag`. +
-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). +### Task 1a: Rewrite Private Image Names -### Rewrite 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). -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. +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 -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. +For more information, see the example below. -#### Example: Rewrite private image names {#local-proxy-example} +#### Example -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: +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 @@ -47,12 +62,16 @@ 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 registry: '{{repl HasLocalRegistry | ternary LocalRegistryHost "proxy.replicated.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 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 @@ -63,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 @@ -76,9 +97,15 @@ spec: image: {{ .Values.image.registry }}/{{ .Values.image.repository }}:{{ .Values.image.tag }} ``` -#### Example: 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 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 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 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 @@ -91,9 +118,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 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: @@ -102,9 +133,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: @@ -112,15 +143,13 @@ During installation, KOTS renders the template functions and sets the `image.reg ```yaml apiVersion: v1 kind: Pod -metadata: - name: mariadb spec: containers: - name: image: {{ .Values.image.registry }}/{{ .Values.image.repository }}:{{ .Values.image.tag }} ``` -### 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. @@ -128,7 +157,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: @@ -160,7 +189,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 @@ -177,7 +208,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). @@ -187,7 +218,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: @@ -237,7 +268,13 @@ spec: {{- end }} ``` -### Add Backup Labels for Snapshots +## 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 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_. + +## 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). @@ -253,7 +290,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: @@ -280,16 +317,21 @@ spec: kots.io/app-slug: repl{{ LicenseFieldValue "appSlug" }} ``` -### Support Local Image Registries {#local-registries} +## Additional Information + +### About the HelmChart Custom Resource -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). + + + +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_. -## HelmChart v1 and v2 Differences - The `kots.io/v1beta2` HelmChart custom resource has the following differences from `kots.io/v1beta1`: @@ -318,4 +360,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).