Skip to content

Edit docs on using the proxy registry #3366

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 7 commits into
base: main
Choose a base branch
from
Open

Edit docs on using the proxy registry #3366

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
ffcac06
Edit docs on using the proxy registry
paigecalvert Jul 8, 2025
a920799
merge conflicts with main
paigecalvert Jul 9, 2025
e7753eb
edits
paigecalvert Jul 9, 2025
fcf7c19
edits
paigecalvert Jul 9, 2025
5e6b5c4
undo extra line in partial
paigecalvert Jul 9, 2025
8bdc1af
edit anchor link
paigecalvert Jul 10, 2025
0755c9f
fix yaml
paigecalvert Jul 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/partials/proxy-service/_step-additional-ns.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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).
57 changes: 12 additions & 45 deletions docs/vendor/helm-image-registry.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,64 +1,32 @@
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"
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

pulls in the new partial that has the step on how to modify image refs in your helm values


# Use the Proxy Registry with Helm Installations
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

one thing that could clarify the docs a bit is if we said something like "with Helm CLI installations." i know helm is all over the place now, and people are using helm for all installation methods, so maybe that would clear up the fact that this is when you're using helm install directly. just a thought.


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.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

minor rewording in overview section mainly to try to remove extra info/words


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. <StepCreds/>

1. <StepCustomDomain/>

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`.
1. <RewriteHelmValues/>
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

^ replaced with the partial


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. 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.
Expand All @@ -79,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:**

Expand Down
94 changes: 64 additions & 30 deletions docs/vendor/private-images-kots.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,38 +1,81 @@
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
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

with KOTS Installations --> with Replicated Installers

Open to other suggestions on wording. Goal is to avoid using "KOTS" to actually mean KOTS/EC/kURL


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). For more information about the proxy registry, see [About the Replicated Proxy Registry](private-images-about).

## Overview
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did some deleting/shuffling so this no longer needs such a big overview section

Instead, jumps right into the steps on how to configure your app to use the proxy, with a couple other subheadings for the non-HelmChart v2 apps

## 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.
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.

### 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 [Configure Other Application Types](#other) below.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

^ I landed on a main "Configure Your App" section that assumes Helm app and HelmChart v2. And then links people that use other packaging/install methods down to the "other" options

My thought is that it highlights the main path that we expect most people to follow while minimizing noise of other possibilities

Open to suggestions on this


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 installations with a Replicated installer:

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. <StepCreds/>

1. <StepCustomDomain/>

1. <RewriteHelmValues/>

1. <InjectPullSecret/>

1. Repeat steps 3 and 4 for each Helm chart used by your application.

1. <AdditionalNs/>

### Image Location Patching (Standard Manifests and HelmChart v1)
1. Create a new release with your changes. Promote the release to a development channel. See [Managing Releases with Vendor Portal](releases-creating-releases).

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. Install in a development environment to test your changes.

## 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.

### HelmChart v1 or Standard Manifests

:::note
<Deprecated/>
:::

To use the proxy registry with HelmChart v1 or applications packaged with standard manifests:

1. <StepCreds/>

1. <StepCustomDomain/>

1. <AdditionalNs/>

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.

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.

<details>

<summary>How does KOTS patch image names?</summary>
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

^ adds all this info to a details element


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
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
Expand All @@ -45,31 +88,22 @@ 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
```
</details>

## Enable the Proxy Registry

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.
### Kubernetes Operators
Copy link
Contributor Author

@paigecalvert paigecalvert Jul 10, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Left in the k8s operator stuff. Not sure if anyone's still using them/if this could be removed yet

If it can be removed, that would of course make it easier to further simplify this page


To enable the proxy registry:
To use the proxy registry with applications packaged as Kubernetes Operators:

1. <StepCreds/>

1. <StepCustomDomain/>

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:

* **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).

* **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.

:::note
<Deprecated/>
:::
1. <AdditionalNs/>

* **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. 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. 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).
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. (Optional) Add a custom domain for the proxy registry instead of `proxy.replicated.com`. See [Use Custom Domains](custom-domains-using).
1. Install in a development environment to test your changes.