Skip to main content

Generating a ConfigValues File

This topic describes how to view the ConfigValues file for an application installed with Replicated KOTS and prepare the ConfigValues file to be shared with your users.

About ConfigValues Files​

A ConfigValues file defines the user-supplied configuration values for an application installed with KOTS. Enterprise users can provide a ConfigValues file to configure an application during automated installations with the KOTS CLI. During installation, KOTS reads the values in the ConfigValues file to configure the application. For more information about automated installations with the KOTS CLI, see Installing with the CLI.

ConfigValues files include the configuration fields defined in the Config custom resource for the 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

Get the ConfigValues File​

When installing an application, KOTS automatically generates a ConfigValues file and saves the file in a directory called upstream. After installation, you can view the generated ConfigValues file.

To get the ConfigValues file for an application:

  1. Install the target release for the application in a development environment. For more information, see About Installing an Application.

  2. View the generated ConfigValues file for the installed instance:

    kubectl kots get config --namespace APP_NAMESPACE --decrypt

    Where APP_NAMESPACE is the cluster namespace where the application is installed.

    note

    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 is the contents of the ConfigValues file. For more information about the kots get config command, including additional flags, see kots get config.

Share a Sample ConfigValues File​

Replicated recommends that you share an example of an accurate ConfigValues file with your users that they can edit for use in automated installations with the KOTS CLI.

After you get the ConfigValues file for your application using the kots get config command, Replicated recommends that you do the following to edit the contents of the ConfigValues file before sharing it with users:

  • 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 TypeSupported 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.