Skip to content

Commit f46f001

Browse files
paigecalvertpaigecalvert
committed
wip
1 parent 6f3daa3 commit f46f001

File tree

1 file changed

+37
-64
lines changed

1 file changed

+37
-64
lines changed

‎docs/vendor/helm-native-v2-using.md‎

Lines changed: 37 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -18,74 +18,33 @@ To configure the HelmChart custom resource, do the following:
1818
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).
1919
:::
2020

21-
## Task 1: Rewrite Image Names and Inject the KOTS Pull Secret {#rewrite-image-names}
21+
## Task 1: Rewrite Image Names and Inject the KOTS Image Pull Secret {#rewrite-image-names}
2222

23-
Configure the HelmChart custom resource so that KOTS rewrites the names of images in your Helm values during deployment. Additionally, add the KOTS-generated pull secret for the proxy service. This allows images to be accessed at one of the following locations, depending on where they were pushed:
24-
* The [Replicated proxy registry](private-images-about) (`proxy.replicated.com` or your custom domain)
25-
* A public image registry
26-
* Your customer's local registry
27-
* The built-in registry used in Replicated Embedded Cluster or Replicated kURL installations in air-gapped environments
23+
Rewriting image names and injecting the KOTS pull secret allows your application images to be accessed at one of the following locations, depending on the installation type and where the given image is available:
24+
* The [Replicated proxy registry](private-images-about) at `proxy.replicated.com` or your custom domain. Private images are pulled through the proxy registry in online installations.
25+
* A public image registry. Any public images that your application uses can be access directly from the public image registry in online installations.
26+
* Your customer's local registry. The most common use case for configuring a local image registry is in KOTS existing cluster installations in air-gapped environments.
27+
* The built-in registry that is used in Replicated Embedded Cluster or Replicated kURL installations in air-gapped environments.
2828

29-
To rewrite image names to the location of the image in the proxy registry:
29+
To rewrite image names and inject the KOTS image pull secret:
3030

