Skip to main content

Online Installation with kURL

This topic describes how to use Replicated kURL to provision an embedded cluster in a virtual machine (VM) or bare metal server and install an application in the cluster.

Replicated kURL is an open source project. For more information, see the kURL documentation.

About High Availability Mode​

Online installations can use high availability (HA) mode with the kURL installer.

A load balancer is required for high availability mode. If your vendor has chosen to use the internal load balancer with the kURL EKCO add-on, you do not need to provide your own external load balancer. An external load balancer can be preferred when clients outside the cluster need access to the cluster's Kubernetes API.

If you decide to use an external load balancer, the external load balancer must be a TCP forwarding load balancer. For more information, see Prerequisites.

The health check for an apiserver is a TCP check on the port that the kube-apiserver listens on. The default value is :6443. For more information about the kube-apiserver external load balancer, see Create load balancer for kube-apiserver in the Kubernetes documentation.

Prerequisites​

Complete the following prerequisites:

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

  • Review the advanced installation options available for the kURL installer. See Advanced Options in the kURL 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.
  • If you are installing in high availability mode:
    • (Optional) If you are going to use the internal load balancer, you can preconfigure it by passing | sudo bash -s ha ekco-enable-internal-load-balancer.
    • For an external load balancer, ensure that your load balancer is:
      • A TCP forwarding external load balancer.
      • Configured to distribute traffic to all healthy control plane nodes in its target list.
      • (Optional) Preconfigured by passing the load-balancer-address=HOST:PORT flag.

Provision the Embedded Cluster​

This procedure describes how to use kURL to provision an embedded cluster on a VM or bare metal server. Additionally, kURL automatically installs Replicated KOTS in the default namespaces in the 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 provision an embedded cluster:

  1. Run one of the following commands to create the cluster with the kURL installer:

    • For a regular installation, run:

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

    • For high availability mode:

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

    Replace:

    • 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.

  2. (High Availability Only) If you did not preconfigure a load balancer, you are prompted during the installation. Do one of the following:

    • If you are using the internal load balancer, leave the prompt blank and proceed with the installation.

    • If you are using an external load balancer, pass the load balancer address.

  3. After the installation command finishes, note the Kotsadm and Login with password (will not be shown again) fields in the output of the command. You use these to log in to the admin console.

    The following shows an example of the Kotsadm and Login with password (will not be shown again) fields in the output of the installation command:

            Installation
              Complete ✔

    Kotsadm: http://10.128.0.35:8800
    Login with password (will not be shown again): 3Hy8WYYid

    This password has been set for you by default. It is recommended that you change
    this password; this can be done with the following command:
    kubectl kots reset-password default

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

    Alternatively, you can use the Replicated kots CLI to automate the installation of the application rather than logging in to the admin console. For more information, see Installing with Automation.

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.