Installing with Automation

This topic describes using the Replicated kots CLI to automate the installation of an application in online and air gap clusters.

About Installing with Automation

You can automate the installation of an application in your existing cluster or in an embedded cluster that you previously created with the Replicated kURL installer. To automate installation, you create an installation command with the kots CLI kots install command.

In an automated installation, you provide all the information required to install and deploy the application with the kots install command, rather than providing this information in the Replicated admin console. For example, rather than uploading your license file for the application in the admin console UI, you provide your license file with the kots install command using the --license-file flag.

The flags that you use with the kots install command vary depending on the type of your cluster (existing cluster or embedded cluster) and on the cluster's internet access (online environment with internet access or air gap environment without internet access).

For more information about the kots install command, see install in the kots CLI documentation.

Prerequisites

Before you install an application with the kots CLI, you must complete the following prerequisites:

• Create a ConfigValues manifest file to define your configuration preferences for the application. Ensure that you can access the ConfigValues file that you create from your installation environment.

  Example:

  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 the configuration fields for the application along with a user-supplied value for each field.

  Your application vendor provides details about the required and optional configuration fields to include in the ConfigValues file.

• (Existing Clusters Only) Install the kots CLI. See Installing the kots CLI.

• (Existing Clusters Only) Complete the prerequisites for your environment:

  • Online: See Prerequisites in Online Installation in Existing Clusters.
  • Air Gap: See Prerequisites in Air Gap Installation in Existing Clusters.

• (Embedded Clusters Only) This topic assumes that you have already run the kURL installation script on your VM or bare metal server to provision an embedded cluster. After you have provisioned a cluster, you can then use the kots install command to install an application in the cluster.

  For information about how to provision an embedded cluster with the kURL installer, see the following:

  • Online: See Prerequisites and Provision the Embedded Cluster in Online Installation with kURL.
  • Air Gap: See Prerequisites and Provision the Embedded Cluster in Air Gap Installation with kURL.

Installation Commands

This section provides the kots install commands that you can use to automate installation in an existing cluster or in an embedded cluster. It includes commands for both online and air gap environments.

Online Existing Cluster

When you use the kots CLI to install an application in an existing cluster, you install both the application and Replicated KOTS with a single command.

The following is the kots CLI command for installing an application in an existing cluster that has access to the internet:

kubectl kots install APP_NAME \
  --shared-password PASSWORD \
  --license-file PATH_TO_LICENSE \
  --config-values PATH_TO_CONFIGVALUES \
  --namespace NAMESPACE \
  --no-port-forward

Replace:

• APP_NAME with a name for the application. This is the unique name that KOTS will use to refer to the application that you install.

• PASSWORD with a shared password for accessing the admin console.

• PATH_TO_LICENSE with the path to the license file that you downloaded.

• PATH_TO_CONFIGVALUES with the path to the ConfigValues manifest file.

• NAMESPACE with the namespace where you want to install both the application and KOTS.

Online Embedded Cluster

When you use the kots CLI to install an application in an embedded cluster, you install the application in the default namespace, which is the same namespace where Replicated KOTS is installed. You previously installed KOTS when you ran the kURL installer script to provision the cluster.

The following is the kots CLI command for installing an application in an embedded cluster that has access to the internet:

kubectl kots install APP_NAME \
  --shared-password PASSWORD \
  --license-file PATH_TO_LICENSE \
  --config-values PATH_TO_CONFIGVALUES \
  --namespace default \
  --no-port-forward

Replace:

• APP_NAME with a name for the application. This is the unique name that KOTS will use to refer to the application that you install.

• PASSWORD with a shared password for accessing the admin console.

• PATH_TO_LICENSE with the path to the license file that you downloaded.

• PATH_TO_CONFIGVALUES with the path to the ConfigValues manifest file.

Air Gap Existing Cluster

When you use the kots CLI to install an application in an existing cluster, you install both the application and Replicated KOTS with a single command.

The following is the kots CLI command for installing an application in an existing cluster that does not have access to the internet:

