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 for the application. Ensure that you can access the downloaded bundle from the environment where you will install the application. See Downloading Air Gap Bundles.
  • Download your license file. Ensure that you can access the downloaded license file from the environment where you will install the application. See Downloading Customer Licenses.

  • 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 in Downloading Air Gap Bundles. The kotsadm.tar.gz air gap bundle includes the container images for the KOTS Admin Console.

Install​

To install KOTS and an application in an air gap existing cluster:

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

    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.

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

  3. Install the KOTS Admin Console using the images that you pushed in the previous step:

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

    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.

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

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

  5. Access the Admin Console on port 8800. 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.

  6. Log in with the password that you created during installation.

  7. Upload your license file.

  8. Upload the .airgap application air gap bundle.

  9. On the config screen, complete the fields for the application configuration options and then click Continue.

  10. On the Preflight checks page, the application-specific preflight checks run automatically. Preflight checks are conformance tests that run against the target namespace and cluster to ensure that the environment meets the minimum requirements to support the application. Click Deploy.

    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.

  11. (Minimal RBAC Only) 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 then automatically displays the results of the preflight checks. Click Deploy.

    kubectl CLI preflight command

    View a larger version of this image

The Admin Console dashboard opens.

On the Admin Console dashboard, the application status changes from Missing to Unavailable while the Deployment is being created. When the installation is complete, the status changes to Ready. For example:

Admin Console dashboard

View a larger version of this image