From 26f935c36177c4493b5e922ceca12bdbadf3fb6f Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Thu, 27 Mar 2025 10:13:54 -0600 Subject: [PATCH 1/4] Update steps for using the proxy registry in Helm installs --- docs/partials/proxy-service/_step-creds.mdx | 4 +- .../proxy-service/_step-custom-domain.mdx | 2 +- docs/vendor/helm-image-registry.mdx | 140 +++++++++--------- 3 files changed, 73 insertions(+), 73 deletions(-) diff --git a/docs/partials/proxy-service/_step-creds.mdx b/docs/partials/proxy-service/_step-creds.mdx index 096d978db8..5cf8685440 100644 --- a/docs/partials/proxy-service/_step-creds.mdx +++ b/docs/partials/proxy-service/_step-creds.mdx @@ -1 +1,3 @@ -Provide read-only credentials for the external private registry in your Replicated account. This allows Replicated to access the images through the proxy registry. See [Add Credentials for an External Registry](packaging-private-images#add-credentials-for-an-external-registry) in _Connecting to an External Registry_. \ No newline at end of file +In the Vendor Portal, go to **Images > Add external registry** and provide read-only credentials for your registry. This allows Replicated to access the images through the proxy registry. See [Add Credentials for an External Registry](packaging-private-images#add-credentials-for-an-external-registry) in _Connecting to an External Registry_. + +Link a new registry in the Vendor Portal \ No newline at end of file diff --git a/docs/partials/proxy-service/_step-custom-domain.mdx b/docs/partials/proxy-service/_step-custom-domain.mdx index a903aae747..b4e323ac7a 100644 --- a/docs/partials/proxy-service/_step-custom-domain.mdx +++ b/docs/partials/proxy-service/_step-custom-domain.mdx @@ -1 +1 @@ -(Optional) Add a custom domain for the proxy registry instead of `proxy.replicated.com`. See [Using Custom Domains](custom-domains-using). \ No newline at end of file +(Recommended) Go to **Custom Domains > Add custom domain** and add a custom domain for the proxy registry. See [Using Custom Domains](custom-domains-using). \ No newline at end of file diff --git a/docs/vendor/helm-image-registry.mdx b/docs/vendor/helm-image-registry.mdx index 81980775e0..816b10c223 100644 --- a/docs/vendor/helm-image-registry.mdx +++ b/docs/vendor/helm-image-registry.mdx @@ -7,56 +7,52 @@ This topic describes how to use the Replicated proxy registry to proxy images fo ## Overview -With the Replicated proxy registry, each customer's unique license can grant proxy access to images in an external private registry. To enable the proxy registry for Helm installations, you must create a Secret with `type: kubernetes.io/dockerconfigjson` to authenticate with the proxy registry. +With the Replicated proxy registry, each customer's unique license can grant proxy access to images in an external private registry. -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 required pull secret. +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. -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. +## Pull Private Images Through the Proxy Registry in Helm Installations -## Enable the Proxy Registry - -This section describes how to enable the proxy registry for applications deployed with Helm, including how to use the `global.replicated.dockerconfigjson` field that is injected during application deployment to create the required pull secret. - -To enable the proxy registry: +To use the Replicated proxy registry for applications installed with Helm: 1. 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: +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`. - ```yaml - # /templates/replicated-pull-secret.yaml + 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. - {{ if .Values.global.replicated.dockerconfigjson }} - apiVersion: v1 - kind: Secret - metadata: - name: replicated-pull-secret - type: kubernetes.io/dockerconfigjson - data: - .dockerconfigjson: {{ .Values.global.replicated.dockerconfigjson }} - {{ end }} - ``` + **Example with custom domain:** - :::note - If you use the Replicated SDK, do not use `replicated` for the name of the image pull secret because the SDK automatically creates a Secret named `replicated`. Using the same name causes an error. - ::: + ```yaml + # values.yaml + images: + your-app: + apiImageRepository: images.yourcompany.com/proxy/your-app-slug/ghcr.io/org-name/api + apiImageTag: v1.0.1 + ``` + + **Example with proxy.replicated.com:** -1. Ensure that you have a field in your Helm chart values file for your image repository URL, and that any references to the image in your Helm chart access the field from your values file. + ```yaml + # values.yaml + images: + your-app: + registry: proxy.replicated.com + repository: proxy/your-app-slug/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 - # values.yaml - ... - dockerconfigjson: '{{ .Values.global.replicated.dockerconfigjson }}' - images: - myapp: - # Add image URL in the values file - apiImageRepository: quay.io/my-org/api - apiImageTag: v1.0.1 - ``` ```yaml # /templates/deployment.yaml @@ -69,32 +65,59 @@ To enable the proxy registry: spec: containers: - name: api - # Access the apiImageRepository field from the values file - image: {{ .Values.images.myapp.apiImageRepository }}:{{ .Values.images.myapp.apiImageTag }} + # Access the repository and tag fields from the values file + image: {{ .Values.images.your-app.apiImageRepository }}:{{ .Values.images.your-app.apiImageTag }} ``` + **Example**: -1. In your Helm chart templates, add the image pull secret that you created to any manifests that reference the private image: + ```yaml + apiVersion: v1 + kind: Pod + spec: + containers: + - name: + # Access the registry, repository, and tag fields from the values file + image: {{ .Values.images.your-app.registry }}/{{ .Values.images.your-app.repository }}:{{ .Values.images.your-app.tag }} + ``` + +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. + + :::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. + ::: ```yaml - # /templates/example.yaml - ... + # /templates/replicated-pull-secret.yaml + {{ if .Values.global.replicated.dockerconfigjson }} - imagePullSecrets: - - name: replicated-pull-secret + apiVersion: v1 + kind: Secret + metadata: + # Note: Do not use "replicated" for the name of the pull secret + name: replicated-pull-secret + type: kubernetes.io/dockerconfigjson + data: + .dockerconfigjson: {{ .Values.global.replicated.dockerconfigjson }} {{ end }} ``` + + +1. Add the image pull secret that you created to any manifests that reference the image: **Example:** ```yaml # /templates/deployment.yaml - ... - image: "{{ .Values.images.myapp.apiImageRepository }}:{{ .Values.images.myapp.apiImageTag }}" + + image: "{{ .Values.images.your-app.apiImageRepository }}:{{ .Values.images.your-app.apiImageTag }}" + # Add the pull secret {{ if .Values.global.replicated.dockerconfigjson }} imagePullSecrets: - name: replicated-pull-secret {{ end }} - name: myapp + name: your-app ports: - containerPort: 3000 name: http @@ -102,32 +125,7 @@ To enable the proxy registry: 1. Package your Helm chart and add it to a release. Promote the release to a development channel. See [Managing Releases with Vendor Portal](releases-creating-releases). -1. Install the chart in a development environment to test your changes: - - 1. Create a local `values.yaml` file to override the default external registry image URL with the URL for the image on `proxy.replicated.com`. - - The proxy registry URL has the following format: `proxy.replicated.com/proxy/APP_SLUG/EXTERNAL_REGISTRY_IMAGE_URL` - - Where: - * `APP_SLUG` is the slug of your Replicated application. - * `EXTERNAL_REGISTRY_IMAGE_URL` is the path to the private image on your external registry. - - **Example** - ```yaml - # A local values.yaml file - ... - images: - myapp: - apiImageRepository: proxy.replicated.com/proxy/my-app/quay.io/my-org/api - apiImageTag: v1.0.1 - - ``` - - :::note - If you configured a custom domain for the proxy registry, use the custom domain instead of `proxy.replicated.com`. For more information, see [Using Custom Domains](custom-domains-using). - ::: - - 1. Log in to the Replicated registry and install the chart, passing the local `values.yaml` file you created with the `--values` flag. See [Installing with Helm](install-with-helm). +1. Install in a development environment to test your changes. See [Installing with Helm](/vendor/install-with-helm). From 8e92f6812584cdac1b78db2d82fef3e38b97abb1 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Tue, 1 Apr 2025 11:52:31 -0600 Subject: [PATCH 2/4] update examples --- docs/vendor/helm-image-registry.mdx | 48 ++++++----------------------- 1 file changed, 9 insertions(+), 39 deletions(-) diff --git a/docs/vendor/helm-image-registry.mdx b/docs/vendor/helm-image-registry.mdx index 816b10c223..b50dbe908c 100644 --- a/docs/vendor/helm-image-registry.mdx +++ b/docs/vendor/helm-image-registry.mdx @@ -27,47 +27,20 @@ To use the Replicated proxy registry for applications installed with Helm: * `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 with custom domain:** - - ```yaml - # values.yaml - images: - your-app: - apiImageRepository: images.yourcompany.com/proxy/your-app-slug/ghcr.io/org-name/api - apiImageTag: v1.0.1 - ``` **Example with proxy.replicated.com:** ```yaml # values.yaml - images: - your-app: - registry: proxy.replicated.com - repository: proxy/your-app-slug/ghcr.io/cloudnative-pg/cloudnative-pg + api: + image: + registry: ghcr.io + repository: proxy/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 - # /templates/deployment.yaml - - apiVersion: apps/v1 - kind: Deployment - metadata: - name: example - spec: - template: - spec: - containers: - - name: api - # Access the repository and tag fields from the values file - image: {{ .Values.images.your-app.apiImageRepository }}:{{ .Values.images.your-app.apiImageTag }} - ``` **Example**: ```yaml @@ -75,9 +48,9 @@ To use the Replicated proxy registry for applications installed with Helm: kind: Pod spec: containers: - - name: + - name: api # Access the registry, repository, and tag fields from the values file - image: {{ .Values.images.your-app.registry }}/{{ .Values.images.your-app.repository }}:{{ .Values.images.your-app.tag }} + image: {{ .Values.images.api.registry }}/{{ .Values.images.api.repository }}:{{ .Values.images.api.tag }} ``` 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. @@ -89,7 +62,7 @@ To use the Replicated proxy registry for applications installed with Helm: ::: ```yaml - # /templates/replicated-pull-secret.yaml + # templates/replicated-pull-secret.yaml {{ if .Values.global.replicated.dockerconfigjson }} apiVersion: v1 @@ -109,7 +82,7 @@ To use the Replicated proxy registry for applications installed with Helm: **Example:** ```yaml - # /templates/deployment.yaml + # templates/deployment.yaml image: "{{ .Values.images.your-app.apiImageRepository }}:{{ .Values.images.your-app.apiImageTag }}" # Add the pull secret @@ -125,7 +98,4 @@ To use the Replicated proxy registry for applications installed with Helm: 1. Package your Helm chart and add it to a release. 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. See [Installing with Helm](/vendor/install-with-helm). - - - +1. Install in a development environment to test your changes. See [Installing with Helm](/vendor/install-with-helm). \ No newline at end of file From a4383644a14ab223f4f244818c4a7f12f107e14f Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Wed, 2 Apr 2025 09:23:50 -0600 Subject: [PATCH 3/4] edit pull secret example --- docs/vendor/helm-image-registry.mdx | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/docs/vendor/helm-image-registry.mdx b/docs/vendor/helm-image-registry.mdx index b50dbe908c..cbce158022 100644 --- a/docs/vendor/helm-image-registry.mdx +++ b/docs/vendor/helm-image-registry.mdx @@ -28,12 +28,13 @@ To use the Replicated proxy registry for applications installed with Helm: * `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 with proxy.replicated.com:** + **Example:** ```yaml # values.yaml api: image: + # proxy.registry.com or your custom domain registry: ghcr.io repository: proxy/app/ghcr.io/cloudnative-pg/cloudnative-pg tag: catalog-1.24.0 @@ -82,18 +83,18 @@ To use the Replicated proxy registry for applications installed with Helm: **Example:** ```yaml - # templates/deployment.yaml - - image: "{{ .Values.images.your-app.apiImageRepository }}:{{ .Values.images.your-app.apiImageTag }}" - # Add the pull secret - {{ if .Values.global.replicated.dockerconfigjson }} - imagePullSecrets: - - name: replicated-pull-secret - {{ end }} - name: your-app - ports: - - containerPort: 3000 - name: http + 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 }} + # Add the pull secret + {{ if .Values.global.replicated.dockerconfigjson }} + imagePullSecrets: + - name: replicated-pull-secret + {{ end }} ``` 1. Package your Helm chart and add it to a release. Promote the release to a development channel. See [Managing Releases with Vendor Portal](releases-creating-releases). From 120d1750e28cd4a30fdbb574a1ccc3cf1b675f38 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Wed, 2 Apr 2025 10:29:28 -0600 Subject: [PATCH 4/4] yaml spacing --- docs/vendor/helm-image-registry.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/vendor/helm-image-registry.mdx b/docs/vendor/helm-image-registry.mdx index cbce158022..788c29342e 100644 --- a/docs/vendor/helm-image-registry.mdx +++ b/docs/vendor/helm-image-registry.mdx @@ -50,7 +50,7 @@ To use the Replicated proxy registry for applications installed with Helm: spec: containers: - name: api - # Access the registry, repository, and tag fields from the values file + # Access the registry, repository, and tag fields from the values file image: {{ .Values.images.api.registry }}/{{ .Values.images.api.repository }}:{{ .Values.images.api.tag }} ```