Skip to main content

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:

kind: ConfigValues
default: Example default value
value: Example user-provided value
value: "1"
valuePlaintext: examplePassword

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:

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

  2. 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_NAMESPACE with the namespace on the cluster where you installed your application.
    • APP_SLUG with 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.


    The --decrypt-password-values flag decrypts all configuration fields with type: password. In the downloaded ConfigValues file, the decrypted value is stored in a valuePlaintext field. For more information, see kots download.

  3. In your local directory, navigate to the directory where KOTS downloaded the files. Open the ConfigValues file located at upstream/userdata/config.yaml in a text editor.


    The following is an example of a ConfigValues file generated by KOTS:

    kind: ConfigValues
    creationTimestamp: null
    name: nginx
    value: A user-supplied value
    valuePlaintext: password
    default: "0"
    value: "1"
    value: Xp1l3JHds2
    value: sIpE9njpy0SWyw9Ht6K+rPzeke1DjG619Lnv4radKJS7lFUfmdzi2+MIJEj33k8PRyYM/eAGtes=
    status: {}
  4. Edit the contents of the ConfigValues file to create an example file that you will share with your users:

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

    2. 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.

    3. (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.

  5. 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_one 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

      "1" specifies true and "0" specifies false.

      value: "1"
      value: "0"

      A filename field and a Base64 encoded string of the contents of the file in the value field.

      filename: my-file.txt
      value: JVBERi0xLjQKMSAw...

      A valuePlaintext field that contains the password in plain text. KOTS encrypts any values in valuePlaintext fields during installation.

      valuePlaintext: myPlainTextPassword

      The value must match the name of one of the options for the select_one field as defined in the Config custom resource manifest.

      value: option_name

      Plain text in the value field.

      value: This is a text field value.

      Plain text in the value field.

      value: This is a text area field value.

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