Skip to content

Commit 1867f2a

Browse files
paigecalvertpaigecalvert
committed
edits
1 parent 3ecb8f2 commit 1867f2a

File tree

4 files changed

+89
-27
lines changed

4 files changed

+89
-27
lines changed

‎docs/enterprise/installing-embedded-automation.mdx‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
import ConfigValuesExample from "../partials/configValues/_configValuesExample.mdx"
22
import ConfigValuesProcedure from "../partials/configValues/_config-values-procedure.mdx"
3+
import ConfigValuesRequirements from "../partials/configValues/_requirements.mdx"
34

45
# Automate Installation with Embedded Cluster
56

@@ -13,12 +14,18 @@ With headless installation, you provide all the necessary installation assets, s
1314

1415
## Prerequisite
1516

16-
Create a ConfigValues YAML file to define the configuration values for the application release. The ConfigValues file allows you to pass the configuration values for an application from the command line with the install command, rather than through the Admin Console UI. For air-gapped environments, ensure that the ConfigValues file can be accessed from the installation environment.
17+
Create a Replicated KOTS ConfigValues resource to define the configuration values for the application. The ConfigValues resource allows you to pass the configuration values for an application from the command line with the install command, rather than through the Admin Console UI. For air-gapped environments, ensure that the ConfigValues file can be accessed from the installation environment.
1718

18-
The KOTS ConfigValues file includes the fields that are defined in the KOTS Config custom resource for an application release, along with the user-supplied and default values for each field, as shown in the example below:
19+
The ConfigValues resource includes the fields that are defined in the Replicated KOTS Config custom resource for the release, along with the user-supplied and default values for each field, as shown in the example below:
1920

2021
<ConfigValuesExample/>
2122

23+
#### ConfigValues Requirements
24+
25+
<ConfigValuesRequirements/>
26+
27+
For more information, see [ConfigValues](/reference/custom-resource-configvalues).
28+
2229
## Limtiation
2330

2431
Automating deployment with Embedded Cluster is supported only for the initial installation. Performing automated (headless) updates of existing installations with Embedded Cluster is not supported. For information about how to update an existing installation through the Admin Console UI, see [Perform Updates in Embedded Clusters](/enterprise/updating-embedded).

‎docs/partials/configValues/_configValuesExample.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ spec:
99
boolean_config_item_name:
1010
value: "1"
1111
password_config_item_name:
12-
valuePlaintext: exampleplaintextpassword
12+
valuePlainText: exampleplaintextpassword
1313
select_one_config_item_name:
1414
default: default_option_name
1515
value: selected_option_name

‎docs/partials/configValues/_requirements.mdx‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
1-
The ConfigValues resource passed to the install command must meet the following requirements:
2-
* Must be valid YAML
3-
* Must list all configuration items that are defined in the corresponding Config resource in the release
4-
* For each item in the Config resource that has a default, the ConfigValues must also list the item's default. Default values are not automatically merged from the Config resource during installation.
5-
* For any configuration items of type `password`, provide the password in plain text in a `valuePlainText` property rather than in the `value` property. For example, `valuePlainText: somesecretvalue`.
1+
The ConfigValues resource must meet the following requirements:
2+
* Must be valid YAML.
3+
* Must list all configuration items that are defined in the corresponding Config resource in the release, except any items with the [`hidden`](/reference/custom-resource-config#hidden) or [`readonly`](/reference/custom-resource-config#readonly) properties set to true.
4+
* For each configuration item in the Config resource that has a default value set, the ConfigValues must also list the default in the `default` property. Defaults are not automatically merged from the Config resource during installation.
5+
* For any configuration items of type [`password`](/reference/custom-resource-config#password), set the password in plain text in a `valuePlainText` property rather than in the `value` property. For example, `valuePlainText: somesecretvalue`. Values set in `valuePlainText` are encrypted during installation.
6+
* All values must be strings. For booleans or integers, use quotes (for example, `value: "1"`, `value: "0"`, or `value: "443"`).

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

Lines changed: 73 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,21 @@
11
import ConfigValuesExample from "../partials/configValues/_configValuesExample.mdx"
2+
import ConfigValuesRequirements from "../partials/configValues/_requirements.mdx"
23

34
# ConfigValues
45

5-
This topic describes the Replicated KOTS ConfigValues custom resource. ConfigValues is used to provide application configuration values during automated or headless installations with the CLI.
6+
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.
7+
8+
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).
69

710
## Overview
811

9-
The ConfigValues resource lists the values and defaults set for each application configuration item defined in the Replicated KOTS Config custom resource in the release. For more information about the Config custom resource, see [Config](custom-resource-config).
12+
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.
1013

11-
For each installation, the Admin Console automatically generates a ConfigValues resource and makes it available for download in the **View files** tab.
14+
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).
1215

