Clarify registry auth behavior per install method#4176
Merged
Conversation
The end customer auth section previously only referenced registry_token without explaining how credentials differ across Helm CLI, KOTS, EC v2, and EC v3 installs. The proxy registry overview said "steps vary" without giving any context on what varies and why. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
✅ Deploy Preview for replicated-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
✅ Deploy Preview for replicated-docs-upgrade ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
replicated-ci
added
type::docs
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| ### End customer authentication | ||
|
|
||
| A valid (unexpired) license file has an embedded `registry_token` value. Replicated components shipped to customers use this value to authenticate to the registry. Only pull access is enabled when authenticating using a `registry_token`. A `registry_token` has pull access to all images in the tenant's account. All requests to pull images are denied when a license expires or the expiration date is changed to a past date. | ||
| End customer access to the registry is read-only (pull access only). The specific credential used depends on the installation method: |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('is read').
| A valid (unexpired) license file has an embedded `registry_token` value. Replicated components shipped to customers use this value to authenticate to the registry. Only pull access is enabled when authenticating using a `registry_token`. A `registry_token` has pull access to all images in the tenant's account. All requests to pull images are denied when a license expires or the expiration date is changed to a past date. | ||
| End customer access to the registry is read-only (pull access only). The specific credential used depends on the installation method: | ||
|
|
||
| - **KOTS and Embedded Cluster v2 installations**: The KOTS license ID is used as both the username and password when authenticating to `registry.replicated.com` and `proxy.replicated.com`. Replicated builds the image pull secret (`dockerconfigjson`) automatically and includes it in the release payload delivered to the admin console. |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('is used').
| A valid (unexpired) license file has an embedded `registry_token` value. Replicated components shipped to customers use this value to authenticate to the registry. Only pull access is enabled when authenticating using a `registry_token`. A `registry_token` has pull access to all images in the tenant's account. All requests to pull images are denied when a license expires or the expiration date is changed to a past date. | ||
| End customer access to the registry is read-only (pull access only). The specific credential used depends on the installation method: | ||
|
|
||
| - **KOTS and Embedded Cluster v2 installations**: The KOTS license ID is used as both the username and password when authenticating to `registry.replicated.com` and `proxy.replicated.com`. Replicated builds the image pull secret (`dockerconfigjson`) automatically and includes it in the release payload delivered to the admin console. |
Contributor
There was a problem hiding this comment.
[Replicated.WordSwapsCaseSensitive] Use 'Admin Console' instead of 'admin console'.
|
|
||
| - **KOTS and Embedded Cluster v2 installations**: The KOTS license ID is used as both the username and password when authenticating to `registry.replicated.com` and `proxy.replicated.com`. Replicated builds the image pull secret (`dockerconfigjson`) automatically and includes it in the release payload delivered to the admin console. | ||
|
|
||
| - **Helm CLI and Embedded Cluster v3 installations**: Customers authenticate using either a license ID or an enterprise portal service account token. The credentials are provided during `helm registry login` or `docker login` before installation. |
Contributor
There was a problem hiding this comment.
[Replicated.WordSwapsCaseSensitive] Use 'Enterprise Portal' instead of 'enterprise portal'.
|
|
||
| - **KOTS and Embedded Cluster v2 installations**: The KOTS license ID is used as both the username and password when authenticating to `registry.replicated.com` and `proxy.replicated.com`. Replicated builds the image pull secret (`dockerconfigjson`) automatically and includes it in the release payload delivered to the admin console. | ||
|
|
||
| - **Helm CLI and Embedded Cluster v3 installations**: Customers authenticate using either a license ID or an enterprise portal service account token. The credentials are provided during `helm registry login` or `docker login` before installation. |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('are provided').
|
|
||
| - **Helm CLI and Embedded Cluster v3 installations**: Customers authenticate using either a license ID or an enterprise portal service account token. The credentials are provided during `helm registry login` or `docker login` before installation. | ||
|
|
||
| In all cases, pull access is scoped to images belonging to the vendor's account. All requests to pull images are denied when a customer's license expires or the expiration date is changed to a past date. |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('is scoped').
|
|
||
| - **Helm CLI and Embedded Cluster v3 installations**: Customers authenticate using either a license ID or an enterprise portal service account token. The credentials are provided during `helm registry login` or `docker login` before installation. | ||
|
|
||
| In all cases, pull access is scoped to images belonging to the vendor's account. All requests to pull images are denied when a customer's license expires or the expiration date is changed to a past date. |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('are denied').
|
|
||
| - **Helm CLI and Embedded Cluster v3 installations**: Customers authenticate using either a license ID or an enterprise portal service account token. The credentials are provided during `helm registry login` or `docker login` before installation. | ||
|
|
||
| In all cases, pull access is scoped to images belonging to the vendor's account. All requests to pull images are denied when a customer's license expires or the expiration date is changed to a past date. |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('is changed').
| * [Use the Proxy Registry with Helm CLI Installations](/vendor/helm-image-registry) | ||
| After connecting your registry, the steps to enable the proxy registry vary depending on your application deployment method: | ||
|
|
||
| * **Helm CLI installations**: The Replicated SDK, included as a subchart, creates the image pull secret in the cluster at runtime. Customer credentials are provided during `helm registry login` before installation. For more information, see [Use the Proxy Registry with Helm CLI Installations](/vendor/helm-image-registry). |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('are provided').
|
|
||
| * **KOTS and Embedded Cluster v2 installations**: Replicated automatically builds an image pull secret using the customer's license ID and includes it in the release payload. Image references in your manifests are rewritten to proxy-prefixed URLs (for example, `proxy.replicated.com/proxy/<app-slug>/gcr.io/my-org/my-app:latest`). For more information, see [Use the Proxy Registry with Replicated Installers](/vendor/private-images-kots). | ||
|
|
||
| * **Embedded Cluster v3 installations**: The Embedded Cluster daemon handles registry authentication using an enterprise portal service account token instead of a license ID. |
Contributor
There was a problem hiding this comment.
[Replicated.WordSwapsCaseSensitive] Use 'Enterprise Portal' instead of 'enterprise portal'.
…kens Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
| A valid (unexpired) license file has an embedded `registry_token` value. Replicated components shipped to customers use this value to authenticate to the registry. Only pull access is enabled when authenticating using a `registry_token`. A `registry_token` has pull access to all images in the tenant's account. All requests to pull images are denied when a license expires or the expiration date is changed to a past date. | ||
| End customer access to the registry is read-only (pull access only). The specific credential used depends on the installation method: | ||
|
|
||
| - **KOTS and Embedded Cluster v2 installations**: The KOTS license ID is used as both the username and password when authenticating to `registry.replicated.com` and `proxy.replicated.com`. Replicated builds the image pull secret (`dockerconfigjson`) automatically and includes it in the release payload delivered to the admin console. Embedded Cluster v2 installations accessed through the Enterprise Portal can also use an enterprise portal service account token. |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('is used').
| A valid (unexpired) license file has an embedded `registry_token` value. Replicated components shipped to customers use this value to authenticate to the registry. Only pull access is enabled when authenticating using a `registry_token`. A `registry_token` has pull access to all images in the tenant's account. All requests to pull images are denied when a license expires or the expiration date is changed to a past date. | ||
| End customer access to the registry is read-only (pull access only). The specific credential used depends on the installation method: | ||
|
|
||
| - **KOTS and Embedded Cluster v2 installations**: The KOTS license ID is used as both the username and password when authenticating to `registry.replicated.com` and `proxy.replicated.com`. Replicated builds the image pull secret (`dockerconfigjson`) automatically and includes it in the release payload delivered to the admin console. Embedded Cluster v2 installations accessed through the Enterprise Portal can also use an enterprise portal service account token. |
Contributor
There was a problem hiding this comment.
[Replicated.WordSwapsCaseSensitive] Use 'Admin Console' instead of 'admin console'.
| A valid (unexpired) license file has an embedded `registry_token` value. Replicated components shipped to customers use this value to authenticate to the registry. Only pull access is enabled when authenticating using a `registry_token`. A `registry_token` has pull access to all images in the tenant's account. All requests to pull images are denied when a license expires or the expiration date is changed to a past date. | ||
| End customer access to the registry is read-only (pull access only). The specific credential used depends on the installation method: | ||
|
|
||
| - **KOTS and Embedded Cluster v2 installations**: The KOTS license ID is used as both the username and password when authenticating to `registry.replicated.com` and `proxy.replicated.com`. Replicated builds the image pull secret (`dockerconfigjson`) automatically and includes it in the release payload delivered to the admin console. Embedded Cluster v2 installations accessed through the Enterprise Portal can also use an enterprise portal service account token. |
Contributor
There was a problem hiding this comment.
[Replicated.WordSwapsCaseSensitive] Use 'Enterprise Portal' instead of 'enterprise portal'.
sgalsaleh
reviewed
Jun 15, 2026
|
|
||
| - **KOTS and Embedded Cluster v2 installations**: The KOTS license ID is used as both the username and password when authenticating to `registry.replicated.com` and `proxy.replicated.com`. Replicated builds the image pull secret (`dockerconfigjson`) automatically and includes it in the release payload delivered to the admin console. Embedded Cluster v2 installations accessed through the Enterprise Portal can also use an enterprise portal service account token. | ||
|
|
||
| - **Helm CLI and Embedded Cluster v3 installations**: Customers authenticate using either a license ID or an enterprise portal service account token. The credentials are provided during `helm registry login` or `docker login` before installation. |
Member
There was a problem hiding this comment.
hmm i don't think EC V3 supports using a service account token to auth here. i believe we only use the license id. unless the license id is set to a service account token when it's downloaded?
sgalsaleh
reviewed
Jun 15, 2026
|
|
||
| * **KOTS and Embedded Cluster v2 installations**: Replicated automatically builds an image pull secret using the customer's license ID and includes it in the release payload. Image references in your manifests are rewritten to proxy-prefixed URLs (for example, `proxy.replicated.com/proxy/<app-slug>/gcr.io/my-org/my-app:latest`). For more information, see [Use the Proxy Registry with Replicated Installers](/vendor/private-images-kots). | ||
|
|
||
| * **Embedded Cluster v3 installations**: The Embedded Cluster daemon handles registry authentication using an enterprise portal service account token instead of a license ID. |
Member
There was a problem hiding this comment.
same note as above. EC V3 uses license.spec.licenseID, i assume SaaS sets that to the service account token?
sgalsaleh
reviewed
Jun 15, 2026
| A valid (unexpired) license file has an embedded `registry_token` value. Replicated components shipped to customers use this value to authenticate to the registry. Only pull access is enabled when authenticating using a `registry_token`. A `registry_token` has pull access to all images in the tenant's account. All requests to pull images are denied when a license expires or the expiration date is changed to a past date. | ||
| End customer access to the registry is read-only (pull access only). The specific credential used depends on the installation method: | ||
|
|
||
| - **KOTS and Embedded Cluster v2 installations**: The KOTS license ID is used as both the username and password when authenticating to `registry.replicated.com` and `proxy.replicated.com`. Replicated builds the image pull secret (`dockerconfigjson`) automatically and includes it in the release payload delivered to the admin console. Embedded Cluster v2 installations accessed through the Enterprise Portal can also use an enterprise portal service account token. |
Member
There was a problem hiding this comment.
username is hardcoded to LICENSE_ID
Per eng review: the actual username in pull secrets is implementation- specific and varies between server-side and client-side. Keep the docs focused on the credential source (license ID) without specifying the exact username/password format. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
| A valid (unexpired) license file has an embedded `registry_token` value. Replicated components shipped to customers use this value to authenticate to the registry. Only pull access is enabled when authenticating using a `registry_token`. A `registry_token` has pull access to all images in the tenant's account. All requests to pull images are denied when a license expires or the expiration date is changed to a past date. | ||
| End customer access to the registry is read-only (pull access only). The specific credential used depends on the installation method: | ||
|
|
||
| - **KOTS and Embedded Cluster v2 installations**: Replicated builds the image pull secret automatically using credentials derived from the customer's license ID and includes it in the release payload delivered to the admin console. Embedded Cluster v2 installations accessed through the Enterprise Portal can also use an enterprise portal service account token. |
Contributor
There was a problem hiding this comment.
[Replicated.WordSwapsCaseSensitive] Use 'Admin Console' instead of 'admin console'.
| A valid (unexpired) license file has an embedded `registry_token` value. Replicated components shipped to customers use this value to authenticate to the registry. Only pull access is enabled when authenticating using a `registry_token`. A `registry_token` has pull access to all images in the tenant's account. All requests to pull images are denied when a license expires or the expiration date is changed to a past date. | ||
| End customer access to the registry is read-only (pull access only). The specific credential used depends on the installation method: | ||
|
|
||
| - **KOTS and Embedded Cluster v2 installations**: Replicated builds the image pull secret automatically using credentials derived from the customer's license ID and includes it in the release payload delivered to the admin console. Embedded Cluster v2 installations accessed through the Enterprise Portal can also use an enterprise portal service account token. |
Contributor
There was a problem hiding this comment.
[Replicated.WordSwapsCaseSensitive] Use 'Enterprise Portal' instead of 'enterprise portal'.
sgalsaleh
approved these changes
Jun 15, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Preview links
Tied to https://app.shortcut.com/replicated/story/136977/update-proxy-registry-and-registry-auth-docs-to-explain-how-auth-works-across-install-methods
Summary
registry_tokendescription with per-install-method breakdown (KOTS/EC v2 use license ID, Helm CLI/EC v3 use license ID or service account token)Related: sc-136977
Test plan
/vendor/private-images-kots,/vendor/helm-image-registry,/vendor/packaging-private-images) still resolveproxy.replicated.com/proxy/<app-slug>/...) matches actual behavior🤖 Generated with Claude Code