Add ConfigValues reference topic #3510

paigecalvert · 2025-09-03T17:12:08Z

https://deploy-preview-3510--replicated-docs-upgrade.netlify.app/reference/custom-resource-configvalues

netlify · 2025-09-03T17:12:14Z

✅ Deploy Preview for replicated-docs-upgrade ready!

Name	Link
🔨 Latest commit	`fd5b66b`
🔍 Latest deploy log	https://app.netlify.com/projects/replicated-docs-upgrade/deploys/68bb1a0f33540500087d5dac
😎 Deploy Preview	https://deploy-preview-3510--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.

netlify · 2025-09-03T17:12:14Z

✅ Deploy Preview for replicated-docs ready!

Name	Link
🔨 Latest commit	`fd5b66b`
🔍 Latest deploy log	https://app.netlify.com/projects/replicated-docs/deploys/68bb1a0fba7a10000831f220
😎 Deploy Preview	https://deploy-preview-3510--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.

paigecalvert · 2025-09-04T18:51:42Z

docs/partials/configValues/_requirements.mdx

@@ -0,0 +1,6 @@
+The ConfigValues resource must meet the following requirements:
+* Must be valid YAML.
+* It is not necessary to set a `value` for each configuration item in the ConfigValues, unless the item is [`required`](/reference/custom-resource-config#required) and has no [`default`](/reference/custom-resource-config#default) set in the Config resource.


It is not necessary to set a value for each configuration item in the ConfigValues, unless the item is required and has no default set in the Config resource.

I'm not super confident about this one. In https://github.com/replicated-collab/pixee-replicated/issues/75#issuecomment-3063546723, Ethan says "all KOTS requires that all values and defaults are set." When I tested an install of slackernews excluding several fields from the ConfigValues, it seems to install fine (as long as those items weren't required).

Asking eng for clarification: https://replicated.slack.com/archives/C036BTS7JCE/p1757014567063689

Update: seems like there might be fewer requirements. When testing, I could get an install to succeed by passing a ConfigValues with only the required items set

paigecalvert · 2025-09-04T18:54:19Z

docs/partials/configValues/_requirements.mdx

