Skip to main content

Online Installation in Existing Clusters

This topic describes how to use Replicated KOTS to install an application in an existing Kubernetes cluster.

Prerequisites​

Complete the following prerequisites:

  • Ensure that your cluster meets the minimum system requirements. See Minimum System Requirements in Installation Requirements.

  • Ensure that you have at least the minimum RBAC permissions in the cluster required to install KOTS. See RBAC Requirements in Installation Requirements.

    note

    If you manually created RBAC resources for KOTS as described in Namespace-scoped RBAC Requirements, include both the --ensure-rbac=false and --skip-rbac-check flags when you run the kots install command.

    These flags prevent KOTS from checking for or attempting to create a Role with * * * permissions in the namespace. For more information about these flags, see install or admin-console upgrade.

  • Review the options available with the kots install command before installing. The kots install command includes several optional flags to support different installation use cases. For a list of options, see install in the kots CLI documentation.

  • Download the license file provided by your software vendor. Ensure that you can access the downloaded license file from the environment where you will install the application.

Install KOTS​

This procedure describes how to install KOTS in your existing cluster.

KOTS deploys the Replicated admin console, which provides a user interface for installing and managing applications. After you install KOTS, you will use the admin console to install the application in your cluster in the Install and Deploy the Application procedure that follows.

To install KOTS:

  1. Run one of these commands to install the Replicated kots CLI and KOTS. As part of the command, you also specify a name and version for the application that you will install as part of the Install and Deploy the Application procedure that follows.

    • For the latest application version:

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

    • For a specific application version:

      curl https://kots.io/install | bash
      kubectl kots install APP_NAME --app-version-label=VERSION_LABEL

    Replace, where applicable:

    • APP_NAME with the name of the application. The APP_NAME is included in the installation command that your vendor gave you. This is a unique identifier that KOTS will use to refer to the application that you install.
    • VERSION_LABEL with the label for the version of the application to install. For example, --app-version-label=3.0.1.

    Examples:

    curl https://kots.io/install | bash
    kubectl kots install application-name
    curl https://kots.io/install | bash
    kubectl kots install application-name --app-version-label=3.0.1

  2. When prompted by the kots install command:

    1. Provide the namespace where you want to install both KOTS and the application.

    2. Create a new password for logging in to the admin console.

      Example:

      $ kubectl kots install application-name
      Enter the namespace to deploy to: application-name
        • Deploying Admin Console
          • Creating namespace ✓
          • Waiting for datastore to be ready ✓
      Enter a new password to be used for the Admin Console: ••••••••
        • Waiting for Admin Console to be ready ✓

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

      After the kots install command completes, it creates a port forward to the admin console. The admin console is exposed internally in the cluster and can only be accessed using a port forward.

  3. Continue to Install and Deploy the Application below to log in to the admin console and install the application.

Install and Deploy the Application​

After you install KOTS, log in to the admin console to provide your license file, define your configuration values, run preflight checks, and install and deploy the application.

To install the application using the admin console:

  1. Access the admin console on port 8800:

    • Existing cluster: If the port forward is active, go to http://localhost:8800 to access the admin console.

      If you need to reopen the port forward to the admin console, run the following command:

      kubectl kots admin-console -n NAMESPACE

      Replace NAMESPACE with the namespace where KOTS is installed.

    • Embedded cluster: Go to the address provided in the Kotsadm field in the output of the installation command. For example, Kotsadm: http://34.171.140.123:8800.

  2. (Embedded Cluster Only) On the Bypass Browser TLS warning page, review the information about how to bypass the browser TLS warning, and then click Continue to Setup.

  3. (Embedded Cluster Only) On the HTTPS page, do one of the following:

    • To use the self-signed TLS certificate only, enter the hostname (required) if you are using the identity service. If you are not using the identity service, the hostname is optional. Click Skip & continue.
    • To use a custom certificate only, enter the hostname (required) if you are using the identity service. If you are not using the identity service, the hostname is optional. Then upload a private key and SSL certificate to secure communication between your browser and the admin console. Click Upload & continue.

  4. Log in to the admin console:

    • Existing cluster: Log in with the password that you created during installation.
    • Embedded cluster: Log in with the password that was provided in the Login with password (will not be shown again): field in the output of the installation command.

    Secure Console

  5. Upload the license file provided by your application vendor.

  6. (Air Gap Only) Upload the .airgap air gap bundle provided by your application vendor.

  7. If there are configurations specific to the application, complete the fields on the configuration screen then click Continue. The required and optional configuration fields on this screen are used to build the final deployable Kubernetes manifests for the application.

    If the application vendor did not include any configuration options for the application, this screen does not display.

    Initial Config

  8. Complete the preflight checks. KOTS automatically runs preflight checks (conformance tests) against the target namespace and cluster to ensure that the environment meets the minimum requirements to support the application.

    • If there are no preflight check warnings or failures, continue with deployment.

    • If there are any preflight check warnings and failures:

      • Resolve the warnings and failures, and click Re-run to run the preflight checks again.

      • If there are no failures that prevent application deployment, you can choose to dismiss the preflight check warnings to continue.

        note

        Replicated recommends that you address any warnings or failures, rather than dismissing them. Preflight checks help ensure that your environment meets the requirements for application deployment.

      • If you are installing with minimal role-based access control (RBAC), KOTS recognizes if the preflight checks failed due to insufficient privileges.

        When this occurs, a kubectl CLI preflight command displays that lets you manually run the preflight checks. The admin console automatically displays the results of the preflight checks.

        kubectl CLI preflight command

        View a larger version of this image

    After preflight checks are complete, KOTS deploys the admin console and the application, and the admin console dashboard opens:

    Graphs on the admin console dashboard

  9. (Recommended) Change the admin console login password:

    1. Click the menu in the top right corner of the admin console, then click Change password.
    2. Enter a new password in the dialog, and click Change Password to save.

    Replicated strongly recommends that you change the password from the default provided during installation on an embedded cluster. For more information, see Changing an Admin Console Password.

  10. (Embedded Cluster Only) Add primary and secondary nodes to the cluster. You might add nodes to either meet application requirements defined by the vendor or to support your usage of the application. See Adding Nodes to Embedded Clusters.

    note

    Reach out to your application vendor for information about any node requirements.

  11. (Existing Cluster Only) Configure application and cluster monitoring. This allows you to view graphs on the admin console dashboard with key metrics collected by Prometheus. See Monitoring Applications.