Update Helmchart cr docs for ec v3#4061
Open
paigecalvert wants to merge 9 commits into
Open
Conversation
✅ Deploy Preview for replicated-docs-upgrade ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
✅ Deploy Preview for replicated-docs 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}
| @@ -1,2 +1,2 @@ | |||
| The `chart` key allows for a mapping between the data in this definition and the chart archive itself. | |||
| More than one `kind: HelmChart` can reference a single chart archive, if different settings are needed. No newline at end of file | |||
| More than one `kind: HelmChart` can reference a single chart archive, if different settings are needed. | |||
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('are needed').
| * When `optionalValues.recursiveMerge` is false, the top level keys in `optionalValues` override the top level keys in `values`. By default, `optionalValues.recursiveMerge` is set to false. | ||
|
|
||
| * When `optionalValues.recursiveMerge` is true, all keys from `values` and `optionalValues` are included. In the case of a conflict where there is a matching key in `optionalValues` and `values`, the Replicated installer uses the value of the key from `optionalValues`. No newline at end of file | ||
| * When `optionalValues.recursiveMerge` is true, all keys from `values` and `optionalValues` are included. In the case of a conflict where there is a matching key in `optionalValues` and `values`, the Replicated installer uses the value of the key from `optionalValues`. |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('are included').
| | Property | Description | | ||
| | --- | --- | | ||
| | `optionalValues.when` | Defines a conditional statement that must evaluate to true for the values in `optionalValues.values` to be set in the Helm chart. Evaluation of the conditional in the `optionalValues.when` field is deferred until render time in the customer environment. | | ||
| | `optionalValues.recursiveMerge` | The `optionalValues.recursiveMerge` boolean defines how the Replicated installer merges `values` and `optionalValues`. When `optionalValues.recursiveMerge` is false, the top level keys in `optionalValues` override the top level keys in `values`. When `optionalValues.recursiveMerge` is true, all keys from `values` and `optionalValues` are included. In the case of a conflict where there is a matching key in `optionalValues` and `values`, the Replicated installer uses the value of the key from `optionalValues`. By default, `optionalValues.recursiveMerge` is false. For an example, see [Recursive merge](#recursive-merge) on this page.| |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('are included').
| <HelmUpgradeFlags/> | ||
|
|
||
| ## exclude | ||
| ### exclude |
Contributor
There was a problem hiding this comment.
[Replicated.Headings] 'exclude' should use sentence case.
| exclude: "repl{{ ConfigOptionEquals `include_chart` false }}" | ||
| ``` | ||
|
|
||
| ### values |
Contributor
There was a problem hiding this comment.
[Replicated.Headings] 'values' should use sentence case.
| #### Delete a default value key | ||
|
|
||
| ### optionalValues.recursiveMerge | ||
| A common use case for deleting default value keys is when you include a community Helm chart as a dependency. Because you cannot control how the community chart is built and structured, you might want to change some of the default behavior. For more information about using a `null` value to delete a key, see [Deleting a Default Key](https://helm.sh/docs/chart_template_guide/values_files/#deleting-a-default-key) in the Helm documentation. |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('is built').
| ## namespace | ||
| <RecursiveMergeExample/> | ||
|
|
||
| ### namespace |
Contributor
There was a problem hiding this comment.
[Replicated.Headings] 'namespace' should use sentence case.
| <Namespace/> | ||
|
|
||
| ## builder | ||
| ### builder |
Contributor
There was a problem hiding this comment.
[Replicated.Headings] 'builder' should use sentence case.
| Using Replicated template functions in the [Config](/reference/template-functions-config-context) context allows you to set Helm values based on user-supplied values from the Admin Console configuration page. | ||
|
|
||
| <OptionalValuesRecursiveMerge/> | ||
| The following Helm chart `values.yaml` file contains `postgresql.enabled`, which is set to `false`: |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('is set').
| ``` | ||
|
|
||
| ### optionalValues.values | ||
| The `values.postgresql.enabled` field in the HelmChart custom resource above uses the Replicated [ConfigOptionEquals](/reference/template-functions-config-context#configoptionequals) template function to evaluate the user's selection for a `postgres_type` configuration option. |
Contributor
There was a problem hiding this comment.
[Replicated.PositionalLanguage] Avoid spacial and directional language like 'above'. Instead, use 'on this page', 'the following', or link to the section.
| The `values.postgresql.enabled` field in the HelmChart custom resource above uses the Replicated [ConfigOptionEquals](/reference/template-functions-config-context#configoptionequals) template function to evaluate the user's selection for a `postgres_type` configuration option. | ||
|
|
||
| In the `optionalValues.values` key, include the values to set if the specified condition is met. The `optionalValues.values` key supports static values and Replicated template functions. | ||
| During installation or upgrade, the template function is rendered to true or false based on the user's selction. Then, the Replicated installer sets the matching `postgresql.enabled` value in the Helm chart `values.yaml` file accordingly. |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('is rendered').
| The `values.postgresql.enabled` field in the HelmChart custom resource above uses the Replicated [ConfigOptionEquals](/reference/template-functions-config-context#configoptionequals) template function to evaluate the user's selection for a `postgres_type` configuration option. | ||
|
|
||
| In the `optionalValues.values` key, include the values to set if the specified condition is met. The `optionalValues.values` key supports static values and Replicated template functions. | ||
| During installation or upgrade, the template function is rendered to true or false based on the user's selction. Then, the Replicated installer sets the matching `postgresql.enabled` value in the Helm chart `values.yaml` file accordingly. |
Contributor
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'selction'?
| enabled: repl{{ LicenseFieldValue "newFeatureEntitlement" }} | ||
| ``` | ||
|
|
||
| During installation or upgrade, the LicenseFieldValue template function is rendered based on the user's license. Then, the Replicated installer sets the matching `newFeature.enabled` value in the Helm chart `values.yaml` file accordingly. |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('is rendered').
| * <TemplateLimitation/> | ||
| * Helm's `lookup` function and some values in the built-in `Capabilities` object are not supported with the `kots.io/v1beta1` HelmChart custom resource. | ||
|
|
||
| This is because KOTS uses the `helm template` command to render chart templates locally. During rendering, Helm does not have access to the cluster where the chart will be installed. For more information, see [Kubernetes and Chart Functions](https://helm.sh/docs/chart_template_guide/function_list/#kubernetes-and-chart-functions) in the Helm documentation. |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('be installed').
| * <TemplateLimitation/> | ||
| * Helm's `lookup` function and some values in the built-in `Capabilities` object are not supported with the `kots.io/v1beta1` HelmChart custom resource. | ||
|
|
||
| This is because KOTS uses the `helm template` command to render chart templates locally. During rendering, Helm does not have access to the cluster where the chart will be installed. For more information, see [Kubernetes and Chart Functions](https://helm.sh/docs/chart_template_guide/function_list/#kubernetes-and-chart-functions) in the Helm documentation. |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('be installed').
| * Any `required` Helm values that need to be set to render the chart templates must have a value supplied in the `builder` key. For more information about the Helm `required` function, see [Using the 'required' function](https://helm.sh/docs/howto/charts_tips_and_tricks/#using-the-required-function) in the Helm documentation. | ||
| * Replicated recommends that you include only the minimum Helm values in the `builder` key required to template the Helm chart with the correct image tags. | ||
| * Use only static, or _hardcoded_, values in the `builder` key. You can't use template functions in the `builder` key because values in the `builder` key are not rendered in a customer environment. | ||
| * Any `required` Helm values that need to be set to render the chart templates must have a value in the `builder` key. For more information about the Helm `required` function, see [Using the 'required' function](https://helm.sh/docs/howto/charts_tips_and_tricks/#using-the-required-function) in the Helm documentation. |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('be set').
| @@ -1,7 +1,3 @@ | |||
| Specifies the order in which Helm charts are installed within the application. Charts are installed by weight in ascending order, with lower weights installed first. **Supported values:** Positive or negative integers. **Default:** `0` | |||
| Specifies the installation order of the Helm charts in the release. Charts are installed by weight in ascending order with lower weights first. Also determines the uninstall order, where charts are uninstalled by weight in descending order with higher weights first. **Supported values:** Positive or negative integers. **Default:** `0` | |||
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('are installed').
| @@ -1,7 +1,3 @@ | |||
| Specifies the order in which Helm charts are installed within the application. Charts are installed by weight in ascending order, with lower weights installed first. **Supported values:** Positive or negative integers. **Default:** `0` | |||
| Specifies the installation order of the Helm charts in the release. Charts are installed by weight in ascending order with lower weights first. Also determines the uninstall order, where charts are uninstalled by weight in descending order with higher weights first. **Supported values:** Positive or negative integers. **Default:** `0` | |||
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('are uninstalled').
| @@ -1,3 +1,5 @@ | |||
| You cannot migrate existing Helm charts in existing installations from the `useHelmInstall: false` installation method to a different method. If KOTS already installed the Helm chart previously in the environment using a HelmChart custom resource with `apiVersion: kots.io/v1beta1` and `useHelmInstall: false`, then KOTS does not attempt to install the chart using a different method and displays the following error message: `Deployment method for chart <chart_name> has changed`. | |||
| You cannot migrate Helm charts in existing installations from the `useHelmInstall: false` installation method to a different method. | |||
| If a user previously installed the Helm chart using `apiVersion: kots.io/v1beta1` and `useHelmInstall: false`, the installer won't attempt to use a different installation method. | |||
Contributor
There was a problem hiding this comment.
[Replicated.Timeless] Avoid temporal words like 'won't'.
paigecalvert
changed the title
paigecalvert
commented
May 12, 2026
| @@ -1,4 +1,5 @@ | |||
| The `namespace` key specifies an alternative namespace where Replicated KOTS installs the Helm chart. **Default:** The Helm chart is installed in the same namespace as the Admin Console. The `namespace` attribute can be parsed by template functions. For more information about template functions, see [About template function contexts](template-functions-about). | |||
| The `namespace` key specifies an alternative namespace to install the Helm chart. By default, for Embedded Cluster v2 and KOTS existing cluster installations, KOTS installs the Helm chart in the same namespace as the Admin Console. For Embedded Cluster v3 installations, Embedded Cluster installs the chart in a `<chart-name>` namespace by default. | |||
Contributor
Author
There was a problem hiding this comment.
For Embedded Cluster v3 installations, Embedded Cluster installs the chart in a
<chart-name>namespace by default.
is that true?
paigecalvert
commented
May 12, 2026
| Template functions can parse the `namespace` attribute. For more information about template functions, see [About Replicated template functions](/reference/template-functions-about). | ||
|
|
||
| If you specify a namespace in the HelmChart `namespace` field, you must also include the same namespace in the `additionalNamespaces` field of the Application custom resource manifest file. KOTS creates the namespaces listed in the `additionalNamespaces` field during installation. For more information, see [additionalNamespaces](custom-resource-application#additionalnamespaces) in the _Application_ reference. No newline at end of file | ||
| If you specify a namespace in the HelmChart `namespace` field, you must also include the same namespace in the [additionalNamespaces](custom-resource-application#additionalnamespaces) field of the Application custom resource. |
Contributor
Author
There was a problem hiding this comment.
If you specify a namespace in the HelmChart
namespacefield, you must also include the same namespace in the additionalNamespaces field of the Application custom resource.
is that true for ec v3 as well?
paigecalvert
commented
May 12, 2026
| @@ -1,8 +1,14 @@ | |||
| Specifies additional flags to pass to the `helm upgrade` command for charts. These flags are passed in addition to any flags Replicated KOTS passes by default. The values specified here take precedence if KOTS already passes the same flag. The `helmUpgradeFlags` attribute can be parsed by template functions. For more information about template functions, see [About template function contexts](template-functions-about). | |||
| Specifies additional flags to pass to the `helm upgrade` command. | |||
| The Replicated installer runs `helm upgrade` for _all_ deployments, not just upgrades, by specifying the `--install` flag. | |||
Contributor
Author
There was a problem hiding this comment.
The Replicated installer runs
helm upgradefor all deployments, not just upgrades, by specifying the--installflag.
is this true for ec v3 as well?
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
2 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.
https://deploy-preview-4061--replicated-docs-upgrade.netlify.app/reference/custom-resource-helmchart-v2