31-
1. In the HelmChart custom resource, under the `values` key, rewrite image names using the format `<proxy-domain>/proxy/<app-slug>/<image>`, where:
32-
* `<proxy-domain>` is `proxy.replicated.com` or your custom domain. For more information about configuring a custom domain for the proxy registry, see [Using Custom Domains](/vendor/custom-domains-using).
33-
* `<app-slug>` is the unique application slug in the Vendor Portal. For more information, see [Get the Application Slug](/vendor/vendor-portal-manage-app#slug).
34-
* `<image>` is the path to the image in your registry
31+
1. In the HelmChart custom resource, under the `values` key, rewrite _private_ image names using the format `PROXY_DOMAIN/proxy/APP_SLUG/IMAGE`, where:
3532

36-
For example, if the private image is `quay.io/my-org/nginx:v1.0.1` and `images.yourcompany.com` is the custom proxy registry domain, then the image name should be rewritten to `images.yourcompany.com/proxy/my-app-slug/quay.io/my-org/nginx:v1.0.1`.
33+
* `PROXY_DOMAIN` is `proxy.replicated.com` or your custom domain. For more information about configuring a custom domain for the proxy registry, see [Using Custom Domains](/vendor/custom-domains-using).
3734

38-
```yaml
39-
values:
40-
image:
41-
registry: '{{repl LocalRegistryHost }}'
42-
repository: '{{repl LocalRegistryNamespace }}/gitea'
43-
```
35+
* `APP_SLUG` is the unique application slug in the Vendor Portal. For more information, see [Get the Application Slug](/vendor/vendor-portal-manage-app#slug).
4436

45-
1. Under the `optionalValues` key, use the KOTS [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry), [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost), and [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace) template functions to conditionally rewrite private image names.
37+
* `IMAGE` is the path to the image in your registry
4638

47-
```yaml
48-
optionalValues:
49-
- when: 'repl{{ HasLocalRegistry }}'
50-
values:
51-
image:
52-
registry: '{{repl LocalRegistryHost }}'
53-
repository: '{{repl LocalRegistryNamespace }}/gitea'
54-
pullSecrets:
55-
- name: '{{repl ImagePullSecretName }}'
56-
```
57-
58-
1. Under the `optionalValues` key, use the KOTS [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry), [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost), and [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace) template functions to conditionally rewrite public image names.
59-
60-
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.
61-
62-
```yaml
63-
# kots.io/v1beta2 HelmChart custom resource
64-
65-
apiVersion: kots.io/v1beta2
66-
kind: HelmChart
67-
metadata:
68-
name: samplechart
69-
spec:
70-
...
71-
values:
72-
image:
73-
# If a local registry is used, use that registry's hostname
74-
# Else, use the public registry host (ghcr.io)
75-
registry: '{{repl HasLocalRegistry | ternary LocalRegistryHost "ghcr.io" }}'
76-
# If a local registry is used, use the registry namespace provided
77-
# Else, use the path to the image in the public registry
78-
repository: '{{repl HasLocalRegistry | ternary LocalRegistryNamespace "cloudnative-pg" }}/cloudnative-pg'
79-
tag: catalog-1.24.0
80-
```
39+
For example, if the private image is `quay.io/my-org/nginx:v1.0.1` and `images.yourcompany.com` is the custom proxy registry domain, then the image name should be rewritten to `images.yourcompany.com/proxy/your-app-slug/quay.io/my-org/nginx:v1.0.1`.
8140

82-
1. Add the pull secret.
83-
84-
Kubernetes requires a Secret of type `kubernetes.io/dockerconfigjson` to authenticate with a registry and pull a private image. For more information, see [Specifying imagePullSecrets on a Pod](https://kubernetes.io/docs/concepts/containers/images/#specifying-imagepullsecrets-on-a-pod) in the Kubernetes documentation.
41+
1. Add the KOTS-generated pull secret to provide authentication for the proxy registry.
8542

8643
During installation, KOTS creates a `kubernetes.io/dockerconfigjson` type Secret that is based on the customer license. This pull secret grants access to the private image through the Replicated proxy registry or in the Replicated registry. Additionally, if the user configured a local image registry, then the pull secret contains the credentials for the local registry. You must provide the name of this KOTS-generated pull secret in any Pod definitions that reference the private image.
44+
45+
For more information about the `kubernetes.io/dockerconfigjson` type Secret required by Kubernetes to authenticate with a registry and pull a private image, see [Specifying imagePullSecrets on a Pod](https://kubernetes.io/docs/concepts/containers/images/#specifying-imagepullsecrets-on-a-pod) in the Kubernetes documentation.
8746

88-
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.
47+
**Example:**
8948

9049
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:
9150

@@ -99,13 +58,25 @@ To rewrite image names to the location of the image in the proxy registry:
9958
spec:
10059
values:
10160
image:
102-
# Note: Use proxy.replicated.com or your custom domain
103-
registry: '{{repl HasLocalRegistry | ternary LocalRegistryHost "proxy.replicated.com" }}'
104-
repository: '{{repl HasLocalRegistry | ternary LocalRegistryNamespace "proxy/my-app/ecr.us-east-1.amazonaws.com/my-org" }}/api'
61+
registry:
62+
repository:
10563
pullSecrets:
10664
- name: '{{repl ImagePullSecretName }}'
10765
```
10866
67+
1. Configure the `optionalValues` key so that KOTS conditionally rewrites private _and_ public image names only when there is a local image registry configured in the installation environment. You can do this using the KOTS [HasLocalRegistry](/reference/template-functions-config-context#haslocalregistry), [LocalRegistryHost](/reference/template-functions-config-context#localregistryhost), and [LocalRegistryNamespace](/reference/template-functions-config-context#localregistrynamespace) template functions.
68+
69+
**Example:**
70+
71+
```yaml
72+
optionalValues:
73+
- when: 'repl{{ HasLocalRegistry }}'
74+
values:
75+
image:
76+
registry: '{{repl LocalRegistryHost }}'
77+
repository: '{{repl LocalRegistryNamespace }}/gitea'
78+
```
79+
10980
## Task 2: Add Pull Secret for Rate-Limited Docker Hub Images {#docker-secret}
11081

11182
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 `<app-slug>-kotsadm-dockerhub` secret for pulling Docker Hub images and applies the secret to Kubernetes manifests that have images. For more information, see [Avoiding Docker Hub Rate Limits](/enterprise/image-registry-rate-limits).
@@ -151,14 +122,16 @@ spec:
151122

152123
## Task 3: Support the Use of Local Image Registries {#local-registries}
153124

154-
Local image registries are required for KOTS installations in air-gapped environments with no outbound internet connection. Also, users in online environments can optionally use a local registry. For more information about how users configure a local image registry with KOTS, see [Configuring Local Image Registries](/enterprise/image-registry-settings).
125+
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.
126+
127+
To support the use of local registries, configure the `builder` key. For information about how to configure the `builder` key, see [`builder`](/reference/custom-resource-helmchart-v2#builder) in _HelmChart v2_.
155128

156-
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_.
129+
For more information about how users configure a local image registry with KOTS, see [Configuring Local Image Registries](/enterprise/image-registry-settings).
157130

158-
## Task 5: Add Backup Labels for Snapshots (KOTS Existing Cluster and kURL Installations Only) {#add-backup-labels-for-snapshots}
131+
## (KOTS Existing Cluster and kURL Installations Only) Task 4: Add Backup Labels for Snapshots {#add-backup-labels-for-snapshots}
159132

160133
:::note
161-
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).
134+
The Replicated [snapshots](snapshots-overview) feature for backup and restsore is supported only for KOTS existing cluster and kURL installations. Snapshots are not support for installations with Embedded Cluster. For more information about disaster recovery for installations with Embedded Cluster, see [Disaster Recovery for Embedded Cluster](/vendor/embedded-disaster-recovery.mdx).
162135
:::
163136

164137
The snapshots feature requires the following labels on all resources in your Helm chart that you want to be included in the backup:

0 commit comments

Comments
 (0)