kubectl kots install APP_NAME \
  --shared-password PASSWORD \
  --license-file PATH_TO_LICENSE \
  --config-values PATH_TO_CONFIGVALUES \
  --airgap-bundle PATH_TO_AIRGAP_BUNDLE \
  --namespace NAMESPACE \
  --kotsadm-registry REGISTRY_HOST \
  --kotsadm-namespace REGISTRY_NAMESPACE \
  --registry-username READ_WRITE_USERNAME \
  --registry-password READ_WRITE_PASSWORD \
  --no-port-forward

Replace:

• APP_NAME with a name for the application. This is the unique name that KOTS will use to refer to the application that you install.

• PASSWORD with a shared password for accessing the admin console.

• PATH_TO_LICENSE with the path to the license file that you downloaded.

• PATH_TO_CONFIGVALUES with the path to the ConfigValues manifest file.

• PATH_TO_AIRGAP_BUNDLE with the path to the application .airgap bundle that you downloaded.

• NAMESPACE with the namespace where you want to install both the application and KOTS.

• REGISTRY_HOST with the hostname for the private registry where you pushed the images. For example, private.registry.host.

• REGISTRY_NAMESPACE with the namespace in the private registry where you pushed the images. For example, if you pushed the images to my-registry.example.com/app-name/image:tag, then app-name is the registry namespace.

• READ_WRITE_USERNAME and READ_WRITE_PASSWORD with credentials with read write permissions to the private registry where you pushed the images.

Air Gap Embedded Cluster

When you use the kots CLI to install an application in an embedded cluster, you install the application in the default namespace, which is the same namespace where Replicated KOTS is installed. You previously installed KOTS when you ran the kURL installer script to provision the cluster.

The following is the kots CLI command for installing an application in an embedded cluster that does not have access to the internet:

kubectl kots install APP_NAME \
  --shared-password PASSWORD \
  --license-file PATH_TO_LICENSE \
  --config-values PATH_TO_CONFIGVALUES \
  --airgap-bundle PATH_TO_AIRGAP_BUNDLE \
  --namespace default \
  --no-port-forward

Replace:

• APP_NAME with a name for the application. This is the unique name that KOTS will use to refer to the application that you install.

• PASSWORD with a shared password for accessing the admin console.

• PATH_TO_LICENSE with the path to the license file that you downloaded.

• PATH_TO_CONFIGVALUES with the path to the ConfigValues manifest file.

• PATH_TO_AIRGAP_BUNDLE with the path to the application .airgap bundle that you downloaded.

(Optional) Access the Admin Console

When you install an application in an existing cluster or when you provision an embedded cluster with the kURL installer, you also install KOTS in the cluster. KOTS deploys the admin console. The admin console is a user interface where you can manage and upgrade your application instances.

By default, during installation, KOTS automatically opens localhost port 8800 to provide access to the admin console. The --no-port-forward flag in the kots install command prevents KOTS from creating a port forward to the admin console.

After you install with the --no-port-forward flag, you can optionally create a port forward so that you can log in to the admin console in a browser window.

To access the admin console:

1. If you installed in a VM where you cannot open a browser window, forward a port on your local machine to localhost:8800 on the remote VM using the SSH client:

   ssh -L LOCAL_PORT:localhost:8800 USERNAME@IP_ADDRESS

   Replace:

   • LOCAL_PORT with the port on your local machine to forward. For example, 9900 or 8800.
   • USERNAME with your username for the VM.
   • IP_ADDRESS with the IP address for the VM.

   Example:

   The following example shows using the SSH client to forward port 8800 on your local machine to localhost:8800 on the remote VM.

   ssh -L 8800:localhost:8800 user@ip-addr

2. Run the following kots CLI command to open localhost port 8800, which forwards to the admin console service:

   kubectl kots admin-console --namespace NAMESPACE

   Replace NAMESPACE with the namespace where the admin console was installed.

   For more information about the kots admin-console command, see admin-console in the kots CLI documentation.

3. Open a browser window and go to https://localhost:8800.

4. Log in to the admin console using the password that you created as part of the kots install command.