Generating a ConfigValues File

This topic describes how to generate the Replicated KOTS ConfigValues file for an application release. It also includes recommendations for how to prepare a sample ConfigValues file to be shared with your users.

Overview

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. The following is an example of a ConfigValues file:

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:
      value: "1"
    password_config_field_name:
      valuePlaintext: examplePassword

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. This supports automated or headless installations, such as when installing an application as part of CI/CD pipelines.

For more information about installing from the command line, see Installing from the Command Line.

Get the ConfigValues File

During installation, KOTS automatically generates a ConfigValues file and saves the file in a directory called upstream. After installation, you can view the generated ConfigValues file in the Admin Console View files tab or from the command line by running the kubectl kots get config command.

To get the ConfigValues file from an installed application instance:

1. Install the target release in a development environment. You can either install the release with Replicated Embedded Cluster or install in an existing cluster with KOTS. For more information, see Online Installation with Embedded Cluster or Online Installation in Existing Clusters.

2. Depending on the installer that you used, do one of the following to get the ConfigValues for the installed instance:

   • For Embedded Cluster installations: In the Admin Console, go to the View files tab. In the filetree, go to upstream > userdata and open config.yaml, as shown in the image below:

     

     View a larger version of this image

   • For KOTS installations in an existing cluster: Run the kubectl kots get config command to view the generated ConfigValues file:

     kubectl kots get config --namespace APP_NAMESPACE --decrypt 

     Where:

     • APP_NAMESPACE is the cluster namespace where KOTS is running.
     • The --decrypt flag decrypts all configuration fields with type: password. In the downloaded ConfigValues file, the decrypted value is stored in a valuePlaintext field.

     The output of the kots get config command shows the contents of the ConfigValues file. For more information about the kots get config command, including additional flags, see kots get config.

     Example:

     kubectl kots get config --namespace namespace --decrypt

     apiVersion: kots.io/v1beta1
     kind: ConfigValues
     metadata:
       creationTimestamp: null
     spec:
       values:
         example_item:
           value: hello world

Share a Sample ConfigValues File

If your users will perform automated or headless installations from the command line, you can share an example of an accurate ConfigValues file that they can edit.

Before sharing a sample ConfigValues with users, Replicated recommends that you edit the sample file in the following ways:

• Remove any configuration fields that have readonly set to true. Users cannot edit read only fields. For more information, see readonly in Config.

• Remove the metadata and status fields. These fields are automatically generated because the file is a Kubernetes custom resource. KOTS does not use the metadata or status fields.

• (Optional) Remove any fields that have hidden set to true. Fields with hidden set to true can be edited by users, but are hidden from the Admin Console Config page. For more information, see hidden in Config.

• Write comments in the file or provide supplementary documentation 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 radio or dropdown fields, 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
    bool	"1" specifies true and "0" specifies false. bool_config_field: value: "1" bool_config_field: value: "0"
    file	A filename field and a Base64 encoded string of the contents of the file in the value field. file_config_field: filename: my-file.txt value: JVBERi0xLjQKMSAw...
    password	A valuePlaintext field that contains the password in plain text. KOTS encrypts any values in valuePlaintext fields during installation. password_config_field: valuePlaintext: myPlainTextPassword
    radio and dropdown	The value must match the name of one of the nested items for the select_one field as defined in the Config custom resource manifest. radio_config_field: value: option_name
    text	Plain text in the value field. text_config_field: value: This is a text field value.
    textarea	Plain text in the value field. textarea_config_field: value: This is a text area field value.

    For more information about each configuration field type in the Config custom resource, see Config.