Edit configuring helmchart v2 #3377

paigecalvert · 2025-07-14T17:59:30Z

https://deploy-preview-3377--replicated-docs.netlify.app/vendor/helm-native-v2-using

Main changes made:

Change the recommended strategy for conditionally rewriting image refs when a local registry is used from ternary operators to optionalValues
Rather than telling vendors to edit the values key to update image refs to the proxy registry, replace that step with a link to the https://docs.replicated.com/vendor/private-images-kots topic, which explains how to edit image refs directly in the Helm chart values to point to the proxy registry
Other content and formatting edits to simplify

netlify · 2025-07-14T17:59:33Z

✅ Deploy Preview for replicated-docs ready!

Name	Link
🔨 Latest commit	`486ad6f`
🔍 Latest deploy log	https://app.netlify.com/projects/replicated-docs/deploys/68965e5cac657800087f19f0
😎 Deploy Preview	https://deploy-preview-3377--replicated-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

netlify · 2025-07-14T17:59:34Z

✅ Deploy Preview for replicated-docs-upgrade ready!

Name	Link
🔨 Latest commit	`486ad6f`
🔍 Latest deploy log	https://app.netlify.com/projects/replicated-docs-upgrade/deploys/68965e5cfa19080008be7ce9
😎 Deploy Preview	https://deploy-preview-3377--replicated-docs-upgrade.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

paigecalvert · 2025-07-15T15:59:43Z

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

-
-    <details>
-    <summary>What is the registry namespace?</summary>
+# Support Installations with HelmChart v2


Configure the HelmChart Custom Resource v2 --> Support Installations with HelmChart v2 since it's walking you through the whole process which now involves editing your Helm values to update image refs to the proxy service (ie, not just configuring the HelmChart resource itself)

paigecalvert · 2025-07-15T16:02:33Z

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

-
-This topic describes how to configure the Replicated HelmChart custom resource version `kots.io/v1beta2` to support Helm chart installations with Replicated KOTS.
-
-## Workflow


^ removed "Workflow" and subheadings in favor of just making this a numbered list of steps. This was possible since we are now linking off to a lot of content and overall there was a lot of content that could be cut down on

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

paigecalvert · 2025-07-15T16:04:14Z

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