+The ConfigValues resource must meet the following requirements:
+* Must be valid YAML.
+* It is not necessary to set a `value` for each configuration item in the ConfigValues, unless the item is [`required`](/reference/custom-resource-config#required) and has no [`default`](/reference/custom-resource-config#default) set in the Config resource.
+* For each configuration item defined in the Config resource that has a [`default`](/reference/custom-resource-config#default) set, the ConfigValues must also list the default in the `default` property. Defaults are not automatically merged from the Config resource during installation.


For each configuration item defined in the Config resource that has a default set, the ConfigValues must also list the default in the default property. Defaults are not automatically merged from the Config resource during installation.

Similar to above, I got this from https://github.com/replicated-collab/pixee-replicated/issues/75#issuecomment-3063546723. With my slackernews test, I excluded the node_port_port config item from the ConfigValues (which has a default set to 443), and the field as well as the 443 default both appeared in the ConfigValues that was generated for the release.

Asking eng for clarification: https://replicated.slack.com/archives/C036BTS7JCE/p1757014567063689

paigecalvert · 2025-09-04T19:00:16Z

docs/partials/configValues/_configValuesExample.mdx

+      valuePlainText: exampleplaintextpassword
+    select_one_config_item_name:
+      default: default_option_name
+      value: selected_option_name  


made a few edits to the existing examples. adds some new fields and updates the placeholder language/formatting

paigecalvert · 2025-09-04T19:01:50Z

docs/reference/custom-resource-configvalues.mdx

+* A value rendered by a Replicated template function. For example, a [`hidden`](/reference/custom-resource-config#hidden) item defined in the Config resource could use the Replicated [RandomString](/reference/template-functions-static-context#randomstring) template function to set the value with `value: repl{{ RandomString 40}}`. In this case, the value for the item in the ConfigValues would be generated by the template function and not user-supplied. For more information about using Replicated template functions, see [About Template Functions](/reference/template-functions-about).
+* An encrypted empty string. For any `password` configuration items without a user-supplied value, the Admin Console sets the value to an empty string. In the ConfigValues generated for the installation, this empty string is automatically encrypted.
+* An empty mapping (`{}`). For configuration items without a user-supplied `value` or a `default` set, the value is set to `{}`.
+:::


^ I added this note to explain how you might see some values that are not "user-supplied" in the value property if you download the ConfigValues from the Admin Console/CLI after install. The encrypted empty string one comes from https://github.com/replicated-collab/pixee-replicated/issues/75#issuecomment-3090171435

paigecalvert · 2025-09-04T19:12:41Z

docs/enterprise/installing-embedded-automation.mdx

+
+<ConfigValuesRequirements/>
+
+For more information, see [ConfigValues](/reference/custom-resource-configvalues).


^ Added the new list of requirements as well as a link to the new ConfigValues page to the prereqs in the EC and KOTS automated install topics

paigecalvert · 2025-09-04T19:13:41Z

docs/reference/custom-resource-configvalues.mdx

+import ConfigValuesRequirements from "../partials/configValues/_requirements.mdx"
+import GetConfigValues from "../partials/configValues/_config-values-procedure.mdx"
+
+# ConfigValues


^ new reference topic that describes the ConfigValues, including info about the spec, examples, info about downloading the generated ConfigValues, requirements, and limitations

paigecalvert · 2025-09-04T19:14:21Z

docs/reference/custom-resource-configvalues.mdx

+
+### values.[item_name].valuePlainText {#valueplaintext}
+
+A plain text value. For any configuration items of type [`password`](/reference/custom-resource-config#password), the password must be provided in plain text in a `valuePlainText` property rather than in the `value` property.


^ explaining how you have to set passwords with valuePlainText

paigecalvert · 2025-09-04T19:15:08Z

docs/reference/custom-resource-configvalues.mdx

+
+For each installation, the Admin Console automatically generates a ConfigValues resource and makes it available for download in the Admin Console **View files** tab or with the [`kots get config`](/reference/kots-cli-get-config) command.
+
+<GetConfigValues/>


^ this was an existing procedure, but it was only being used in the KOTS existing cluster automated/headless install page. Moving it over here so it can be linked to from a logical location

paigecalvert · 2025-09-04T19:15:39Z

static/images/configvalues-diagram.png

goal was to show mapping between an item in the Config resource and how you can set it in the ConfigValues

paigecalvert · 2025-09-04T19:16:16Z

static/images/configvalues-plaintext.png

goal was to show how a password value that's set in plain text in the user-supplied ConfigValues gets rendered in the ConfigValues generated by the Admin Console post install

paigecalvert · 2025-09-04T19:17:17Z

docs/reference/custom-resource-configvalues.mdx

+
+The following image shows how application configuration items defined a Config resource map to a ConfigValues resource:
+
+![Config fields mapped from Config resource to ConfigValues resource](/images/configvalues-diagram.png)


^ added a couple new visuals to help show how the configvalues works

these were nice

docs/reference/custom-resource-configvalues.mdx

ajp-io · 2025-09-05T14:25:59Z

docs/reference/custom-resource-configvalues.mdx

+
+The following image shows how application configuration items defined a Config resource map to a ConfigValues resource:
+
+![Config fields mapped from Config resource to ConfigValues resource](/images/configvalues-diagram.png)


these were nice

Co-authored-by: Alex Parker <[email protected]>

paigecalvert added 2 commits August 26, 2025 09:14

adding configvalues

cbd264b

Add ConfigValues reference topic

20e0a9f

paigecalvert requested a review from a team as a code owner September 3, 2025 17:12

paigecalvert changed the title ~~128361~~ Add ConfigValues reference topic Sep 3, 2025

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

paigecalvert added 8 commits September 3, 2025 16:10

edits

7c962a9

edits

aba140f

add requirements for configvalues

3ecb8f2

edits

1867f2a

edits

8c9f52c

edits

6956999

edits

360a029

edit

ec7406d

paigecalvert commented Sep 4, 2025

View reviewed changes

edits

c4e58b7

paigecalvert commented Sep 4, 2025

View reviewed changes

ajp-io reviewed Sep 5, 2025

View reviewed changes

Update docs/reference/custom-resource-configvalues.mdx

b6d592b

Co-authored-by: Alex Parker <[email protected]>

edit requirements

fd5b66b


		<ConfigValuesRequirements/>

		For more information, see [ConfigValues](/reference/custom-resource-configvalues).


		### values.[item_name].valuePlainText {#valueplaintext}

		A plain text value. For any configuration items of type [`password`](/reference/custom-resource-config#password), the password must be provided in plain text in a `valuePlainText` property rather than in the `value` property.


		For each installation, the Admin Console automatically generates a ConfigValues resource and makes it available for download in the Admin Console View files tab or with the [`kots get config`](/reference/kots-cli-get-config) command.

		<GetConfigValues/>


		The following image shows how application configuration items defined a Config resource map to a ConfigValues resource:

		![Config fields mapped from Config resource to ConfigValues resource](/images/configvalues-diagram.png)

Add ConfigValues reference topic #3510

Are you sure you want to change the base?

Add ConfigValues reference topic #3510

Uh oh!

Conversation

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

Uh oh!

Uh oh!

netlify bot commented Sep 3, 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!

netlify bot commented Sep 3, 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!

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 Sep 4, 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!

paigecalvert Sep 4, 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 Sep 4, 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!

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!

Uh oh!

paigecalvert commented Sep 3, 2025 •

edited

Loading

netlify bot commented Sep 3, 2025 •

edited

Loading

netlify bot commented Sep 3, 2025 •

edited

Loading

paigecalvert Sep 4, 2025 •

edited

Loading

paigecalvert Sep 4, 2025 •

edited

Loading

paigecalvert Sep 4, 2025 •

edited

Loading