Add ConfigValues reference topic #3510
There are no files selected for viewing
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
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
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
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. | ||
|
There was a problem hiding this comment. 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). There was a problem hiding this comment. Asking eng for clarification: https://replicated.slack.com/archives/C036BTS7JCE/p1757014567063689 There was a problem hiding this comment. 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 |
||
| * 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 any configuration items of type [`password`](/reference/custom-resource-config#password) defined in the Config resource, set the value in plain text in the ConfigValues [`valuePlainText`](/reference/custom-resource-configvalues#valueplaintext) property rather than in the `value` property. For example, `valuePlainText: somesecretvalue`. Values set in `valuePlainText` are automatically encrypted during installation. | ||
| * All values must be strings. For booleans, integers, or floats, wrap the value in quotes (for example, `value: "1"`, `value: "0"`, or `value: "443"`). | ||
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,126 @@ | ||
| import ConfigValuesExample from "../partials/configValues/_configValuesExample.mdx" | ||
| import ConfigValuesRequirements from "../partials/configValues/_requirements.mdx" | ||
| import GetConfigValues from "../partials/configValues/_config-values-procedure.mdx" | ||
|
|
||
| # ConfigValues | ||
|
There was a problem hiding this comment. ^ new reference topic that describes the ConfigValues, including info about the spec, examples, info about downloading the generated ConfigValues, requirements, and limitations |
||
|
|
||
| This topic describes the Replicated KOTS ConfigValues resource. ConfigValues is used to set application configuration values during automated or headless installations from the command line. | ||
|
|
||
| For information about the Replicated KOTS Config custom resource, which is used to customize the application-specific configuration fields on the Admin Console config screen, see [Config](custom-resource-config). | ||
|
|
||
| ## Overview | ||
|
|
||
| The ConfigValues resource lists the values and defaults for each application configuration item defined in the Replicated KOTS [Config](custom-resource-config) resource in the release. | ||
|
|
||
| In automated or headless installations, end users provide a ConfigValues resource with the install command to set the application configuration values from the command line rather than through the Admin Console UI. For more information about performing headless installations with Replicated Embedded Cluster, see [Automate Embedded Cluster Installations](/enterprise/installing-embedded-automation). For information about performing headless installations with KOTS in an existing cluster, see [Install with the KOTS CLI](/enterprise/installing-existing-cluster-automation). | ||
|
|
||
| Additionally, 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. For more information, see [Download the ConfigValues for an Installation](#download) below. | ||
|
|
||
| The following image shows how application configuration items defined a Config resource map to a ConfigValues resource: | ||
|
|
||
|  | ||
|
There was a problem hiding this comment. ^ added a couple new visuals to help show how the configvalues works |
||
|
|
||
| [View a larger version of this image](/images/configvalues-diagram.png) | ||
|
|
||
| As shown in the image above, the ConfigValues resource `values` key lists each item from the Config resource by its `name`. For each item, the ConfigValues resource lists the user-supplied value as well as the default that was defined in the Config resource (if applicable). | ||
paigecalvert marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| ## Example | ||
|
|
||
| <ConfigValuesExample/> | ||
|
|
||
| ## Requirements | ||
|
|
||
| <ConfigValuesRequirements/> | ||
|
|
||
| ## Limitation | ||
|
|
||
| Replicated template functions are not supported in the ConfigValues resource. To set an application configuration item to a value rendered by a template function, you can use a template function in the `default` or `value` property for the item in the [Config](custom-resource-config) resource. | ||
|
|
||
| For more information about working with Replicated template functions, see [About Template Functions](/reference/template-functions-about). | ||
|
|
||
| ## Spec | ||
|
|
||
| ### values.[item_name].default | ||
|
|
||
| The item's default value, as defined in the [Config](custom-resource-config) custom resource in the release. | ||
|
|
||
| #### Example | ||
|
|
||
| ```yaml | ||
| apiVersion: kots.io/v1beta1 | ||
| kind: ConfigValues | ||
| spec: | ||
| values: | ||
| certificate_source: | ||
| default: generate_internal | ||
| deploy_postgres: | ||
| default: "1" | ||
| value: "0" | ||
| service_type: | ||
| default: cluster_ip | ||
| value: node_port | ||
| node_port_port: | ||
| default: "443" | ||
| value: "3000" | ||
| ``` | ||
| ### values.[item_name].value | ||
| The user-supplied value for the application configuration item. | ||
| #### Example | ||
| ```yaml | ||
| apiVersion: kots.io/v1beta1 | ||
| kind: ConfigValues | ||
| spec: | ||
| values: | ||
| slack_clientid: | ||
| value: T057KR02S | ||
| slackernews_domain: | ||
| value: hello.ingress.replicatedcluster.com | ||
| slackernews_admin_user_emails: | ||
| value: [email protected], [email protected], [email protected] | ||
| service_type: | ||
| value: node_port | ||
| node_port_port: | ||
| value: "443" | ||
| ``` | ||
| :::note | ||
| In the ConfigValues resource that is automatically generated by the Admin Console as part of installation, the `value` property might also be set to one of the following: | ||
| * 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 `{}`. | ||
| ::: | ||
|
There was a problem hiding this comment. ^ I added this note to explain how you might see some values that are not "user-supplied" in the |
||
|
|
||
| ### 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. | ||
|
There was a problem hiding this comment. ^ explaining how you have to set passwords with valuePlainText |
||
|
|
||
| During installation, the Admin Console encrypts the values set in `valuePlainText`. In the ConfigValues resource that is automatically generated as part of installation, these encrypted values are saved in `value` properties. The image below shows how a `valuePlainText` value is encrypted and added to a `value` property during installation: | ||
|
|
||
|  | ||
|
|
||
| [View a larger version of this image](/images/configvalues-plaintext.png) | ||
|
|
||
| #### Example | ||
|
|
||
| ```yaml | ||
| apiVersion: kots.io/v1beta1 | ||
| kind: ConfigValues | ||
| spec: | ||
| values: | ||
| slack_bot_token: | ||
| valuePlainText: examplebottoken | ||
| slack_clientsecret: | ||
| valuePlainText: exampleclientsecret | ||
| slack_user_token: | ||
| valuePlainText: exampleusertoken | ||
| ``` | ||
|
|
||
| ## Download the ConfigValues for an Installation {#download} | ||
|
|
||
| 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/> | ||
|
There was a problem hiding this comment. ^ 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 |
||
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
|
There was a problem hiding this comment. goal was to show mapping between an item in the Config resource and how you can set it in the ConfigValues |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
|
There was a problem hiding this comment. 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 |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
^ 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