Downloading the 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 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, the app manager 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 Using Automation to Install on an Existing Cluster in the Enterprise section.

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

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, the Replicated app manager 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 the app manager 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

   Replace:

   • APP_NAMESPACE with the namespace on the cluster where you installed your application.
   • APP_SLUG with the slug of the application.

   The app manager downloads your application files from the cluster. The output of this command provides the location of the downloaded files in your local directory.

   note

   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 the app manager downloaded the files. Open the ConfigValues file located at upstream/userdata/config.yaml in a text editor.

   Example:

   The following is an example of a ConfigValues file generated by the app manager:

    apiVersion: kots.io/v1beta1
    kind: ConfigValues
    metadata:
      creationTimestamp: null
      name: nginx
    spec:
      values:
        example_text_config_field:
          value: A user-supplied value
        example_password_config_field:
          valuePlaintext: password
        example_boolean_config_field:
          default: "0"
          value: "1"
        readonly_example:
          value: Xp1l3JHds2
        hidden_example:
          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. The app manager 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 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. The app manager encrypts any values in valuePlaintext fields during installation. password_config_field: valuePlaintext: myPlainTextPassword
     select_one	The value must match the name of one of the options for the select_one field as defined in the Config custom resource manifest. select_one_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.