Installing with the CLI

This topic describes how to use the Replicated kots CLI to install an application.

Overview

You can use the kots CLI to install an application rather than using the KOTS admin console UI. In a CLI installation, you provide all the necessary artifacts to configure and install the application with the kots install command. For example, rather than uploading your license file in the admin console, you provide your license file with the kots install command using the --license-file flag. Additionally, any preflight checks defined for the application automatically run from the CLI rather than being displayed in the admin console.

The following shows an example of the output from the kots install command:

• Deploying Admin Console
 • Creating namespace ✓
 • Waiting for datastore to be ready ✓
• Waiting for Admin Console to be ready ✓
• Waiting for installation to complete ✓
• Waiting for preflight checks to complete ✓

• Press Ctrl+C to exit
• Go to http://localhost:8800 to access the Admin Console

• Go to http://localhost:8888 to access the application

One common use case for installing with the CLI is to automate installation, such as installing applications as part of CI/CD pipelines. CLI installations are supported for online environments (with outbound internet access), air gap environments (without outbound internet access), existing clusters, and clusters created with Replicated kURL on a VM or bare metal server.

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

For a tutorial that demonstrates how to install a sample application using the kots CLI, see KOTS Tutorial (CLI).

Prerequisite

Create a ConfigValues file to define the configuration settings for the application. For air gap environments, 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.

The ConfigValues file is specific to the application. For more information, see Sharing a ConfigValues File.

Install

This section provides the steps for installing an application with the kots CLI in different types of environments.

Existing Cluster

To install in an existing cluster:

1. Install the kots CLI:

   curl https://kots.io/install | bash

   For more installation options, see Installing the kots CLI.

2. Install the application:

   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 your license file.

   • PATH_TO_CONFIGVALUES with the path to the ConfigValues file.

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

kURL Cluster

You can use Replicated kURL to provision a cluster and install an application on a VM or bare metal server. When you use the kots CLI to install an application in a kURL cluster, you first run the kURL installation script to provision the cluster and automatically install KOTS in the cluster. Then, you can run the kots install command to install the application.

To install with kURL on a VM or bare metal server:

1. Create the kURL cluster:

   curl -sSL https://k8s.kurl.sh/APP_NAME | sudo bash

2. Install the application in the cluster:

   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 your license file.

   • PATH_TO_CONFIGVALUES with the path to the ConfigValues file.

   • NAMESPACE with the namespace where Replicated kURL installed Replicated KOTS when creating the cluster. By default, kURL installs KOTS in the default namespace.

Air Gap Existing Cluster

Air gap installations in existing clusters require the application .airgap bundle and the KOTS admin console kotsadm.tar.gz air gap bundle. Additionally, images for the application and the KOTS admin console must be pushed to a local private registry. For more information about downloading the necessary air gap bundles, see Downloading Air Gap Bundles.

To install in an air gap existing cluster:

1. Install the kots CLI. See Manually Download and Install in Installing the kots CLI.

2. Download the kotsadm.tar.gz air gap bundle from the Releases page in the kots GitHub repository or from the download portal. For more information, see Download the KOTS Admin Console Bundle. The kotsadm.tar.gz air gap bundle includes the container images for the KOTS admin console.

   note

   The versions of the kots CLI and the kotsadm.tar.gz bundle must match. You can check the version of the kots CLI with kubectl kots version.

3. Extract the KOTS admin console container images from the kotsadm.tar.gz bundle and push the images to your private registry:

   kubectl kots admin-console push-images ./kotsadm.tar.gz REGISTRY_HOST \
     --registry-username RW_USERNAME \
     --registry-password RW_PASSWORD

   Replace:

   • REGISTRY_HOST with the hostname for the private registry. For example, private.registry.host or my-registry.example.com/my-namespace.

   • RW_USERNAME and RW_PASSWORD with the username and password for an account that has read and write access to the private registry.

     note

     KOTS does not store or reuse these read-write credentials.

4. Install the application:

   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 \
     --registry-username RO_USERNAME \
     --registry-password RO_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 your license file.

   • PATH_TO_CONFIGVALUES with the path to the ConfigValues file.

   • PATH_TO_AIRGAP_BUNDLE with the path to the application .airgap bundle. For information about downloading the .airgap bundle, see Build and Download the Application Bundle in Downloading Air Gap Bundles.
   • NAMESPACE with the namespace where you want to install both the application and KOTS.

   • REGISTRY_HOST with the same hostname for the private registry where you pushed the admin console images.

   • RO_USERNAME and RO_PASSWORD with the username and password for an account that has read-only access to the private registry.

     note

     KOTS stores these read-only credentials in a Kubernetes secret in the same namespace where the admin console is installed.

     KOTS uses these credentials to pull the images. To allow KOTS to pull images, the credentials are automatically created as an imagePullSecret on all of the admin console Pods.

Air Gap kURL Cluster

You can use Replicated kURL to provision a cluster and install an application on a VM or bare metal server. When you use the kots CLI to install an application in a kURL cluster, you first run the kURL installation script to provision the cluster and automatically install KOTS in the cluster. Then, you can run the kots install command to install the application.

Air gap installations with kURL require the application .airgap bundle and the kURL .tar.gz air gap bundle. For more information about downloading the necessary air gap bundles, see Downloading Air Gap Bundles.

To install in an air gap kURL cluster on a VM or bare metal server:

1. Download the kURL .tar.gz air gap bundle:

   export REPLICATED_APP=APP_SLUG
   curl -LS https://k8s.kurl.sh/bundle/$REPLICATED_APP.tar.gz -o $REPLICATED_APP.tar.gz

   Where APP_SLUG is the unqiue slug for the application.

   For more information, see Download the kURL Bundle in Downloading Air Gap Bundles.

2. In your installation environment, extract the contents of the kURL .tar.gz bundle that you downloaded:

   tar -xvzf $REPLICATED_APP.tar.gz

3. Create the kURL cluster:

   cat install.sh | sudo bash -s airgap

4. Install the application:

   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 your license file.

   • PATH_TO_CONFIGVALUES with the path to the ConfigValues file.

   • PATH_TO_AIRGAP_BUNDLE with the path to the application .airgap bundle. For information about downloading the .airgap bundle, see Build and Download the Application Bundle in Downloading Air Gap Bundles.
   • NAMESPACE with the namespace where Replicated kURL installed Replicated KOTS when creating the cluster. By default, kURL installs KOTS in the default namespace.

(Optional) Access the Admin Console

When you install an application in an existing cluster or when you provision a 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.