Make Config and ConfigValues content work for EC v3#4039
Conversation
✅ 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}
| # ConfigValues | ||
|
|
||
| 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. | ||
| This topic describes the Replicated ConfigValues resource. ConfigValues is used to set application configuration values during automated or headless installations from the command line. |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('is used').
| 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 [Online installation with Embedded Cluster](/embedded-cluster/v3/installing-embedded). 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. | ||
| 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 UI. |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.SentenceLength] Try to keep your sentence length to 26 words or fewer.
| ``` | ||
|
|
||
| ## Download the ConfigValues for an Installation {#download} | ||
| ## (KOTS Existing Cluster Only) Download the ConfigValues for an installation {#download} |
There was a problem hiding this comment.
[Replicated.Headings] '(KOTS Existing Cluster Only) Download the ConfigValues for an installation ***********' should use sentence case.
| # Config | ||
|
|
||
| The Config custom resource can be provided by a vendor to specify a Config page in the Replicated Admin Console for collecting customer supplied values and template function rendering. | ||
| The Replicated Config custom resource defines the application-specific configuration fields that you want to expose to your end customers. For example, if you let your customers bring their own external database for your application, you could expose config fields for the database host, port, and username, and password. |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.SentenceLength] Try to keep your sentence length to 26 words or fewer.
| ## Example | ||
|
|
||
| For more information about the properties of groups and items, see [Group Properties](#group-properties) and [Item Properties](#item-properties) below. | ||
| The following example shows three groups defined in the Config custom resource manifest file, and how these groups are displayed on the config screen. |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('are displayed').
| > Introduced in KOTS v1.114.0 | ||
|
|
||
| The `radio` item type includes one or more nested items that are displayed as radio buttons on the Admin Console config screen. Radio buttons are especially useful for displaying short lists of options. You can also use the [`dropdown`](#dropdown) item type for items with longer lists of options. | ||
| The `radio` item type includes one or more nested items that are displayed as radio buttons on the config screen. Radio buttons are especially useful for displaying short lists of options. You can also use the [`dropdown`](#dropdown) item type for items with longer lists of options. |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('are displayed').
| ::: | ||
|
|
||
| `select_one` items must contain nested items. The nested items are displayed as radio buttons in the Admin Console. | ||
| `select_one` items must contain nested items. The nested items are displayed as radio buttons on the config screen. |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('are displayed').
| ## Repeatable Examples | ||
|
|
||
| In these examples, the default service port of "80" is included with the release. Port 443 is added as an additional port on the Admin Console configuration page, which is stored in the ConfigValues file. | ||
| In these examples, the default service port of "80" is included with the release. Port 443 is added as an additional port on the config screen, which is stored in the ConfigValues file. |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('is included').
| ## Repeatable Examples | ||
|
|
||
| In these examples, the default service port of "80" is included with the release. Port 443 is added as an additional port on the Admin Console configuration page, which is stored in the ConfigValues file. | ||
| In these examples, the default service port of "80" is included with the release. Port 443 is added as an additional port on the config screen, which is stored in the ConfigValues file. |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('is added').
| ## Repeatable Examples | ||
|
|
||
| In these examples, the default service port of "80" is included with the release. Port 443 is added as an additional port on the Admin Console configuration page, which is stored in the ConfigValues file. | ||
| In these examples, the default service port of "80" is included with the release. Port 443 is added as an additional port on the config screen, which is stored in the ConfigValues file. |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('is stored').
| :::note | ||
| When you assign a template function that generates a value to a `value` property, you can use the `readonly` and `hidden` properties to define whether or not the generated value is ephemeral or persistent between changes to the configuration settings for the application. For more information, see [RandomString](template-functions-static-context#randomstring) in _Static Context_. | ||
| ::: No newline at end of file | ||
| When you assign a template function that generates a value to a `value` property, you can use the `readonly` and `hidden` properties to define whether or not the generated value is ephemeral or persistent between changes to the configuration settings for the application. For more information, see [RandomString](template-functions-static-context#randomstring) in _Static Context_. No newline at end of file |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.SentenceLength] Try to keep your sentence length to 26 words or fewer.
|  | ||
| <img width="650px" alt="Text area field on the configuration screen" src="/images/config-screen-textarea.png"/> | ||
|
|
||
| ## Item Properties |
There was a problem hiding this comment.
[Replicated.Headings] 'Item Properties' should use sentence case.
|
|
||
| ### `affix` | ||
|
|
||
| Items can be affixed `left` or `right`. Affixing items allows them to appear on the config screen on the same line. |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('be affixed').
|
|
||
| ### `default` | ||
|
|
||
| Defines the default value for the config item. If the user does not provide a value for the item, then the `default` value is applied. |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('is applied').
| If the `default` value is not associated with a `password` type config item, then it appears as placeholder text on the config screen. | ||
|
|
||
| A `validation` can be specified to validate the value of an item. `regex` is the supported validation type. | ||
| Any Go template functions that you use in the `default` property are reevaluated every time the user makes a change to their configuration settings for the application. |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('are reevaluated').
| #### Example | ||
|
|
||
| Validates and returns if `password` value is not matching the regex. | ||
| The `jwt_token` file content is only validated if the file is uploaded since it is optional. |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('is uploaded').
| ``` | ||
|
|
||
| ## Repeatable Examples | ||
| ### Repeatable Examples |
There was a problem hiding this comment.
[Replicated.Headings] 'Repeatable Examples' should use sentence case.
| In these examples, the default service port of "80" is included with the release. Port 443 is added as an additional port on the config screen, which is stored in the ConfigValues file. | ||
|
|
||
| ### Repeatable Item Example for a yamlPath | ||
| #### Repeatable Item Example for a yamlPath |
There was a problem hiding this comment.
[Replicated.Headings] 'Repeatable Item Example for a yamlPath' should use sentence case.
| In these examples, the default service port of "80" is included with the release. Port 443 is added as an additional port on the config screen, which is stored in the ConfigValues file. | ||
|
|
||
| ### Repeatable Item Example for a yamlPath | ||
| #### Repeatable Item Example for a yamlPath |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'yamlPath'?
| ``` | ||
|
|
||
| ### Repeatable Item Example for an Entire Document | ||
| #### Repeatable Item Example for an Entire Document |
There was a problem hiding this comment.
[Replicated.Headings] 'Repeatable Item Example for an Entire Document' should use sentence case.
| This lets you conditionally show or hide fields so your end customers only see the options that are relevant to them. | ||
|
|
||
| You can construct conditional statements in the `when` property using Replicated template functions. Replicated template functions are a set of custom template functions based on the Go text/template library. For more information, see [About Replicated Template Functions](/reference/template-functions-about). No newline at end of file | ||
| You can use Go template functions to create conditional statements. Replicated provides a set of Go template functions that you can use to evaluate conditions like the user's environment, their license entitlements, and their previous configuration choices. For more information, see [About Replicated Template Functions](/reference/template-functions-about). |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.SentenceLength] Try to keep your sentence length to 26 words or fewer.
| ``` | ||
|  | ||
| [View a larger version of this image](/images/config-screen-groups.png) | ||
| The following images show this Config custom resource is rendered in the Embedded Cluster v3 installation wizard: |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('is rendered').
| Descriptive help text for the group that displays on the Admin Console Config page. Supports markdown formatting. | ||
|
|
||
| To provide help text for individual items on the Config page, use the item `help_text` property. See [help_text](#help_text) below. | ||
| Descriptive help text for the group that displays on the config screen. Supports markdown formatting. To provide help text for individual items on the Config page, use the item `help_text` property. See [help_text](#help_text) below. |
There was a problem hiding this comment.
[Replicated.PositionalLanguage] Avoid spacial and directional language like 'below'. Instead, use 'on this page', 'the following', or link to the section.
| For more information about working with Replicated template functions, see [About Replicated Template Functions](/reference/template-functions-about). | ||
|
|
||
| ## Spec | ||
| ## ConfigValues Spec |
There was a problem hiding this comment.
[Replicated.Headings] 'ConfigValues Spec' should use sentence case.
|
|
||
| :::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: | ||
| For KOTS or Embedded Cluster v2 installations, the `value` property in the auto-generated ConfigValues might also be set to one of the following: |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('be set').
| 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. | ||
|
|
||
| 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: | ||
| During installation, the installer 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: |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('are saved').
| 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. | ||
|
|
||
| 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: | ||
| During installation, the installer 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: |
There was a problem hiding this comment.
[Replicated.PositionalLanguage] Avoid spacial and directional language like 'below'. Instead, use 'on this page', 'the following', or link to the section.
| 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. | ||
|
|
||
| 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: | ||
| During installation, the installer 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: |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('is encrypted').
|
|
||
| :::important | ||
| The `select_one` item type is deprecated and is replaced by [`radio`](#radio). | ||
| The `select_one` item type is deprecated. Use [`radio`](#radio) instead. |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('is deprecated').
|
|
||
| :::important | ||
| Do not store secrets or passwords in `text` items because they are not encrypted or masked and can be easily accessed. Instead, use [`password`](#password) items. | ||
| Do not store secrets or passwords in `text` items because they are not encrypted or masked and can be accessed. Instead, use [`password`](#password) items. |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Replicated.Passive] In general, use active voice instead of passive voice ('be accessed').
|
|
||
| ### `help_text` | ||
|
|
||
| Displays a helpful message under the `title` for the config item on the config screen. |
There was a problem hiding this comment.
[Replicated.PositionalLanguage] Avoid spacial and directional language like 'under'. Instead, use 'on this page', 'the following', or link to the section.
| #### Requirements | ||
|
|
||
| <WhenRequirements/> | ||
| - Do not apply `when` to items nested under a `radio`, `dropdown`, or `select_one` item. To conditionally show or hide `radio`, `dropdown`, or `select_one` items, apply the `when` property to the item itself. |
There was a problem hiding this comment.
[Replicated.PositionalLanguage] Avoid spacial and directional language like 'under'. Instead, use 'on this page', 'the following', or link to the section.
2 participants
No description provided.