Sharing a ConfigValues File
This topic describes how to access and download the ConfigValues file for an installed application instance so that you can share the file with your users.
About ConfigValues Files
A ConfigValues file is a YAML manifest file that defines the user-supplied configuration values for an application. To configure an application using the Replicated kots CLI rather than using the Replicated admin console Config page, users must provide a ConfigValues file when they run the
kots install command.
During application installation, Replicated KOTS reads the values provided in the ConfigValues file to configure the application. For more information about how users provide a ConfigValues file when installing with the kots CLI, see Installing with Automation.
The following is an example of a ConfigValues file:
default: Example default value
value: Example user-provided value
As shown in the example above, the ConfigValues file includes the names of configuration fields along with a user-supplied value for each field. Where applicable, the ConfigValues file can also include the default values of the configuration fields.
In the ConfigValues file, users can include any optional or required configuration fields that you defined in the Config custom resource for the release. For any required configuration fields that do not have a default value, users must provide a value in the ConfigValues file to install the application.
For more information about how to create custom configuration fields for your application in the Config custom resource, see Config in Reference.
Download the ConfigValues File
During application installation, KOTS automatically generates a ConfigValues file and saves the file in a directory called
upstream. After installing an application, you can view this generated ConfigValues file in the admin console View files page. You can also download the file using the kots CLI.
To allow your users to install and configure your application with the kots CLI, Replicated recommends that you provide your users with an example of an accurate ConfigValues file. To create this example, you can use the ConfigValues file generated by KOTS for an instance of your application that you installed in a development environment.
To download the ConfigValues file for an installed instance of your application:
Install the desired release for your application in a development environment. For more information, see About Installing an Application.
Run the following command to download the manifest files for the installed instance of the application:
kubectl kots download --namespace APP_NAMESPACE --slug APP_SLUG --decrypt-password-values
APP_NAMESPACEwith the namespace on the cluster where you installed your application.
APP_SLUGwith the slug of the application.
KOTS downloads your application files from the cluster. The output of this command provides the location of the downloaded files in your local directory.note
--decrypt-password-valuesflag decrypts all configuration fields with
type: password. In the downloaded ConfigValues file, the decrypted value is stored in a
valuePlaintextfield. For more information, see kots download.
In your local directory, navigate to the directory where KOTS downloaded the files. Open the ConfigValues file located at
upstream/userdata/config.yamlin a text editor.
The following is an example of a ConfigValues file generated by KOTS:
value: A user-supplied value
Edit the contents of the ConfigValues file to create an example file that you will share with your users:
Remove any configuration fields that have
true. Users cannot edit read only fields. For more information, see readonly in Config.
statusfields. These fields are automatically generated because the file is a Kubernetes custom resource. KOTS does not use the
(Optional) Remove any fields that have
true. Fields with
truecan be edited by users, but are hidden from the admin console Config page. For more information, see hidden in Config.
In the example ConfigValues file that you will give to your users, write comments to describe the following:
The fields that are required and optional. For any required configuration fields that do not have a default value, users must provide a value in the ConfigValues file to install the application.
The supported values for each configuration field. For example, for
select_onefields, document each of the possible values that users can provide.
The supported YAML format for each value. The following table describes the supported value format for each configuration field type:
Field Type Supported Value Format
"1"specifies true and
filenamefield and a Base64 encoded string of the contents of the file in the
valuePlaintextfield that contains the password in plain text. KOTS encrypts any values in
valuePlaintextfields during installation.
valuemust match the name of one of the options for the
select_onefield as defined in the Config custom resource manifest.
Plain text in the
value: This is a text field value.
Plain text in the
value: This is a text area field value.
For more information about each configuration field type in the Config custom resource, see Config.