Skip to main content

Air-Gapped Install

Air-Gapped / Offline / VPC Clusters​

If your cluster is air-gapped, within a VPC or restricts network connectivity in other ways, you may run into issues validating the vCluster Platform license and pulling container images required for vCluster Platform.

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

To solve not being able to pull images from Docker Hub, you can use a private image registry to host your own copies of the vCluster Platform images that your cluster can reach.

Prerequisites​

  • A running air-gapped Kubernetes cluster v1.26.x, v1.27.x, or v1.28.x
  • On installation computer:
    • kubectl (check via kubectl version)
    • helm (check with helm version)
    • docker (check with docker version)
    • A kube-context with admin access to this Kubernetes cluster (check with kubectl auth can-i create clusterrole -A)
    • [Optional] An offline license key for vCluster Platform (provided by Loft)
  • [Optional] A private Docker registry that the installer computer and the air-gapped Kubernetes cluster can access

Resource requirements​

  • Pod Resource Requirements:

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

  • Open network ports:

    Since vCluster Platform installs webhooks and API server extensions into the cluster, the Kubernetes master needs to be able to communicate with the vCluster Platform pods. For example - in private GKE clusters the Kubernetes master and nodes are not in the same subnetwork, and cannot communicate directly with each other on every port. Hence, you need to ensure that there is a firewall rule that allows incoming traffic from the Kubernetes master network to the tcp ports:

    • 8443 (vCluster Platform agent api service extension - v1.cluster.loft.sh)
    • 9443 (vCluster Platform agent webhook & loft webhook)
    • 9444 (vCluster Platform api service extension - v1.management.loft.sh)

Offline Images​

If your cluster is not able to pull images from Docker Hub, you have to push the vCluster Platform images into your private registry. To find out which images are required, we publish a file called loft-images.txt with each vCluster Platform release.

Follow these instructions to download all vCluster Platform and import them to your private registry:

  1. Set the VERSION variable to the vCluster Platform version you want to upgrade to OR set it to the current version using:

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

  2. Set your private registry as variable:

    REGISTRY=ecr.io/myteam      # THIS SHOULD BE A PREFIX / DO NOT INCLUDE ANY LOFT_IMAGE PATHS

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

    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.sh --image-list loft-images.txt

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

    ./push-images.sh --registry ${REGISTRY}

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

    image: ${REGISTRY}/ghcr.io/loft-sh/loft:${VERSION} # Replace ${REGISTRY} and ${VERSION}
    env:
      DEFAULT_IMAGE_REGISTRY: ${REGISTRY} # Replace ${REGISTRY}

  7. Upgrade vCluster Platform via:

    To upgrade vCluster Platform via vCluster CLI, update $PLATFORM_VERSION with a valid vCluster Platform version and run:

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

Offline License Key​

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

You can edit vCluster Platform install values as follows to use your offline license key:

env:
  LICENSE_KEY: "YOUR_LICENSE_KEY"