13-
In automated or headless installs from the command line, end users must pass a ConfigValues resource to the install command to provide application configuration values to the Admin Console. For more information about performing headless installations, see [Automate Embedded Cluster Installations](/enterprise/installing-embedded-automation) and [Automate Existing Cluster Installations with the KOTS CLI](/enterprise/installing-existing-cluster-automation).
16+
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.
1417

15-
The following image shows how application configuration items defined a Config resource are represented in a ConfigValues resource:
18+
The following image shows how application configuration items defined a Config resource map to a ConfigValues resource:
1619

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

@@ -22,33 +25,84 @@ As shown in the image above, the ConfigValues resource `values` key lists each i
2225

2326
## Example
2427

25-
The following shows an example of a ConfigValues resource that can be provided during automated or headless installation from the command line:
26-
2728
<ConfigValuesExample/>
2829

30+
## Requirements
31+
32+
<ConfigValuesRequirements/>
33+
2934
## Spec
3035

3136
### values.[item_name].default
3237

33-
The `default` value that was defined for the item in the Config custom resource in the release.
34-
35-
When creating a ConfigValues to perform a headless installation from the command line, the `default` value must match the default that was defined in the Config custom resource.
38+
The item's default value, as defined in the [Config](custom-resource-config) custom resource in the release.
39+
40+
#### Example
41+
42+
```yaml
43+
apiVersion: kots.io/v1beta1
44+
kind: ConfigValues
45+
spec:
46+
values:
47+
certificate_source:
48+
default: generate_internal
49+
deploy_postgres:
50+
default: "1"
51+
value: "0"
52+
service_type:
53+
default: cluster_ip
54+
value: node_port
55+
node_port_port:
56+
default: "443"
57+
value: "3000"
58+
```
3659
3760
### values.[item_name].value
3861
39-
The value for the item. This is either a user-supplied value or a value rendered by a Replicated template function used in the Config custom resource.
40-
41-
For user-supplied values, the value must meet the following requirements:
42-
* The value must For example, if the item includes a `validation` field with regex, then the value supplied must match the regex pattern.
43-
* For `select_one` items, the value must match the name of one of the options defined in the Config custom resource
44-
* All required config items must have a default or a value supplied
62+
The user-supplied value for the application configuration item.
63+
64+
:::note
65+
In the ConfigValues resource that is automatically generated by the Admin Console as part of installation, the `value` property might also be set to a value rendered by a Replicated template function. For example, a [`hidden`](/reference/custom-resource-config#hidden) item defined in the Config resource might use the Replicated RandomString template function to set the value with `value: repl{{ RandomString 40}}`.
66+
:::
67+
68+
#### Example
69+
70+
```yaml
71+
apiVersion: kots.io/v1beta1
72+
kind: ConfigValues
73+
spec:
74+
values:
75+
slack_clientid:
76+
value: T057KR02S
77+
slackernews_domain:
78+
value: hello.ingress.replicatedcluster.com
79+
service_type:
80+
value: node_port
81+
node_port_port:
82+
value: "443"
83+
```
4584

4685
### values.[item_name].valuePlainText
4786

48-
When creating a ConfigValues to provide during a headless install from the command line, users must include the `valuePlainText` field to provide values for `password` config items.
87+
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.
4988

50-
The following shows an example of how a `valuesPlainText` field in a user-supplied ConfigValues is rendered in a post-installation ConfigValues generated by the Admin Console:
89+
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 during installation:
5190

5291
![valuesPlainText field in ConfigValues](/images/configvalues-plaintext.png)
5392

54-
[View a larger version of this image](/images/configvalues-plaintext.png)
93+
[View a larger version of this image](/images/configvalues-plaintext.png)
94+
95+
#### Example
96+
97+
```yaml
98+
apiVersion: kots.io/v1beta1
99+
kind: ConfigValues
100+
spec:
101+
values:
102+
slack_bot_token:
103+
valuePlainText: examplebottoken
104+
slack_clientsecret:
105+
valuePlainText: exampleclientsecret
106+
slack_user_token:
107+
valuePlainText: exampleusertoken
108+
```

0 commit comments

Comments
 (0)