From 113d98b0e84593bc4d1d5974b18604a6c41f4912 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Fri, 6 Sep 2024 15:46:39 -0600 Subject: [PATCH 01/11] Use anonymous for rewriting public images --- docs/vendor/helm-native-v2-using.md | 49 ++++++++++++++++++----------- 1 file changed, 31 insertions(+), 18 deletions(-) diff --git a/docs/vendor/helm-native-v2-using.md b/docs/vendor/helm-native-v2-using.md index 63c6c397ca..40cdba35ff 100644 --- a/docs/vendor/helm-native-v2-using.md +++ b/docs/vendor/helm-native-v2-using.md @@ -47,24 +47,33 @@ The `kots.io/v1beta2` HelmChart custom resource has the following differences fr ## Workflow 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). +* Rewrite image names so that images can be located in your registry or in the user's local 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). +* 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. + ::: * 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). -### Rewrite Image Names +## Rewrite Image Names -During installation or upgrade with KOTS, any application images in the software vendor's private registry are accessed through the [Replicated proxy service](private-images-about) at `proxy.replicated.com`. Additionally, KOTS allows enterprise users to push images to their own registry. +During installation or upgrade with KOTS, any application images in the software vendor's private registry are accessed through the [Replicated proxy service](private-images-about) at `proxy.replicated.com`. Replicated recommends that any public images are also proxied through the Replicated proxy service to reduce to total number of endpoints that your users are required to allowlist. Enterprise users can also push images to their own 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. +To ensure that images are discovered in either your registry or in your user's registry, configure the HelmChart custom resource so that image names are rewritten in your Helm chart during deployment. -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 image names to a local registry or the proxy service](#local-proxy-example) or [Example: Rewrite images names to a local registry or the vendor's public registry](#local-public-example) below. +### About the KOTS Registry Template Functions -#### Example: Rewrite private image names {#local-proxy-example} +You can use the following KOTS template functions 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 gapped installations and optionally true for online installations. +* [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. + +These template functions can be used to conditionally rewrite images names in your Helm chart so that KOTS uses the host and namespace of your user's registry only if they configured one. + +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`. + +### Rewrite Private Image Names {#local-proxy-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: @@ -108,9 +117,13 @@ 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} + +For any public images, use `proxy.replicated.com/anonymous/`. + +So, if your image is `registry.k8s.io/metrics-server/metrics-server:v0.7.0`, you would use `proxy.replicated.com/anonymous/registry.k8s.io/metrics-server/metrics-server:v0.7.0`. -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 `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 public image on `docker.io` or in the user's local registry: ```yaml # kots.io/v1beta2 HelmChart custom resource @@ -123,8 +136,8 @@ spec: ... values: image: - registry: '{{repl HasLocalRegistry | ternary LocalRegistryHost "docker.io" }}' - repository: '{{repl HasLocalRegistry | ternary LocalRegistryNamespace "bitnami" }}/mariadb' + registry: '{{repl HasLocalRegistry | ternary LocalRegistryHost "proxy.replicated.com" }}' + repository: '{{repl HasLocalRegistry | ternary LocalRegistryNamespace "anonymous" }}/metrics-server' tag: v1.0.1 ``` @@ -152,7 +165,7 @@ spec: image: {{ .Values.image.registry }}/{{ .Values.image.repository }}:{{ .Values.image.tag }} ``` -### 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. @@ -209,7 +222,7 @@ spec: {{- end }} ``` -### Add Pull Secret for Rate-Limited Docker Hub Images {#docker-secret} +## 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). @@ -269,7 +282,7 @@ spec: {{- end }} ``` -### Add Backup Labels for Snapshots +## Add Backup Labels for Snapshots 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` @@ -308,7 +321,7 @@ spec: kots.io/app-slug: repl{{ LicenseFieldValue "appSlug" }} ``` -### Support Local Image Registries for Online Installations {#local-registries} +## Support Local Image Registries for Online Installations {#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). From fbcd20f2ab1f18be0e39073a1a5f45453a17d328 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Mon, 9 Sep 2024 12:00:27 -0600 Subject: [PATCH 02/11] edits --- docs/vendor/helm-native-v2-using.md | 34 ++++++++++++++++------------- 1 file changed, 19 insertions(+), 15 deletions(-) diff --git a/docs/vendor/helm-native-v2-using.md b/docs/vendor/helm-native-v2-using.md index 40cdba35ff..f8fb453b0f 100644 --- a/docs/vendor/helm-native-v2-using.md +++ b/docs/vendor/helm-native-v2-using.md @@ -58,24 +58,26 @@ To support installations with the `kots.io/v1beta2` HelmChart custom resource, d ## Rewrite Image Names -During installation or upgrade with KOTS, any application images in the software vendor's private registry are accessed through the [Replicated proxy service](private-images-about) at `proxy.replicated.com`. Replicated recommends that any public images are also proxied through the Replicated proxy service to reduce to total number of endpoints that your users are required to allowlist. Enterprise users can also push images to their own registry. +During installation and upgrade with KOTS, any application images in your private registry must be accessed through the [Replicated proxy service](private-images-about) at `proxy.replicated.com`. Replicated also recommends that any public application images are proxied through the proxy service to reduce the total number of endpoints that your users are required to add to an allowlist. -To ensure that images are discovered in either your registry or in your user's registry, configure the HelmChart custom resource so that image names are rewritten in your Helm chart during deployment. +Additionally, your users can push images to their own registry. This is common especially for installations in air gap environments. + +To ensure that all application images can be discovered, you need to configure the HelmChart custom resource so that image names are rewritten in your Helm chart during deployment. ### About the KOTS Registry Template Functions -You can use the following KOTS template functions to rewrite image names: +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 gapped installations and optionally true for online installations. * [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. +* [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`. -These template functions can be used to conditionally rewrite images names in your Helm chart so that KOTS uses the host and namespace of your user's registry only if they configured one. +### Rewrite Private Image Names {#local-proxy-example} -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`. +To rewrite names of private images, use the [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry) template function to conditionally update the registry hostname and namespace for the image depending on if the end user configured their own registry. -### 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 example shows how to configure fields in the HelmChart `values` key that rewrite the registry domain and namespace for an image on `proxy.replicated.com` or in the end user's own registry: ```yaml # kots.io/v1beta2 HelmChart custom resource @@ -85,10 +87,13 @@ kind: HelmChart metadata: name: samplechart 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 provided + # 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 ``` @@ -104,7 +109,7 @@ 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 @@ -119,11 +124,11 @@ spec: ### Rewrite Public Image Names {#local-public-example} -For any public images, use `proxy.replicated.com/anonymous/`. +For any public images, configure the HelmChart custom resource so that image names are rewritten to `proxy.replicated.com/anonymous/`. This allows the public image to be accessed through the Replicated proxy service at `proxy.replicated.com`. Replicated recommends proxying both public and private images through the proxy service because it reduces the total number of endpoints that your users need to add to an allowlist. -So, if your image is `registry.k8s.io/metrics-server/metrics-server:v0.7.0`, you would use `proxy.replicated.com/anonymous/registry.k8s.io/metrics-server/metrics-server:v0.7.0`. +#### 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 public image on `docker.io` or in the user's local registry: +So, if your image is `registry.k8s.io/metrics-server/metrics-server:v0.7.0`, you would use `proxy.replicated.com/anonymous/registry.k8s.io/metrics-server/metrics-server:v0.7.0`. ```yaml # kots.io/v1beta2 HelmChart custom resource @@ -133,11 +138,10 @@ kind: HelmChart metadata: name: samplechart spec: - ... values: image: registry: '{{repl HasLocalRegistry | ternary LocalRegistryHost "proxy.replicated.com" }}' - repository: '{{repl HasLocalRegistry | ternary LocalRegistryNamespace "anonymous" }}/metrics-server' + repository: '{{repl HasLocalRegistry | ternary LocalRegistryNamespace "anonymous" }}/registry.k8s.io/metrics-server' tag: v1.0.1 ``` From 2e7a10a82cf803e05cc5d8d0d88028399629c55e Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Mon, 9 Sep 2024 13:50:58 -0600 Subject: [PATCH 03/11] edits --- docs/vendor/helm-native-v2-using.md | 34 +++++++++++++++++++---------- 1 file changed, 22 insertions(+), 12 deletions(-) diff --git a/docs/vendor/helm-native-v2-using.md b/docs/vendor/helm-native-v2-using.md index f8fb453b0f..98e8d4befe 100644 --- a/docs/vendor/helm-native-v2-using.md +++ b/docs/vendor/helm-native-v2-using.md @@ -58,11 +58,11 @@ To support installations with the `kots.io/v1beta2` HelmChart custom resource, d ## Rewrite Image Names -During installation and upgrade with KOTS, any application images in your private registry must be accessed through the [Replicated proxy service](private-images-about) at `proxy.replicated.com`. Replicated also recommends that any public application images are proxied through the proxy service to reduce the total number of endpoints that your users are required to add to an allowlist. +During installation and upgrade with KOTS, any application images in your private registry must be accessed through the [Replicated proxy service](private-images-about) at `proxy.replicated.com`. Replicated also recommends that any public application images are accessed through the proxy service to reduce the total number of endpoints that your users are required to add to an allowlist. -Additionally, your users can push images to their own registry. This is common especially for installations in air gap environments. +Additionally, your users can push images to their own registry. This is required for installations in air gap environments. -To ensure that all application images can be discovered, you need to configure the HelmChart custom resource so that image names are rewritten in your Helm chart during deployment. +To ensure that your application images can be discovered, you need to configure the HelmChart custom resource so that image names are rewritten in your Helm chart during deployment. ### About the KOTS Registry Template Functions @@ -73,7 +73,11 @@ You will use the following KOTS template functions in the HelmChart custom resou ### Rewrite Private Image Names {#local-proxy-example} -To rewrite names of private images, use the [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry) template function to conditionally update the registry hostname and namespace for the image depending on if the end user configured their own registry. +For any private images, configure the HelmChart custom resource so that image names are rewritten to `proxy.replicated.com/proxy/`. For example, if the private image is `registry.k8s.io/my-app/quay.io/my-org/nginx:v1.0.1`, then the image name should be rewritten to `proxy.replicated.com/proxy/my-app/quay.io/my-org/nginx:v1.0.1`. + +To rewrite names of private images, use the [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry) template function to conditionally update the registry hostname and namespace for the image: +* If the user configured a registry, use the hostname and namespace provided by the user +* Else, use `proxy.replicated.com` and #### Example @@ -124,11 +128,11 @@ spec: ### Rewrite Public Image Names {#local-public-example} -For any public images, configure the HelmChart custom resource so that image names are rewritten to `proxy.replicated.com/anonymous/`. This allows the public image to be accessed through the Replicated proxy service at `proxy.replicated.com`. Replicated recommends proxying both public and private images through the proxy service because it reduces the total number of endpoints that your users need to add to an allowlist. +For any public images, configure the HelmChart custom resource so that image names are rewritten to `proxy.replicated.com/anonymous/`. For example, if the public image is `registry.k8s.io/metrics-server/metrics-server:v0.7.0`, then the image name should be rewritten to `proxy.replicated.com/anonymous/registry.k8s.io/metrics-server/metrics-server:v0.7.0`. -#### Example +This allows the public image to be accessed through the Replicated proxy service at `proxy.replicated.com`. Replicated recommends proxying both public and private images through the proxy service because it reduces the total number of endpoints that your users need to add to an allowlist. -So, if your image is `registry.k8s.io/metrics-server/metrics-server:v0.7.0`, you would use `proxy.replicated.com/anonymous/registry.k8s.io/metrics-server/metrics-server:v0.7.0`. +#### Example ```yaml # kots.io/v1beta2 HelmChart custom resource @@ -140,8 +144,12 @@ metadata: 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" }}' - repository: '{{repl HasLocalRegistry | ternary LocalRegistryNamespace "anonymous" }}/registry.k8s.io/metrics-server' + # If the user configured a registry, use the registry namespace provided + # Else, use "anonymous/registry.k8s.io" + repository: '{{repl HasLocalRegistry | ternary LocalRegistryNamespace "anonymous/registry.k8s.io" }}/metrics-server/metrics-server' tag: v1.0.1 ``` @@ -151,12 +159,14 @@ 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: registry.k8s.io + repository: registry.k8s.io/metrics-server/metrics-server + tag: v0.7.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: +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: ```yaml apiVersion: v1 From 616952a45672c387fc9b97ced9a9d540af49ec56 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Tue, 10 Sep 2024 11:49:02 -0600 Subject: [PATCH 04/11] edits --- docs/vendor/helm-native-v2-using.md | 44 ++++++++++++++++++----------- 1 file changed, 28 insertions(+), 16 deletions(-) diff --git a/docs/vendor/helm-native-v2-using.md b/docs/vendor/helm-native-v2-using.md index 98e8d4befe..d3b14d873a 100644 --- a/docs/vendor/helm-native-v2-using.md +++ b/docs/vendor/helm-native-v2-using.md @@ -64,24 +64,22 @@ Additionally, your users can push images to their own registry. This is required To ensure that your application images can be discovered, you need to configure the HelmChart custom resource so that image names are rewritten in your Helm chart during deployment. -### About the KOTS Registry Template Functions - 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 gapped installations and optionally true for online installations. +* [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 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/`. For example, if the private image is `registry.k8s.io/my-app/quay.io/my-org/nginx:v1.0.1`, then the image name should be rewritten to `proxy.replicated.com/proxy/my-app/quay.io/my-org/nginx:v1.0.1`. +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 rewrite names of private images, use the [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry) template function to conditionally update the registry hostname and namespace for the image: -* If the user configured a registry, use the hostname and namespace provided by the user -* Else, use `proxy.replicated.com` and +For example, if the private image is `registry.k8s.io/quay.io/my-org/nginx:v1.0.1`, then the image name should be rewritten to `proxy.replicated.com/proxy/my-app/quay.io/my-org/nginx:v1.0.1`. #### Example -The following example shows how to configure fields in the HelmChart `values` key that rewrite the registry domain and namespace for an image on `proxy.replicated.com` or in the end user's own registry: +The following example shows how to configure the 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. ```yaml # kots.io/v1beta2 HelmChart custom resource @@ -102,7 +100,7 @@ spec: 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 @@ -113,7 +111,9 @@ image: tag: v1.0.1 ``` -During installation, KOTS renders the template functions and sets the `image.registry` and `image.repository` fields in the Helm chart `values.yaml` file based on the value of the corresponding fields in the HelmChart custom resource. Any templates in the Helm chart that access the `image.registry` and `image.repository` fields are updated to use the appropriate value, as shown in the example below: +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 @@ -128,12 +128,22 @@ spec: ### Rewrite Public Image Names {#local-public-example} -For any public images, configure the HelmChart custom resource so that image names are rewritten to `proxy.replicated.com/anonymous/`. For example, if the public image is `registry.k8s.io/metrics-server/metrics-server:v0.7.0`, then the image name should be rewritten to `proxy.replicated.com/anonymous/registry.k8s.io/metrics-server/metrics-server:v0.7.0`. +For any public images, configure the HelmChart custom resource so that image names are rewritten to `proxy.replicated.com/anonymous/`, where `` is the path to the image in the public registry. -This allows the public image to be accessed through the Replicated proxy service at `proxy.replicated.com`. Replicated recommends proxying both public and private images through the proxy service because it reduces the total number of endpoints that your users need to add to an allowlist. +For example, if the public image is `registry.k8s.io/metrics-server/metrics-server:v0.7.0`, then the image name should be rewritten to `proxy.replicated.com/anonymous/registry.k8s.io/metrics-server/metrics-server:v0.7.0`. + +This allows the public image to be accessed through the Replicated proxy service at `proxy.replicated.com`. + +:::note +Replicated recommends proxying both public and private images through the proxy service because it reduces the total number of endpoints that your users need to add to an allowlist. +::: #### Example +The following example shows how to configure fields in the HelmChart `values` key that rewrite the registry domain and namespace for a public 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. + ```yaml # kots.io/v1beta2 HelmChart custom resource @@ -148,12 +158,12 @@ spec: # Else, use proxy.replicated.com registry: '{{repl HasLocalRegistry | ternary LocalRegistryHost "proxy.replicated.com" }}' # If the user configured a registry, use the registry namespace provided - # Else, use "anonymous/registry.k8s.io" - repository: '{{repl HasLocalRegistry | ternary LocalRegistryNamespace "anonymous/registry.k8s.io" }}/metrics-server/metrics-server' + # Else, use "anonymous" + repository: '{{repl HasLocalRegistry | ternary LocalRegistryNamespace "anonymous/registry.k8s.io/metrics-server" }}/metrics-server' 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 @@ -219,7 +229,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 From 972fc770cb0d5eec6561ababd1f2e1739e7526ab Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Tue, 10 Sep 2024 11:56:16 -0600 Subject: [PATCH 05/11] 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 d3b14d873a..cee446ca33 100644 --- a/docs/vendor/helm-native-v2-using.md +++ b/docs/vendor/helm-native-v2-using.md @@ -58,11 +58,11 @@ To support installations with the `kots.io/v1beta2` HelmChart custom resource, d ## Rewrite Image Names -During installation and upgrade with KOTS, any application images in your private registry must be accessed through the [Replicated proxy service](private-images-about) at `proxy.replicated.com`. Replicated also recommends that any public application images are accessed through the proxy service to reduce the total number of endpoints that your users are required to add to an allowlist. +During installation and upgrade with KOTS, any application images in your private registry must be accessed through the [Replicated proxy service](private-images-about) at `proxy.replicated.com`. Replicated also recommends that any public images used by your application are accessed through the proxy service to reduce the total number of endpoints that your users are required to add to an allowlist. Additionally, your users can push images to their own registry. This is required for installations in air gap environments. -To ensure that your application images can be discovered, you need to configure the HelmChart custom resource so that image names are rewritten in your Helm chart during deployment. +To ensure that images can be discovered, you need to configure the HelmChart custom resource so that image names are rewritten in your Helm chart values during deployment. 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. @@ -73,11 +73,11 @@ You will use the following KOTS template functions in the HelmChart custom resou 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 example, if the private image is `registry.k8s.io/quay.io/my-org/nginx:v1.0.1`, then the image name should be rewritten to `proxy.replicated.com/proxy/my-app/quay.io/my-org/nginx:v1.0.1`. +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 -The following example shows how to configure the HelmChart `values` key to rewrite the registry hostname and namespace for a private image. +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. @@ -140,7 +140,7 @@ Replicated recommends proxying both public and private images through the proxy #### Example -The following example shows how to configure fields in the HelmChart `values` key that rewrite the registry domain and namespace for a public image. +The following example shows how to configure fields in the KOTS HelmChart `values` key that rewrite the registry domain and namespace for a public 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. From 5de127ced5b5f3c2ae33abf232ab112f4e7a46cf Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Tue, 10 Sep 2024 11:58:58 -0600 Subject: [PATCH 06/11] edits --- docs/vendor/helm-native-v2-using.md | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/docs/vendor/helm-native-v2-using.md b/docs/vendor/helm-native-v2-using.md index cee446ca33..5a3b917708 100644 --- a/docs/vendor/helm-native-v2-using.md +++ b/docs/vendor/helm-native-v2-using.md @@ -131,13 +131,6 @@ spec: For any public images, configure the HelmChart custom resource so that image names are rewritten to `proxy.replicated.com/anonymous/`, where `` is the path to the image in the public registry. For example, if the public image is `registry.k8s.io/metrics-server/metrics-server:v0.7.0`, then the image name should be rewritten to `proxy.replicated.com/anonymous/registry.k8s.io/metrics-server/metrics-server:v0.7.0`. - -This allows the public image to be accessed through the Replicated proxy service at `proxy.replicated.com`. - -:::note -Replicated recommends proxying both public and private images through the proxy service because it reduces the total number of endpoints that your users need to add to an allowlist. -::: - #### Example The following example shows how to configure fields in the KOTS HelmChart `values` key that rewrite the registry domain and namespace for a public image. @@ -170,7 +163,7 @@ The `spec.values.image.registry` and `spec.values.image.repository` fields in th image: registry: registry.k8s.io - repository: registry.k8s.io/metrics-server/metrics-server + repository: metrics-server/metrics-server tag: v0.7.0 ``` From 6138a4b8674f5c727689b8045f7597b01a1b64a3 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Tue, 10 Sep 2024 12:05:36 -0600 Subject: [PATCH 07/11] edits --- docs/vendor/helm-native-v2-using.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/vendor/helm-native-v2-using.md b/docs/vendor/helm-native-v2-using.md index 5a3b917708..0ce03b2116 100644 --- a/docs/vendor/helm-native-v2-using.md +++ b/docs/vendor/helm-native-v2-using.md @@ -52,13 +52,13 @@ To support installations with the `kots.io/v1beta2` HelmChart custom resource, d * 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 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. + 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). ::: * 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). ## Rewrite Image Names -During installation and upgrade with KOTS, any application images in your private registry must be accessed through the [Replicated proxy service](private-images-about) at `proxy.replicated.com`. Replicated also recommends that any public images used by your application are accessed through the proxy service to reduce the total number of endpoints that your users are required to add to an allowlist. +During installation and upgrade with KOTS, any application images in your private registry are accessed through the [Replicated proxy service](private-images-about) at `proxy.replicated.com`. Replicated also recommends that any public images used by your application are accessed through the proxy service to reduce the total number of endpoints that your users are required to add to an allowlist. Additionally, your users can push images to their own registry. This is required for installations in air gap environments. From 43df157ac5a979a58b4a614f08bfb57f8ec792cf Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Tue, 10 Sep 2024 12:10:06 -0600 Subject: [PATCH 08/11] edits --- docs/vendor/helm-native-v2-using.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/vendor/helm-native-v2-using.md b/docs/vendor/helm-native-v2-using.md index 0ce03b2116..991e09c49c 100644 --- a/docs/vendor/helm-native-v2-using.md +++ b/docs/vendor/helm-native-v2-using.md @@ -303,6 +303,10 @@ spec: ## 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). +::: + 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` * `kots.io/app-slug: APP_SLUG`, where `APP_SLUG` is the slug of your Replicated application. From 2d9165f6b6f66333998fd6be0c63dea337f658b9 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Tue, 10 Sep 2024 13:26:17 -0600 Subject: [PATCH 09/11] Update docs/vendor/helm-native-v2-using.md 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 991e09c49c..bf44d818b6 100644 --- a/docs/vendor/helm-native-v2-using.md +++ b/docs/vendor/helm-native-v2-using.md @@ -133,7 +133,7 @@ For any public images, configure the HelmChart custom resource so that image nam For example, if the public image is `registry.k8s.io/metrics-server/metrics-server:v0.7.0`, then the image name should be rewritten to `proxy.replicated.com/anonymous/registry.k8s.io/metrics-server/metrics-server:v0.7.0`. #### Example -The following example shows how to configure fields in the KOTS HelmChart `values` key that rewrite the registry domain and namespace for a public image. +The following example shows how to configure fields in the KOTS HelmChart `values` key to rewrite the registry domain and namespace for a public 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. From dc26ad103e1a16c399874b41599e2230a70b56a4 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Tue, 10 Sep 2024 14:32:33 -0600 Subject: [PATCH 10/11] update public image example --- docs/vendor/helm-native-v2-using.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/docs/vendor/helm-native-v2-using.md b/docs/vendor/helm-native-v2-using.md index bf44d818b6..1abff02e89 100644 --- a/docs/vendor/helm-native-v2-using.md +++ b/docs/vendor/helm-native-v2-using.md @@ -130,7 +130,7 @@ spec: For any public images, configure the HelmChart custom resource so that image names are rewritten to `proxy.replicated.com/anonymous/`, where `` is the path to the image in the public registry. -For example, if the public image is `registry.k8s.io/metrics-server/metrics-server:v0.7.0`, then the image name should be rewritten to `proxy.replicated.com/anonymous/registry.k8s.io/metrics-server/metrics-server:v0.7.0`. +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 example shows how to configure fields in the KOTS HelmChart `values` key to rewrite the registry domain and namespace for a public image. @@ -152,8 +152,8 @@ spec: registry: '{{repl HasLocalRegistry | ternary LocalRegistryHost "proxy.replicated.com" }}' # If the user configured a registry, use the registry namespace provided # Else, use "anonymous" - repository: '{{repl HasLocalRegistry | ternary LocalRegistryNamespace "anonymous/registry.k8s.io/metrics-server" }}/metrics-server' - tag: v1.0.1 + repository: '{{repl HasLocalRegistry | ternary LocalRegistryNamespace "anonymous/ghcr.io/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 above correspond to `image.registry` and `image.repository` fields in the Helm chart `values.yaml` file, as shown below: @@ -162,9 +162,9 @@ The `spec.values.image.registry` and `spec.values.image.repository` fields in th # Helm chart values.yaml file image: - registry: registry.k8s.io - repository: metrics-server/metrics-server - tag: v0.7.0 + 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. @@ -174,8 +174,6 @@ Any templates in the Helm chart that access the `image.registry` and `image.repo ```yaml apiVersion: v1 kind: Pod -metadata: - name: mariadb spec: containers: - name: From 49095cddce1c35b7a40601694413c0810aff3476 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Tue, 10 Sep 2024 14:36:07 -0600 Subject: [PATCH 11/11] simplify intro --- docs/vendor/helm-native-v2-using.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/docs/vendor/helm-native-v2-using.md b/docs/vendor/helm-native-v2-using.md index 1abff02e89..70e22f98f6 100644 --- a/docs/vendor/helm-native-v2-using.md +++ b/docs/vendor/helm-native-v2-using.md @@ -58,11 +58,7 @@ To support installations with the `kots.io/v1beta2` HelmChart custom resource, d ## Rewrite Image Names -During installation and upgrade with KOTS, any application images in your private registry are accessed through the [Replicated proxy service](private-images-about) at `proxy.replicated.com`. Replicated also recommends that any public images used by your application are accessed through the proxy service to reduce the total number of endpoints that your users are required to add to an allowlist. - -Additionally, your users can push images to their own registry. This is required for installations in air gap environments. - -To ensure that images can be discovered, you need to configure the HelmChart custom resource so that image names are rewritten in your Helm chart values during deployment. +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` or in your user's local registry. 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.