From ffcac0677859df92d136336d57b5dbf7ee1c5a70 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Tue, 8 Jul 2025 16:45:35 -0600 Subject: [PATCH 1/6] Edit docs on using the proxy registry --- .../proxy-service/_step-additional-ns.mdx | 1 + .../_step-inject-pull-secret.mdx | 40 +++++ .../_step-rewrite-helm-values.mdx | 30 ++++ docs/vendor/helm-image-registry.mdx | 36 +--- docs/vendor/private-images-kots.mdx | 157 +++++++++++++----- 5 files changed, 185 insertions(+), 79 deletions(-) create mode 100644 docs/partials/proxy-service/_step-additional-ns.mdx create mode 100644 docs/partials/proxy-service/_step-inject-pull-secret.mdx create mode 100644 docs/partials/proxy-service/_step-rewrite-helm-values.mdx diff --git a/docs/partials/proxy-service/_step-additional-ns.mdx b/docs/partials/proxy-service/_step-additional-ns.mdx new file mode 100644 index 0000000000..0dc1cdf578 --- /dev/null +++ b/docs/partials/proxy-service/_step-additional-ns.mdx @@ -0,0 +1 @@ +If you are deploying Pods to namespaces other than the application namespace, add the namespace to the `additionalNamespaces` attribute of the KOTS Application custom resource. This ensures that KOTS can provision the `imagePullSecret` in the namespace to allow the Pod to pull the image. For instructions, see [Define Additional Namespaces](operator-defining-additional-namespaces). \ No newline at end of file diff --git a/docs/partials/proxy-service/_step-inject-pull-secret.mdx b/docs/partials/proxy-service/_step-inject-pull-secret.mdx new file mode 100644 index 0000000000..b9a482e84c --- /dev/null +++ b/docs/partials/proxy-service/_step-inject-pull-secret.mdx @@ -0,0 +1,40 @@ +In the HelmChart v2 custom resource, configure the `values` key to inject the Replicated image pull secret into your Helm values. This provides authentication for the proxy registry. Use the KOTS [ImagePullSecretName](/reference/template-functions-config-context#imagepullsecretname) template function to get the pull secret name. + +
+ What is the Replicated image pull secret? +

During application deployment, KOTS automatically creates an `imagePullSecret` with `type: kubernetes.io/dockerconfigjson` that is based on the customer license. This secret is used to authenticate with the proxy registry and grant proxy access to private images. For information about how Kubernetes uses the `kubernetes.io/dockerconfigjson` Secret type to authenticate to a private image registry, see [Pull an Image from a Private Registry](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/) in the Kubernetes documentation.

+
+ + **Example**: + + ```yaml + # kots.io/v1beta2 HelmChart custom resource + + apiVersion: kots.io/v1beta2 + kind: HelmChart + metadata: + name: samplechart + spec: + values: + image: + # Get the pull secret name with ImagePullSecretName + pullSecrets: + - name: '{{repl ImagePullSecretName }}' + ``` + Ensure that you provide this pull secret in any Pod definitions that reference images to be pulled through the proxy registry. + **Example**: + ```yaml + apiVersion: v1 + kind: Pod + metadata: + name: nginx + spec: + containers: + - name: nginx + image: {{ .Values.image.registry }}/{{ .Values.image.repository }} + # Access the value to provide the KOTS pull secret + {{- with .Values.image.pullSecrets }} + imagePullSecrets: + {{- toYaml . | nindent 2 }} + {{- end }} + ``` \ No newline at end of file diff --git a/docs/partials/proxy-service/_step-rewrite-helm-values.mdx b/docs/partials/proxy-service/_step-rewrite-helm-values.mdx new file mode 100644 index 0000000000..a123ee0e19 --- /dev/null +++ b/docs/partials/proxy-service/_step-rewrite-helm-values.mdx @@ -0,0 +1,30 @@ +For each image reference in your Helm chart values file, set the image repository URL to the location of the image on the proxy registry. This is either `proxy.replicated.com` or your custom domain. + + The proxy registry URL has the following format: `DOMAIN/proxy/APP_SLUG/EXTERNAL_REGISTRY_IMAGE_URL` + + Where: + * `DOMAIN` is either `proxy.replicated.com` or your custom domain. + * `APP_SLUG` is the unique slug of your application. + * `EXTERNAL_REGISTRY_IMAGE_URL` is the path to the private image on your external registry. + + **Example:** + + ```yaml + # values.yaml + api: + image: + # proxy.replicated.com or your custom domain + registry: proxy.replicated.com + repository: proxy/your-app/ghcr.io/cloudnative-pg/cloudnative-pg + tag: catalog-1.24.0 + ``` + Ensure that any references to the image in your Helm chart access the field from your values file. + **Example**: + ```yaml + apiVersion: v1 + kind: Pod + spec: + containers: + - name: api + # Access the registry, repository, and tag fields from the values file + image: {{ .Values.image.api.registry }}/{{ .Values.image.api.repository }}:{{ .Values.image.api.tag }} \ No newline at end of file diff --git a/docs/vendor/helm-image-registry.mdx b/docs/vendor/helm-image-registry.mdx index a81ba65a5b..5993bbd782 100644 --- a/docs/vendor/helm-image-registry.mdx +++ b/docs/vendor/helm-image-registry.mdx @@ -1,5 +1,6 @@ import StepCreds from "../partials/proxy-service/_step-creds.mdx" import StepCustomDomain from "../partials/proxy-service/_step-custom-domain.mdx" +import RewriteHelmValues from "../partials/proxy-service/_step-rewrite-helm-values.mdx" # Use the Proxy Registry with Helm Installations @@ -21,40 +22,7 @@ To use the Replicated proxy registry for applications installed with Helm: 1. -1. In your Helm chart values file, set your image repository URL to the location of the image on the proxy registry. If you added a custom domain, use your custom domain. Otherwise, use `proxy.replicated.com`. - - The proxy registry URL has the following format: `DOMAIN/proxy/APP_SLUG/EXTERNAL_REGISTRY_IMAGE_URL` - - Where: - * `DOMAIN` is either `proxy.replicated.com` or your custom domain. - * `APP_SLUG` is the unique slug of your application. - * `EXTERNAL_REGISTRY_IMAGE_URL` is the path to the private image on your external registry. - - **Example:** - - ```yaml - # values.yaml - api: - image: - # proxy.replicated.com or your custom domain - registry: proxy.replicated.com - repository: proxy/your-app/ghcr.io/cloudnative-pg/cloudnative-pg - tag: catalog-1.24.0 - ``` - -1. Ensure that any references to the image in your Helm chart access the field from your values file. - - **Example**: - - ```yaml - apiVersion: v1 - kind: Pod - spec: - containers: - - name: api - # Access the registry, repository, and tag fields from the values file - image: {{ .Values.images.api.registry }}/{{ .Values.images.api.repository }}:{{ .Values.images.api.tag }} - ``` +1. 1. In your Helm chart templates, create a Kubernetes Secret to evaluate if the `global.replicated.dockerconfigjson` value is set and then write the rendered value into a Secret on the cluster, as shown below. diff --git a/docs/vendor/private-images-kots.mdx b/docs/vendor/private-images-kots.mdx index 9527486115..f1ed54395a 100644 --- a/docs/vendor/private-images-kots.mdx +++ b/docs/vendor/private-images-kots.mdx @@ -1,75 +1,142 @@ import Deprecated from "../partials/helm/_replicated-deprecated.mdx" import StepCreds from "../partials/proxy-service/_step-creds.mdx" import StepCustomDomain from "../partials/proxy-service/_step-custom-domain.mdx" +import RewriteHelmValues from "../partials/proxy-service/_step-rewrite-helm-values.mdx" +import AdditionalNs from "../partials/proxy-service/_step-additional-ns.mdx" +import InjectPullSecret from "../partials/proxy-service/_step-inject-pull-secret.mdx" -# Use the Proxy Registry with KOTS Installations +# Use the Proxy Registry with Replicated Installers -This topic describes how to use the Replicated proxy registry with applications deployed with Replicated KOTS. +This topic describes how to use the Replicated proxy registry for applications deployed with Replicated installers (Embedded Cluster, KOTS existing cluster, or kURL). -## Overview +## Configure Your Application to Use the Proxy Registry -Replicated KOTS automatically creates the required image pull secret for accessing the Replicated proxy registry during application deployment. When possible, KOTS also automatically rewrites image names in the application manifests to the location of the image at `proxy.replicated.com` or your custom domain. +:::note +These steps assume that you package your application with Helm and that you install with the KOTS HelmChart v2 custom resource. -### Image Pull Secret +If you are installing with the HelmChart v1 custom resource, or if your application is not packaged with Helm, there are different steps for configuring your application to use the proxy registry. See [Other Scenarios](#other-scenarios) below. +::: -During application deployment, KOTS automatically creates an `imagePullSecret` with `type: kubernetes.io/dockerconfigjson` that is based on the customer license. This secret is used to authenticate with the proxy registry and grant proxy access to private images. +To configure your application to use the proxy registry: -For information about how Kubernetes uses the `kubernetes.io/dockerconfigjson` Secret type to authenticate to a private image registry, see [Pull an Image from a Private Registry](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/) in the Kubernetes documentation. +1. -### Image Location Patching (Standard Manifests and HelmChart v1) +1. -For applications packaged with standard Kubernetes manifests (or Helm charts deployed with the [HelmChart v1](/reference/custom-resource-helmchart) custom resource), KOTS automatically patches image names to the location of the image at at `proxy.replicated.com` or your custom domain during deployment. If KOTS receives a 401 response when attempting to load image manifests using the image reference from the PodSpec, it assumes that this is a private image that must be proxied through the proxy registry. +1. -KOTS uses Kustomize to patch the `midstream/kustomization.yaml` file to change the image name during deployment to reference the proxy registry. For example, a PodSpec for a Deployment references a private image hosted at `quay.io/my-org/api:v1.0.1`: +1. -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: example -spec: - template: - spec: - containers: - - name: api - image: quay.io/my-org/api:v1.0.1 -``` +1. Repeat steps 3 and 4 for each Helm chart used by your application. + +1. + +1. Create a new release with your changes. Promote the release to a development channel. See [Managing Releases with Vendor Portal](releases-creating-releases). + +1. Install in a development environment to test your changes. -When this application is deployed, KOTS detects that it cannot access -the image at quay.io. So, it creates a patch in the `midstream/kustomization.yaml` -file that changes the image name in all manifest files for the application. This causes the container runtime in the cluster to use the proxy registry to pull the images, using the license information provided to KOTS for authentication. +## Other Scenarios -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -bases: -- ../../base -images: -- name: quay.io/my-org/api:v1.0.1 - newName: proxy.replicated.com/proxy/my-kots-app/quay.io/my-org/api -``` +If you are installing with the HelmChart v1 custom resource, or if your application is not packaged with Helm, there are different steps for configuring your application to use the proxy registry. -## Enable the Proxy Registry +### HelmChart v1 or Standard Manifests -This section describes how to enable the proxy registry for applications deployed with KOTS, including how to ensure that image names are rewritten and that the required image pull secret is provided. +:::note + +::: -To enable the proxy registry: +To use the proxy registry with HelmChart v1 or applications packaged with standard manifests: 1. 1. -1. Rewrite images names to the location of the image at `proxy.replicated.com` or your custom domain. Also, ensure that the correct image pull secret is provided for all private images. The steps required to configure image names and add the image pull secret vary depending on your application type: +1. + +1. For standard manifest-based applications or Helm charts deployed with the [HelmChart v1](/reference/custom-resource-helmchart) custom resource, KOTS automatically rewrites image names and injects image pull secrets during deployment for these application types. No additional configuration is required to rewrite image names. + +
+ How does KOTS patch image names? + + For applications packaged with standard Kubernetes manifests (or Helm charts deployed with the [HelmChart v1](/reference/custom-resource-helmchart) custom resource), KOTS automatically patches image names to the location of the image at at `proxy.replicated.com` or your custom domain during deployment. If KOTS receives a 401 response when attempting to load image manifests using the image reference from the PodSpec, it assumes that this is a private image that must be proxied through the proxy registry. + + KOTS uses Kustomize to patch the `midstream/kustomization.yaml` file to change the image name during deployment to reference the proxy registry. For example, a PodSpec for a Deployment references a private image hosted at `quay.io/my-org/api:v1.0.1`: + + ```yaml + apiVersion: apps/v1 + kind: Deployment + metadata: + name: example + spec: + template: + spec: + containers: + - name: api + image: quay.io/my-org/api:v1.0.1 + ``` - * **HelmChart v2**: For Helm charts deployed with the[ HelmChart v2](/reference/custom-resource-helmchart-v2) custom resource, configure the HelmChart v2 custom resource to dynamically update image names in your Helm chart and to inject the image pull secret that is automatically created by KOTS. For instructions, see [Configure the HelmChart Custom Resource v2](/vendor/helm-native-v2-using). + When this application is deployed, KOTS detects that it cannot access + the image at quay.io. So, it creates a patch in the `midstream/kustomization.yaml` + file that changes the image name in all manifest files for the application. This causes the container runtime in the cluster to use the proxy registry to pull the images, using the license information provided to KOTS for authentication. - * **Standard Manifests or HelmChart v1**: For standard manifest-based applications or Helm charts deployed with the [HelmChart v1](/reference/custom-resource-helmchart) custom resource, no additional configuration is required. KOTS automatically rewrites image names and injects image pull secrets during deployment for these application types. + ```yaml + apiVersion: kustomize.config.k8s.io/v1beta1 + bases: + - ../../base + images: + - name: quay.io/my-org/api:v1.0.1 + newName: proxy.replicated.com/proxy/my-kots-app/quay.io/my-org/api + ``` +
- :::note - - ::: +1. Create a new release with your changes. Promote the release to a development channel. See [Managing Releases with Vendor Portal](releases-creating-releases). - * **Kubernetes Operators**: For applications packaged with Kubernetes Operators, KOTS cannot modify pods that are created at runtime by the Operator. To support the use of private images in all environments, the Operator code should use KOTS functionality to determine the image name and image pull secrets for all pods when they are created. For instructions, see [Reference Images](/vendor/operator-referencing-images) in the _Packaging Kubernetes Operators_ section. +1. Install in a development environment to test your changes. -1. If you are deploying Pods to namespaces other than the application namespace, add the namespace to the `additionalNamespaces` attribute of the KOTS Application custom resource. This ensures that KOTS can provision the `imagePullSecret` in the namespace to allow the Pod to pull the image. For instructions, see [Define Additional Namespaces](operator-defining-additional-namespaces). +### Kubernetes Operators -1. (Optional) Add a custom domain for the proxy registry instead of `proxy.replicated.com`. See [Use Custom Domains](custom-domains-using). \ No newline at end of file +To use the proxy registry with applications packaged as Kubernetes Operators: + +1. + +1. + +1. + +1. For standard manifest-based applications or Helm charts deployed with the [HelmChart v1](/reference/custom-resource-helmchart) custom resource, KOTS automatically rewrites image names and injects image pull secrets during deployment for these application types. No additional configuration is required to rewrite image names. + +
+ How does KOTS patch image names? + + For applications packaged with standard Kubernetes manifests (or Helm charts deployed with the [HelmChart v1](/reference/custom-resource-helmchart) custom resource), KOTS automatically patches image names to the location of the image at at `proxy.replicated.com` or your custom domain during deployment. If KOTS receives a 401 response when attempting to load image manifests using the image reference from the PodSpec, it assumes that this is a private image that must be proxied through the proxy registry. + + KOTS uses Kustomize to patch the `midstream/kustomization.yaml` file to change the image name during deployment to reference the proxy registry. For example, a PodSpec for a Deployment references a private image hosted at `quay.io/my-org/api:v1.0.1`: + + ```yaml + apiVersion: apps/v1 + kind: Deployment + metadata: + name: example + spec: + template: + spec: + containers: + - name: api + image: quay.io/my-org/api:v1.0.1 + ``` + + When this application is deployed, KOTS detects that it cannot access + the image at quay.io. So, it creates a patch in the `midstream/kustomization.yaml` + file that changes the image name in all manifest files for the application. This causes the container runtime in the cluster to use the proxy registry to pull the images, using the license information provided to KOTS for authentication. + + ```yaml + apiVersion: kustomize.config.k8s.io/v1beta1 + bases: + - ../../base + images: + - name: quay.io/my-org/api:v1.0.1 + newName: proxy.replicated.com/proxy/my-kots-app/quay.io/my-org/api + ``` +
+ +1. For applications packaged with Kubernetes Operators, KOTS cannot modify pods that are created at runtime by the Operator. To support the use of private images in all environments, the Operator code should use KOTS functionality to determine the image name and image pull secrets for all pods when they are created. For instructions, see [Reference Images](/vendor/operator-referencing-images) in the _Packaging Kubernetes Operators_ section. \ No newline at end of file From e7753eb55caa4f753f25fecd513b5f64f5b88108 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Wed, 9 Jul 2025 12:52:48 -0600 Subject: [PATCH 2/6] edits --- docs/vendor/private-images-kots.mdx | 113 ++++++++++------------------ 1 file changed, 40 insertions(+), 73 deletions(-) diff --git a/docs/vendor/private-images-kots.mdx b/docs/vendor/private-images-kots.mdx index f1ed54395a..5571fb5ad4 100644 --- a/docs/vendor/private-images-kots.mdx +++ b/docs/vendor/private-images-kots.mdx @@ -11,11 +11,9 @@ This topic describes how to use the Replicated proxy registry for applications d ## Configure Your Application to Use the Proxy Registry -:::note -These steps assume that you package your application with Helm and that you install with the KOTS HelmChart v2 custom resource. +These steps assume that you package your application with Helm and that you install with the KOTS [HelmChart v2](/reference/custom-resource-helmchart-v2) custom resource. -If you are installing with the HelmChart v1 custom resource, or if your application is not packaged with Helm, there are different steps for configuring your application to use the proxy registry. See [Other Scenarios](#other-scenarios) below. -::: +If you are installing with the HelmChart v1 custom resource, or if your application is not packaged with Helm, there are different steps for configuring your application to use the proxy registry. See [Configure Other Application Types](#other-scenarios) below. To configure your application to use the proxy registry: @@ -35,7 +33,7 @@ To configure your application to use the proxy registry: 1. Install in a development environment to test your changes. -## Other Scenarios +## Configure Other Application Types {#other} If you are installing with the HelmChart v1 custom resource, or if your application is not packaged with Helm, there are different steps for configuring your application to use the proxy registry. @@ -53,45 +51,46 @@ To use the proxy registry with HelmChart v1 or applications packaged with standa 1. -1. For standard manifest-based applications or Helm charts deployed with the [HelmChart v1](/reference/custom-resource-helmchart) custom resource, KOTS automatically rewrites image names and injects image pull secrets during deployment for these application types. No additional configuration is required to rewrite image names. +1. Create a new release with your changes. Promote the release to a development channel. See [Managing Releases with Vendor Portal](releases-creating-releases). -
- How does KOTS patch image names? +1. Install in a development environment to test your changes. - For applications packaged with standard Kubernetes manifests (or Helm charts deployed with the [HelmChart v1](/reference/custom-resource-helmchart) custom resource), KOTS automatically patches image names to the location of the image at at `proxy.replicated.com` or your custom domain during deployment. If KOTS receives a 401 response when attempting to load image manifests using the image reference from the PodSpec, it assumes that this is a private image that must be proxied through the proxy registry. +For applications packed with Kubernetes manifests and for Helm charts deployed with the [HelmChart v1](/reference/custom-resource-helmchart) custom resource, KOTS automatically rewrites image names and injects image pull secrets during deployment for these application types. No additional configuration is required to rewrite image names. - KOTS uses Kustomize to patch the `midstream/kustomization.yaml` file to change the image name during deployment to reference the proxy registry. For example, a PodSpec for a Deployment references a private image hosted at `quay.io/my-org/api:v1.0.1`: +
- ```yaml - apiVersion: apps/v1 - kind: Deployment - metadata: - name: example - spec: - template: - spec: - containers: - - name: api - image: quay.io/my-org/api:v1.0.1 - ``` - - When this application is deployed, KOTS detects that it cannot access - the image at quay.io. So, it creates a patch in the `midstream/kustomization.yaml` - file that changes the image name in all manifest files for the application. This causes the container runtime in the cluster to use the proxy registry to pull the images, using the license information provided to KOTS for authentication. - - ```yaml - apiVersion: kustomize.config.k8s.io/v1beta1 - bases: - - ../../base - images: - - name: quay.io/my-org/api:v1.0.1 - newName: proxy.replicated.com/proxy/my-kots-app/quay.io/my-org/api - ``` -
+How does KOTS patch image names? -1. Create a new release with your changes. Promote the release to a development channel. See [Managing Releases with Vendor Portal](releases-creating-releases). +KOTS automatically patches image names to the location of the image at at `proxy.replicated.com` or your custom domain during deployment. If KOTS receives a 401 response when attempting to load image manifests using the image reference from the PodSpec, it assumes that this is a private image that must be proxied through the proxy registry. -1. Install in a development environment to test your changes. +KOTS uses Kustomize to patch the `midstream/kustomization.yaml` file to change the image name during deployment to reference the proxy registry. For example, a PodSpec for a Deployment references a private image hosted at `quay.io/my-org/api:v1.0.1`: + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: example +spec: + template: + spec: + containers: + - name: api + image: quay.io/my-org/api:v1.0.1 +``` + +When this application is deployed, KOTS detects that it cannot access +the image at quay.io. So, it creates a patch in the `midstream/kustomization.yaml` +file that changes the image name in all manifest files for the application. This causes the container runtime in the cluster to use the proxy registry to pull the images, using the license information provided to KOTS for authentication. + +```yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +bases: +- ../../base +images: +- name: quay.io/my-org/api:v1.0.1 + newName: proxy.replicated.com/proxy/my-kots-app/quay.io/my-org/api +``` +
### Kubernetes Operators @@ -103,40 +102,8 @@ To use the proxy registry with applications packaged as Kubernetes Operators: 1. -1. For standard manifest-based applications or Helm charts deployed with the [HelmChart v1](/reference/custom-resource-helmchart) custom resource, KOTS automatically rewrites image names and injects image pull secrets during deployment for these application types. No additional configuration is required to rewrite image names. - -
- How does KOTS patch image names? +1. For applications packaged with Kubernetes Operators, KOTS cannot modify pods that are created at runtime by the Operator. To support the use of private images in all environments, the Operator code should use KOTS functionality to determine the image name and image pull secrets for all pods when they are created. For instructions, see [Reference Images](/vendor/operator-referencing-images) in the _Packaging Kubernetes Operators_ section. - For applications packaged with standard Kubernetes manifests (or Helm charts deployed with the [HelmChart v1](/reference/custom-resource-helmchart) custom resource), KOTS automatically patches image names to the location of the image at at `proxy.replicated.com` or your custom domain during deployment. If KOTS receives a 401 response when attempting to load image manifests using the image reference from the PodSpec, it assumes that this is a private image that must be proxied through the proxy registry. - - KOTS uses Kustomize to patch the `midstream/kustomization.yaml` file to change the image name during deployment to reference the proxy registry. For example, a PodSpec for a Deployment references a private image hosted at `quay.io/my-org/api:v1.0.1`: +1. Create a new release with your changes. Promote the release to a development channel. See [Managing Releases with Vendor Portal](releases-creating-releases). - ```yaml - apiVersion: apps/v1 - kind: Deployment - metadata: - name: example - spec: - template: - spec: - containers: - - name: api - image: quay.io/my-org/api:v1.0.1 - ``` - - When this application is deployed, KOTS detects that it cannot access - the image at quay.io. So, it creates a patch in the `midstream/kustomization.yaml` - file that changes the image name in all manifest files for the application. This causes the container runtime in the cluster to use the proxy registry to pull the images, using the license information provided to KOTS for authentication. - - ```yaml - apiVersion: kustomize.config.k8s.io/v1beta1 - bases: - - ../../base - images: - - name: quay.io/my-org/api:v1.0.1 - newName: proxy.replicated.com/proxy/my-kots-app/quay.io/my-org/api - ``` -
- -1. For applications packaged with Kubernetes Operators, KOTS cannot modify pods that are created at runtime by the Operator. To support the use of private images in all environments, the Operator code should use KOTS functionality to determine the image name and image pull secrets for all pods when they are created. For instructions, see [Reference Images](/vendor/operator-referencing-images) in the _Packaging Kubernetes Operators_ section. \ No newline at end of file +1. Install in a development environment to test your changes. \ No newline at end of file From fcf7c19e44255059e1f6610a9067e808c65a308a Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Wed, 9 Jul 2025 13:30:27 -0600 Subject: [PATCH 3/6] edits --- docs/vendor/helm-image-registry.mdx | 21 ++++++++++----------- docs/vendor/private-images-kots.mdx | 4 ++-- 2 files changed, 12 insertions(+), 13 deletions(-) diff --git a/docs/vendor/helm-image-registry.mdx b/docs/vendor/helm-image-registry.mdx index 5993bbd782..7b8f65a9c5 100644 --- a/docs/vendor/helm-image-registry.mdx +++ b/docs/vendor/helm-image-registry.mdx @@ -4,19 +4,21 @@ import RewriteHelmValues from "../partials/proxy-service/_step-rewrite-helm-valu # Use the Proxy Registry with Helm Installations -This topic describes how to use the Replicated proxy registry to proxy images for installations with the Helm CLI. For more information about the proxy registry, see [About the Replicated Proxy Registry](private-images-about). +This topic describes how to configure your application to use the Replicated proxy registry with Helm installations. For more information about the proxy registry, see [About the Replicated Proxy Registry](private-images-about). For more information about installing applications distributed with Replicated using Helm, see [About Helm Installations with Replicated](/vendor/helm-install-overview). ## Overview -With the Replicated proxy registry, each customer's unique license can grant proxy access to images in an external private registry. +During Helm installations with Replicated, after customers provide their unique license ID, a `global.replicated.dockerconfigjson` field that contains a base64 encoded Docker configuration file is automatically injected in the Helm chart values. -During Helm installations, after customers provide their license ID, a `global.replicated.dockerconfigjson` field that contains a base64 encoded Docker configuration file is automatically injected in the Helm chart values. You can use this `global.replicated.dockerconfigjson` field to create the pull secret required to authenticate with the proxy registry, allowing you to use the proxy registry for images in your Helm charts. +You can use this `global.replicated.dockerconfigjson` field to create the pull secret required to authenticate with the proxy registry. For more information about how Kubernetes uses the `kubernetes.io/dockerconfigjson` Secret type to provide authentication for a private registry, see [Pull an Image from a Private Registry](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/) in the Kubernetes documentation. -Additionally, if you include the Replicated SDK as a dependency in your Helm chart, the image used by the Replicated SDK is automatically proxied through the proxy registry. +:::note +For Helm charts that include the Replicated SDK as a dependency, the image used by the Replicated SDK is automatically proxied through the proxy registry. No additional configuration is required. For more information, see [About the Replicated SDK](/vendor/replicated-sdk-overview). +::: -## Pull Private Images Through the Proxy Registry in Helm Installations +## Configure Your Application to Use the Proxy Registry -To use the Replicated proxy registry for applications installed with Helm: +To configure your application to use the proxy registry with Helm installations: 1. @@ -24,9 +26,7 @@ To use the Replicated proxy registry for applications installed with Helm: 1. -1. In your Helm chart templates, create a Kubernetes Secret to evaluate if the `global.replicated.dockerconfigjson` value is set and then write the rendered value into a Secret on the cluster, as shown below. - - This Secret is used to authenticate with the proxy registry. For information about how Kubernetes uses the `kubernetes.io/dockerconfigjson` Secret type to provide authentication for a private registry, see [Pull an Image from a Private Registry](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/) in the Kubernetes documentation. +1. In your Helm chart templates, add a YAML file that evaluates if the `global.replicated.dockerconfigjson` value is set, and then writes the rendered value into a Secret on the cluster, as shown below. :::note Do not use `replicated` for the name of the image pull secret because the Replicated SDK automatically creates a Secret named `replicated`. Using the same name causes an error. @@ -47,8 +47,7 @@ To use the Replicated proxy registry for applications installed with Helm: {{ end }} ``` - -1. Add the image pull secret that you created to any manifests that reference the image: +1. Add the image pull secret that you created to any manifests that reference the image. **Example:** diff --git a/docs/vendor/private-images-kots.mdx b/docs/vendor/private-images-kots.mdx index 5571fb5ad4..e39f059b2f 100644 --- a/docs/vendor/private-images-kots.mdx +++ b/docs/vendor/private-images-kots.mdx @@ -7,7 +7,7 @@ import InjectPullSecret from "../partials/proxy-service/_step-inject-pull-secret # Use the Proxy Registry with Replicated Installers -This topic describes how to use the Replicated proxy registry for applications deployed with Replicated installers (Embedded Cluster, KOTS existing cluster, or kURL). +This topic describes how to use the Replicated proxy registry for applications deployed with Replicated installers (Embedded Cluster, KOTS existing cluster, or kURL). For more information about the proxy registry, see [About the Replicated Proxy Registry](private-images-about). ## Configure Your Application to Use the Proxy Registry @@ -15,7 +15,7 @@ These steps assume that you package your application with Helm and that you inst If you are installing with the HelmChart v1 custom resource, or if your application is not packaged with Helm, there are different steps for configuring your application to use the proxy registry. See [Configure Other Application Types](#other-scenarios) below. -To configure your application to use the proxy registry: +To configure your application to use the proxy registry for installations with a Replicated installer: 1. From 5e6b5c44d3104a94d178580a8eb01e90f72a77d0 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Wed, 9 Jul 2025 13:38:56 -0600 Subject: [PATCH 4/6] undo extra line in partial --- docs/partials/proxy-service/_step-rewrite-helm-values.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/partials/proxy-service/_step-rewrite-helm-values.mdx b/docs/partials/proxy-service/_step-rewrite-helm-values.mdx index 66a30713ce..8a892e926f 100644 --- a/docs/partials/proxy-service/_step-rewrite-helm-values.mdx +++ b/docs/partials/proxy-service/_step-rewrite-helm-values.mdx @@ -6,7 +6,7 @@ For each image reference in your Helm chart values file, set the image repositor * `DOMAIN` is either `proxy.replicated.com` or your custom domain. * `APP_SLUG` is the unique slug of your application. * `EXTERNAL_REGISTRY_IMAGE_URL` is the path to the private image on your external registry. - + **Example:** ```yaml From 8bdc1afa3db2d50083155a8e60fdbb7ae01fbbd4 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Wed, 9 Jul 2025 18:04:02 -0600 Subject: [PATCH 5/6] edit anchor link --- docs/vendor/private-images-kots.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/vendor/private-images-kots.mdx b/docs/vendor/private-images-kots.mdx index e39f059b2f..93d3351f8f 100644 --- a/docs/vendor/private-images-kots.mdx +++ b/docs/vendor/private-images-kots.mdx @@ -13,7 +13,7 @@ This topic describes how to use the Replicated proxy registry for applications d These steps assume that you package your application with Helm and that you install with the KOTS [HelmChart v2](/reference/custom-resource-helmchart-v2) custom resource. -If you are installing with the HelmChart v1 custom resource, or if your application is not packaged with Helm, there are different steps for configuring your application to use the proxy registry. See [Configure Other Application Types](#other-scenarios) below. +If you are installing with the HelmChart v1 custom resource, or if your application is not packaged with Helm, there are different steps for configuring your application to use the proxy registry. See [Configure Other Application Types](#other) below. To configure your application to use the proxy registry for installations with a Replicated installer: From 0755c9f8f05de4f0ad7c03f851385f918ac0a141 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Wed, 9 Jul 2025 18:08:48 -0600 Subject: [PATCH 6/6] fix yaml --- docs/vendor/private-images-kots.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/vendor/private-images-kots.mdx b/docs/vendor/private-images-kots.mdx index 93d3351f8f..18acd4a53e 100644 --- a/docs/vendor/private-images-kots.mdx +++ b/docs/vendor/private-images-kots.mdx @@ -69,13 +69,13 @@ KOTS uses Kustomize to patch the `midstream/kustomization.yaml` file to change t apiVersion: apps/v1 kind: Deployment metadata: - name: example + name: example spec: - template: + template: spec: - containers: + containers: - name: api - image: quay.io/my-org/api:v1.0.1 + image: quay.io/my-org/api:v1.0.1 ``` When this application is deployed, KOTS detects that it cannot access @@ -88,7 +88,7 @@ bases: - ../../base images: - name: quay.io/my-org/api:v1.0.1 - newName: proxy.replicated.com/proxy/my-kots-app/quay.io/my-org/api + newName: proxy.replicated.com/proxy/my-kots-app/quay.io/my-org/api ```