Skip to main content

Air-Gapped Install

Air-Gapped / Offline / VPC Clusters​

If your cluster is air-gapped, within a VPC, or has restricted network connectivity, you may encounter issues validating the platform license and pulling required container images.

To solve the licensing issue, you can either use allow HTTP requests from the platform pods to https://admin.loft.sh/* (this is the preferred option), or use an offline license key.

To address image pulling issues from Docker Hub, you can use a private image registry to host your own copies of the platform images accessible to your cluster.

Prerequisites​

  • A running air-gapped Kubernetes cluster v1.26.x, v1.27.x, or v1.28.x
  • On the installation computer:
    • kubectl (verify with kubectl version)
    • helm (verify with helm version)
    • docker (verify with docker version)
    • A kube-context with admin access to the Kubernetes cluster (verify with kubectl auth can-i create clusterrole -A)
      info

      To obtain a kube-context with admin access, ensure you have the necessary credentials and permissions for your Kubernetes cluster. This typically involves using kubectl config commands or authenticating through your cloud provider's CLI tools.

    • [Optional] An offline license key for the platform (provided by Loft)
  • [Optional] A private Docker registry accessible to both the installer computer and the air-gapped Kubernetes cluster

Resource requirements​

  • Pod Resource Requirements:

    • Requests
      • memory: 256Mi
      • cpu: 200m
    • Limits
      • memory: 4Gi
      • cpu: 2

  • Open network ports:

    info

    The platform installs webhooks and API server extensions into the cluster. The Kubernetes master needs to communicate with the platform pods. For example, in private GKE clusters, the Kubernetes master and nodes are not in the same subnetwork and cannot communicate directly on every port. Ensure a firewall rule allows incoming traffic from the Kubernetes master network to the following TCP ports:

    • 8443 (platform agent API service extension - v1.cluster.loft.sh)
    • 9443 (platform agent webhook & loft webhook)
    • 9444 (platform API service extension - v1.management.loft.sh)

Offline Images​

For clusters unable to pull images from Docker Hub, you need to push the platform images to your private registry. Each platform release includes a loft-images.txt file that lists the necessary images.

Follow these instructions to download all platform images and import them to your private registry:

  1. Set the VERSION variable to the platform version you want to upgrade to or set it to the current version using:

    Set VERSION variable
    CHART=$(kubectl get service loft -n vcluster-platform -o jsonpath={.metadata.labels.chart})
    VERSION=${CHART:5}

  2. Set your private registry as a variable:

    Set private registry
    REGISTRY=ecr.io/myteam      # This should be a prefix; do not include any LOFT_IMAGE paths

  3. Download the loft-images.txt file and the required scripts download-images.sh and push-images.sh, then make them executable:

    Download and prepare scripts
    wget https://github.com/loft-sh/loft/releases/download/v${VERSION}/loft-images.txt
    wget https://github.com/loft-sh/loft/releases/download/v${VERSION}/download-images.sh
    wget https://github.com/loft-sh/loft/releases/download/v${VERSION}/push-images.sh

    chmod +x ./download-images.sh
    chmod +x ./push-images.sh

  4. Run download-images.sh to download all images locally:

    Download images
    ./download-images.sh --image-list loft-images.txt

  5. Run push-images.sh to push all downloaded images to your private registry:

    Push images to private registry
    ./push-images.sh --registry ${REGISTRY}

  6. Edit your existing vcluster-platform.yaml file or create a new one with the following content:

    vcluster-platform.yaml
    image: ${REGISTRY}/ghcr.io/loft-sh/loft:${VERSION} # Replace ${REGISTRY} and ${VERSION}
    env:
      DEFAULT_IMAGE_REGISTRY: ${REGISTRY} # Replace ${REGISTRY}
    Example of a fully formed registry path

    If your REGISTRY is set to ecr.io/myteam, a fully formed registry path might look like: ecr.io/myteam/ghcr.io/loft-sh/loft:3.0.0

  7. Upgrade the platform​

    Upgrade considerations
    • Review the release notes for the target version to understand any breaking changes or new features.
    • Test the upgrade in a non-production environment before applying it to your production setup.

    Upgrade the platform via:

    To upgrade the platform using the vcluster CLI, update $PLATFORM_VERSION with a valid platform version and run:

    Upgrade the platform using vCluster CLI
    RELEASE_NAMESPACE=vcluster-platform # Replace with the namespace of the platform deployment if different
    PLATFORM_VERSION='' # Set this to a specific version or leave empty for latest

    vcluster platform start --upgrade --version=$PLATFORM_VERSION --namespace=$RELEASE_NAMESPACE --values=vcluster-platform.yaml

Offline license key​

If your cluster does not allow the platform pod to connect to the platform license server (https://admin.loft.sh/*), contact sales@loft.sh to purchase an offline license key or request a trial license key for offline use.

Edit the platform install values as follows to use your offline license key:

Offline license configuration
env:
  LICENSE_KEY: "YOUR_LICENSE_KEY"
info

Apply this configuration during the initial installation process or when upgrading the platform. Include it in your vcluster-platform.yaml file or pass it as a value to the Helm install/upgrade command.