diff --git a/docs/enterprise/installing-embedded-automation.mdx b/docs/enterprise/installing-embedded-automation.mdx index b08ffc1121..3b05284205 100644 --- a/docs/enterprise/installing-embedded-automation.mdx +++ b/docs/enterprise/installing-embedded-automation.mdx @@ -1,5 +1,6 @@ import ConfigValuesExample from "../partials/configValues/_configValuesExample.mdx" import ConfigValuesProcedure from "../partials/configValues/_config-values-procedure.mdx" +import ConfigValuesRequirements from "../partials/configValues/_requirements.mdx" # Automate Installation with Embedded Cluster @@ -13,12 +14,18 @@ With headless installation, you provide all the necessary installation assets, s ## Prerequisite -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. +Create a 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. -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: +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: +#### ConfigValues Requirements + + + +For more information, see [ConfigValues](/reference/custom-resource-configvalues). + ## Limtiation 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). diff --git a/docs/enterprise/installing-existing-cluster-automation.mdx b/docs/enterprise/installing-existing-cluster-automation.mdx index 708ebb1013..56440f926e 100644 --- a/docs/enterprise/installing-existing-cluster-automation.mdx +++ b/docs/enterprise/installing-existing-cluster-automation.mdx @@ -1,5 +1,5 @@ import ConfigValuesExample from "../partials/configValues/_configValuesExample.mdx" -import ConfigValuesProcedure from "../partials/configValues/_config-values-procedure.mdx" +import ConfigValuesRequirements from "../partials/configValues/_requirements.mdx" import PlaceholdersGlobal from "../partials/install/_placeholders-global.mdx" import PlaceholderAirgapBundle from "../partials/install/_placeholder-airgap-bundle.mdx" import PlaceholderNamespaceExisting from "../partials/install/_placeholder-namespace-existing.mdx" @@ -39,13 +39,17 @@ The following shows an example of the output from the kots install command: ## Prerequisite -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. +Create a 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. -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: +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: - +#### ConfigValues Requirements + + + +For more information, see [ConfigValues](/reference/custom-resource-configvalues). ## Online (Internet-Connected) Installation diff --git a/docs/partials/configValues/_configValuesExample.mdx b/docs/partials/configValues/_configValuesExample.mdx index a5d1d44924..96a03ccb76 100644 --- a/docs/partials/configValues/_configValuesExample.mdx +++ b/docs/partials/configValues/_configValuesExample.mdx @@ -3,11 +3,14 @@ apiVersion: kots.io/v1beta1 kind: ConfigValues spec: values: - text_config_field_name: - default: Example default value - value: Example user-provided value - boolean_config_field_name: + config_item_name: + default: example_default_value + value: example_value + boolean_config_item_name: value: "1" - password_config_field_name: - valuePlaintext: examplePassword + password_config_item_name: + valuePlainText: exampleplaintextpassword + select_one_config_item_name: + default: default_option_name + value: selected_option_name ``` diff --git a/docs/partials/configValues/_requirements.mdx b/docs/partials/configValues/_requirements.mdx new file mode 100644 index 0000000000..0f1d9fc8ce --- /dev/null +++ b/docs/partials/configValues/_requirements.mdx @@ -0,0 +1,5 @@ +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 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"`). \ No newline at end of file diff --git a/docs/reference/custom-resource-configvalues.mdx b/docs/reference/custom-resource-configvalues.mdx new file mode 100644 index 0000000000..eb6ae68834 --- /dev/null +++ b/docs/reference/custom-resource-configvalues.mdx @@ -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 + +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: + +![Config fields mapped from Config resource to ConfigValues resource](/images/configvalues-diagram.png) + +[View a larger version of this image](/images/configvalues-diagram.png) + +As shown in the image above, the `values` key in the ConfigValues resource 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). + +## Example + + + +## Requirements + + + +## 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: mandy@nitflex.com, jeff@nitflex.com, anil@nitflex.com + 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 `{}`. +::: + +### 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. + +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: + +![valuesPlainText field in ConfigValues](/images/configvalues-plaintext.png) + +[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. + + \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index 40e18644b2..a736681da8 100644 --- a/sidebars.js +++ b/sidebars.js @@ -389,6 +389,7 @@ const sidebars = { 'reference/custom-resource-about', 'reference/custom-resource-application', 'reference/custom-resource-config', + 'reference/custom-resource-configvalues', 'reference/custom-resource-helmchart-v2', 'reference/custom-resource-helmchart', 'reference/custom-resource-lintconfig', diff --git a/static/images/configvalues-diagram.png b/static/images/configvalues-diagram.png new file mode 100644 index 0000000000..192cf75bc5 Binary files /dev/null and b/static/images/configvalues-diagram.png differ diff --git a/static/images/configvalues-plaintext.png b/static/images/configvalues-plaintext.png new file mode 100644 index 0000000000..2b578ab52e Binary files /dev/null and b/static/images/configvalues-plaintext.png differ