+      The registry namespace is the path between the registry and the image name. For example, `images.registry.com/namespace/image:tag`.
+   </details>
+
+1. In the HelmChart v2 custom resource that corresponds to the chart where the Replicated SDK is declared as a dependency, configure the [`optionalValues`](/reference/custom-resource-helmchart-v2#optionalValues) key using the same method as in the previous step to conditionally rewrite the Replicated SDK image reference.


^ also added a corresponding step for updating the sdk image to be conditionally rewritten to local registries. this was missing before

paigecalvert · 2025-07-15T16:05:48Z

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

+     <summary>What is the registry namespace?</summary>
+
+      The registry namespace is the path between the registry and the image name. For example, `images.registry.com/namespace/image:tag`.
+   </details>


^ I moved a lot of the explanatory content to <details> dropdowns to cut down on noise on the page

i like the dropdown. again, i'm wondering if there should be some split context given between if the customer is using a private registry or airgap in what the behavior of LocalRegistryNamespace will be.

I'm not sure we have it documented anywhere else but currently if you have an image named quay.io/some-namespace/some-namespace/image-name, when we push it into our registry for airgap, we strip both namespaces and say internal-registry-namespace/local-registry-namespace/image-name and i've seen support cases in the past where customers expected internal-registry-namespace/some-namespace/local-registry-namespace/image-name or something like that.

Oh, I think that's new to me. Yeah that would be helpful to clarify I'm sure. And I don't think it's documented currently

So it looks like we have the following documented for LocalRegistryNamespace:

Returns the namespace of the local registry that the user configured. Alternatively, for air gap installations with Embedded Cluster or kURL, LocalRegistryNamespace returns the namespace of the built-in registry.

https://docs.replicated.com/reference/template-functions-config-context#localregistrynamespace

I wonder if this might need a follow-up story to improve this description.

Added a story here: https://app.shortcut.com/replicated/story/127733/clarify-how-the-localregistrynamespace-template-function-works-in-air-gap-environmentsAdded a

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

diamonwiggins · 2025-07-18T22:01:24Z

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

+
+1. For each Helm chart in the release, ensure that there is a corresponding HelmChart v2 custom resource (version `kots.io/v1beta2`) . See [HelmChart v2](/reference/custom-resource-helmchart-v2).
+
+1. If you are migrating from HelmChart v1, remove any unsupported fields from the HelmChart custom resource(s) in the release. See [HelmChart v1 and v2 Differences](#differences) below.


we should maybe link to the migration docs as well here.

actually, I decided to rewrite this a little bit to remove the "migrating" language in favor of more plain language to articulate updating the resource from v1 to v2. The reason I wanted to go this path was because the "migrating" content really refers to the steps after migrating an existing customer installation, not editing the custom resource itself. There's a "next step" subheading on this page that tells vendors to go read the migration doc once they are ready to migrate existing installations

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

diamonwiggins · 2025-07-18T22:11:27Z

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

+            repository: your-org/example-docker-hub-image
+            # Add a new pullSecrets array with the <app-slug>-kotsadm-dockerhub pull secret
+            pullSecrets:
+            - name: your-app-slug-kotsadm-dockerhub


is there not a repl{{ ImagePullSecret }} for this?

Indeed there is...I must have accidentally edited that out somehow. Thanks

or wait...I think the pull secret for dockerhub might be different. I'll investigate

Okay, so here is where we tell people to use that ImagePullSecretName template function: https://docs.replicated.com/vendor/private-images-kots#configure-your-application-to-use-the-proxy-registry

^ those are the steps to configure your app to use the proxy registry. In those steps, we tell people to use the ImagePullSecretName template function to inject the pull secret to authenticate with the proxy registry.

I think the docker hub pull secret mentioned here in this PR might be specifically for the kots docker ensure-secret command. For reference, here's the content that's currently published on the docs site that explains the dockerhub pull secret stuff: https://docs.replicated.com/vendor/helm-native-v2-using#docker-secret. I basically just rewrote this existing content a bit for this PR

ajp-io · 2025-08-06T20:45:34Z

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

+
+This topic describes how to configure a release to support installations with the Replicated HelmChart custom resource version `kots.io/v1beta2` (HelmChart v2). For more information about HelmChart v2, see [About Distributing Helm Chart with KOTS](/vendor/helm-native-about).
+
+## Configure a Release to Support HelmChart v2 Installations


just curious, not saying to change it, but you do think it's weird that with our setup now you have all these "make sure you did this and this and this first" notes? i haven't thought about it enough to have any alternative, and it might be totally fine. it was just something i noticed when reading through this.

Yeah, it's definitely not an ideal flow. Probably annoying to have it to make it through a lot of "pre" before getting to the main task.

Here's how I was thinking about it, and maybe you have an opinion one way or the other that could tip the scales:

In the original mega-PR, I removed this topic all together and redistributed all the steps into their relevant sections of the docs (ie, the stuff about snapshots went to the snapshots section and the stuff about dockerhub rate limiting went to the rate limiting page).

As part of breaking the mega-PR into smaller-PRs, this PR was intended to be a smaller step that at least updates the info to show how to use optionalValues for rewriting to local image registries. That was main objective.

I still think it's worth considering if this page can be deleted, because yeah, it's a weird flow. In the meantime before it gets deleted and redistributed, which would be a larger PR, I wanted to at least make sure that it included all the info people would need to actually accomplish the task outlined in the page title: support helmchart v2 installs.

ajp-io · 2025-08-06T20:47:25Z

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

-The following HelmChart custom resource includes `spec.values.image.registry`, `spec.values.image.repository`, and `spec.values.image.pullSecrets`, which correspond to those in the Helm chart `values.yaml` file above.
-
-The `spec.values.image.pullSecrets` array lists the `<app-slug>-kotsadm-dockerhub` pull secret, where the slug for the application is `example-app-slug`:
+1. For any of your application images that could be rate limited by Docker Hub, do the following to avoid errors caused by reaching the rate limit:


so you ended up deciding to put this in here? i just wonder if it's a good idea since it requires using a kots cli command, and generally people onboarding aren't using kots now.

We could totally remove it! I think that would really simplify things. I was mainly trying to limit the number of edits I was making in this PR, and so I left it in since it's included in the currently-published version.

Thinking about this again: If we remove the docker hub stuff because it applies to existing cluster KOTS installs, then we would probably also remove the step for snapshots for the same reason, right? Not necessarily a vote in either direction for this particular PR, but just seems that they go hand-in-hand

that's a good point. if this is the flow that new vendors go through, let's not bog it down with either of those. but i suppose we do need a way for those docs to exist for older vendors.

paigecalvert added 4 commits July 10, 2025 11:25

Edit steps in configure helmchart v2 topic

cb80d5e

edit

35d0933

formatting into numbered steps

20368c7

editing steps on how to configure helmchart v2

fb1c1f8

replicated-ci added type::docs Improvements or additions to documentation type::feature labels Jul 14, 2025

paigecalvert added 3 commits July 15, 2025 08:47

Merge branch 'main' into edit-configuring-helmchart-v2

e251173

edits

6c5c420

undo sidebar change

3cf0c35

paigecalvert commented Jul 15, 2025

View reviewed changes

docs/vendor/helm-native-v2-using.md Outdated Show resolved Hide resolved

paigecalvert commented Jul 15, 2025

View reviewed changes

docs/vendor/helm-native-v2-using.md Outdated Show resolved Hide resolved

paigecalvert commented Jul 15, 2025

View reviewed changes

docs/vendor/helm-native-v2-using.md Show resolved Hide resolved

paigecalvert commented Jul 15, 2025

View reviewed changes

docs/vendor/helm-native-v2-using.md Outdated Show resolved Hide resolved

undo heading change

1d34098

paigecalvert marked this pull request as ready for review July 15, 2025 16:09

paigecalvert requested a review from a team as a code owner July 15, 2025 16:09

diamonwiggins reviewed Jul 18, 2025

View reviewed changes

docs/vendor/helm-native-v2-using.md Outdated Show resolved Hide resolved

diamonwiggins reviewed Jul 18, 2025

View reviewed changes

paigecalvert added 2 commits July 30, 2025 09:10

clarify helm values language

82e6803

edit migration language

579c312

ajp-io reviewed Aug 6, 2025

View reviewed changes

split out dockerhub and snapshots steps

486ad6f

paigecalvert requested a review from ajp-io August 8, 2025 20:30

paigecalvert merged commit 3ea318e into main Aug 11, 2025
5 checks passed

paigecalvert deleted the edit-configuring-helmchart-v2 branch August 11, 2025 17:03


		This topic describes how to configure the Replicated HelmChart custom resource version `kots.io/v1beta2` to support Helm chart installations with Replicated KOTS.

		## Workflow


		1. For each Helm chart in the release, ensure that there is a corresponding HelmChart v2 custom resource (version `kots.io/v1beta2`) . See [HelmChart v2](/reference/custom-resource-helmchart-v2).

		1. If you are migrating from HelmChart v1, remove any unsupported fields from the HelmChart custom resource(s) in the release. See [HelmChart v1 and v2 Differences](#differences) below.


		This topic describes how to configure a release to support installations with the Replicated HelmChart custom resource version `kots.io/v1beta2` (HelmChart v2). For more information about HelmChart v2, see [About Distributing Helm Chart with KOTS](/vendor/helm-native-about).

		## Configure a Release to Support HelmChart v2 Installations

Edit configuring helmchart v2 #3377

Edit configuring helmchart v2 #3377

Uh oh!

Conversation

paigecalvert commented Jul 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify bot commented Jul 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for replicated-docs ready!

Uh oh!

netlify bot commented Jul 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for replicated-docs-upgrade ready!

Uh oh!

paigecalvert Jul 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

paigecalvert Jul 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

paigecalvert Jul 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

paigecalvert Jul 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

paigecalvert Jul 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

paigecalvert commented Jul 14, 2025 •

edited

Loading

netlify bot commented Jul 14, 2025 •

edited

Loading

netlify bot commented Jul 14, 2025 •

edited

Loading

paigecalvert Jul 15, 2025 •

edited

Loading

paigecalvert Jul 15, 2025 •

edited

Loading

paigecalvert Jul 15, 2025 •

edited

Loading

paigecalvert Jul 15, 2025 •

edited

Loading

paigecalvert Jul 30, 2025 •

edited

Loading