# Install with the KOTS CLI

This topic describes how to install an application with Replicated KOTS in an existing cluster using the KOTS CLI.

## Overview

You can use the KOTS CLI to install an application with Replicated KOTS. A common use case for installing from the command line is to automate installation, such as performing headless installations as part of CI/CD pipelines.

To install with the KOTS CLI, 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 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
  ```

## 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:

```yaml
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

* Linux operating system

* x86-64 architecture

* systemd

* At least 2GB of memory and 2 CPU cores

* The disk on the host must have a maximum P99 write latency of 10 ms. This supports etcd performance and stability. For more information about the disk write latency requirements for etcd, see [Disks](https://etcd.io/docs/latest/op-guide/hardware/#disks) in _Hardware recommendations_ and [What does the etcd warning “failed to send out heartbeat on time” mean?](https://etcd.io/docs/latest/faq/) in the etcd documentation.

* The user performing the installation must have root access to the machine, such as with `sudo`.

* The data directory used by Embedded Cluster must have 40Gi or more of total space and be less than 80% full. By default, the data directory is `/var/lib/embedded-cluster`. The directory can be changed by passing the `--data-dir` flag with the Embedded Cluster `install` command. For more information, see [install](/reference/embedded-cluster-install).

   Note that in addition to the primary data directory, Embedded Cluster creates directories and files in the following locations:

      - `/etc/cni`
      - `/etc/k0s`
      - `/opt/cni`
      - `/opt/containerd`
      - `/run/calico`
      - `/run/containerd`
      - `/run/k0s`
      - `/sys/fs/cgroup/kubepods`
      - `/sys/fs/cgroup/system.slice/containerd.service`
      - `/sys/fs/cgroup/system.slice/k0scontroller.service`
      - `/usr/libexec/k0s`
      - `/var/lib/calico`
      - `/var/lib/cni`
      - `/var/lib/containers`
      - `/var/lib/kubelet`
      - `/var/log/calico`
      - `/var/log/containers`
      - `/var/log/embedded-cluster`
      - `/var/log/pods`
      - `/usr/local/bin/k0s`

* (Online installations only) Access to replicated.app and proxy.replicated.com or your custom domain for each

* Embedded Cluster is based on k0s, so all k0s system requirements and external runtime dependencies apply. See [System requirements](https://docs.k0sproject.io/stable/system-requirements/) and [External runtime dependencies](https://docs.k0sproject.io/stable/external-runtime-deps/) in the k0s documentation.

For more information, see [ConfigValues](/reference/custom-resource-configvalues).
   
## Online (internet-connected) installation

To install with KOTS in an online existing cluster:

1. <InstallKotsCli/>

1. Install the application:

    ```bash 
    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. See [Downloading Customer Licenses](/vendor/licenses-download). For information about how to download licenses with the Vendor API v3, see [Download a customer license file as YAML](https://replicated-vendor-api.readme.io/reference/downloadlicense) in the Vendor API v3 documentation.

    * `PATH_TO_CONFIGVALUES` with the path to the ConfigValues file.

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

## Air gap installation {#air-gap}

To install with KOTS in an air-gapped existing cluster:

1. <InstallKotsCliAirGap/>

1. <DownloadKotsBundle/>

    :::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`.
    :::

1. <PushKotsImages/>

1. Install the application:

      ```bash
      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. See [Downloading Customer Licenses](/vendor/licenses-download). For information about how to download licenses with the Vendor API v3, see [Download a customer license file as YAML](https://replicated-vendor-api.readme.io/reference/downloadlicense) in the Vendor API v3 documentation.

      * `PATH_TO_CONFIGVALUES` with the path to the ConfigValues file.
      
      * `PATH_TO_AIRGAP_BUNDLE` with the path to the `.airgap` bundle for the application release. You can build and download the air gap bundle for a release in the [Vendor Portal](https://vendor.replicated.com) on the **Release history** page for the channel where the release is promoted.

           Alternatively, for information about building and downloading air gap bundles with the Vendor API v3, see [Trigger airgap build for a channel's release](https://replicated-vendor-api.readme.io/reference/channelreleaseairgapbuild) and [Get airgap bundle download URL for the active release on the channel](https://replicated-vendor-api.readme.io/reference/channelreleaseairgapbundleurl) in the Vendor API v3 documentation.

      * `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.
          :::

## (Optional) Access the Admin Console

By default, during installation, KOTS automatically opens localhost port 8800 to provide access to the Admin Console. Using the `--no-port-forward` flag with 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:

   ```bash
   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.
  
   ```bash
   ssh -L 8800:localhost:8800 user@ip-addr
   ```

1. Run the following KOTS CLI command to open localhost port 8800, which forwards to the Admin Console service:

   ```bash
   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](/reference/kots-cli-admin-console-index) in the _KOTS CLI_ documentation.

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

1. Log in to the Admin Console using the password that you created as part of the `kots install` command.