Automate Installation with Embedded Cluster

This topic describes how to install an application with Replicated Embedded Cluster from the command line, without needing to access the Replicated KOTS Admin Console.

Overview

A common use case for installing with Embedded Cluster from the command line is to automate installation, such as performing headless installations as part of CI/CD pipelines.

With headless installation, you provide all the necessary installation assets, such as the license file and the application config values, with the installation command rather than through the Admin Console UI. Any preflight checks defined for the application run automatically during headless installations from the command line rather than being displayed in the Admin Console.

Prerequisite

Create a ConfigValues resource to define the configuration values for the application. The ConfigValues resource 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. For air-gapped environments, ensure that the ConfigValues file can be accessed from the installation environment.

The ConfigValues resource includes the fields that are defined in the Replicated KOTS Config custom resource for the release, along with the user-supplied and default values for each field, as shown in the example below:

apiVersion: kots.io/v1beta1
kind: ConfigValues
spec:
  values:
    config_item_name:
      default: example_default_value
      value: example_value
    boolean_config_item_name:
      value: "1"
    password_config_item_name:
      valuePlainText: exampleplaintextpassword
    select_one_config_item_name:
      default: default_option_name
      value: selected_option_name  

ConfigValues Requirements

The ConfigValues resource must meet the following requirements:

• Must be valid YAML.
• It is not necessary to set a value for each configuration item in the ConfigValues, unless the item is required and has no default set in the Config resource.
• For any configuration items of type password defined in the Config resource, set the value in plain text in the ConfigValues valuePlainText property rather than in the value property. For example, valuePlainText: somesecretvalue. Values set in valuePlainText are automatically encrypted during installation.
• All values must be strings. For booleans, integers, or floats, wrap the value in quotes (for example, value: "1", value: "0", or value: "443").

For more information, see ConfigValues.

Limtiation

Automating deployment with Embedded Cluster is supported only for the initial installation. Performing automated (headless) updates of existing installations with Embedded Cluster is not supported. For information about how to update an existing installation through the Admin Console UI, see Perform Updates in Embedded Clusters.

Online (Internet-Connected) Installation

To install with Embedded Cluster in an online environment:

1. Follow the steps provided in the Vendor Portal to download and untar the Embedded Cluster installation assets. For more information, see Online Installation with Embedded Cluster.

2. Run the following command to install:

   sudo ./APP_SLUG install --license PATH_TO_LICENSE \
     --config-values PATH_TO_CONFIGVALUES \
     --admin-console-password ADMIN_CONSOLE_PASSWORD

   Replace:

   • APP_SLUG with the unique slug for the application.
   • PATH_TO_LICENSE with the path to the customer license.
   • ADMIN_CONSOLE_PASSWORD with a password for accessing the Admin Console.
   • PATH_TO_CONFIGVALUES with the path to the ConfigValues file.

Air Gap Installation

To install with Embedded Cluster in an air-gapped environment:

1. Follow the steps provided in the Vendor Portal to download and untar the Embedded Cluster air gap installation assets. For more information, see Air Gap Installation with Embedded Cluster.

2. Ensure that the Embedded Cluster installation assets are available on the air-gapped machine, then run the following command to install:

   sudo ./APP_SLUG install --license PATH_TO_LICENSE \
     --config-values PATH_TO_CONFIGVALUES \
     --admin-console-password ADMIN_CONSOLE_PASSWORD \
     --airgap-bundle PATH_TO_AIRGAP_BUNDLE

   Replace:

   • APP_SLUG with the unique slug for the application.
   • PATH_TO_LICENSE with the path to the customer license.
   • PATH_TO_CONFIGVALUES with the path to the ConfigValues file.
   • ADMIN_CONSOLE_PASSWORD with a password for accessing the Admin Console.
   • PATH_TO_AIRGAP_BUNDLE with the path to the Embedded Cluster .airgap bundle for the release.