Skip to main content

Air Gap Installation in Existing Clusters

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

The procedures in this topic apply to installation environments that do not have access to the internet, known as air gap environments.

About Private Registries​

Air gapped networks must have a Docker image registry that is available inside the network. KOTS rewrites the application image names in all application manifests to read from the on-premises registry, and it re-tags and pushes the images to the on-premises registry. When authenticating to the registry, credentials with push permissions are required.

A single application expects to use a single namespace in the Docker image registry. The namespace name can be any valid URL-safe string, supplied at installation time. A registry typically expects the namespace to exist before any images can be pushed into it.

note

ECR does not use namespaces.

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.

  • Ensure that there is a compatible Docker image registry available inside the network. For more information about Docker registry compatibility, see Private Registry Requirements.
  • Download the .airgap bundle provided by your software vendor. Ensure that you can access the downloaded bundle from the environment where you will install the application.
  • 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.
  • Download the kotsadm.tar.gz air gap bundle from the kots release page on GitHub. The kotsadm.tar.gz air gap bundle includes the container images for the Replicated admin console. See Releases in the kots GitHub repository.

Install KOTS​

This procedure describes how to install KOTS in your existing cluster using the kotsadm.tar.gz air gap bundle.

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. Install the Replicated kots CLI plugin. See Install without Root Access in the kots CLI reference section.

  2. Run the following command to confirm that the kots CLI version matches the version of the kotsadm.tar.gz air gap bundle that you downloaded:

    kubectl kots version

  3. Run the following command to extract 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.

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

    • RW_PASSWORD with the password for the account with read and write access.

    note

    KOTS does not store or reuse these credentials.

  4. Run the following command to install KOTS using the images that you pushed in the previous step:

    kubectl kots install APP_NAME \
      --kotsadm-registry REGISTRY_HOST \
      --kotsadm-namespace REGISTRY_NAMESPACE \
      --registry-username RO-USERNAME \
      --registry-password RO-PASSWORD

    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.

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

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

    • RO_PASSWORD with the password for the read-only account.

    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.

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

  6. 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 and the .airgap bundle, 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.