Skip to main content

Deploy in Air-Gapped Environments

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​

  • Administrator access to a Kubernetes cluster: See Accessing Clusters with kubectl for more information. Your current kube-context must have administrative privileges, which you can 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.

  • helm installed: Helm v3.10 is required for deploying the platform. Refer to the Helm Installation Guide if you need to install it.

  • kubectl installed: Kubernetes command-line tool for interacting with the cluster. See Install and Set Up kubectl for installation instructions.

  • A private Docker registry accessible to both the installer computer and the air-gapped Kubernetes cluster

Optional prerequisites​

  • On the installation computer:
    • docker (verify with docker version)
    • An offline license key for the platform (provided by Loft)

Supported Kubernetes versions​

  • A running air-gapped Kubernetes cluster with one of the supported versions: v1.30.x, v1.31.x, or v1.32.x
note

Although the platform may work with other versions, using the supported versions is recommended to avoid potential issues.

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)

Deployment​

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.

warning

When using virtual clusters in air-gapped environments, the config.experimental.deploy.vcluster.helm configuration setting does not work with external Helm repositories since they cannot be accessed. This means custom Helm charts from repositories like charts.bitnami.com cannot be used for virtual cluster deployments.

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

Configuration​

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.

Login​

If the loftHost is not configured in the platform settings, a random domain is automatically provisioned. You can retrieve this domain from the loft-router-domain secret located in the installation namespace. This domain is essential for accessing the platform interface and configuring other services.

info

You can easily configure your own custom domain.

Follow these steps to retrieve the domain name from the secret:

To retrieve the domain from the secret on Linux, run:

Retrieve domain value.
# Set the namespace where the platform is installed
PLATFORM_NAMESPACE=vcluster-platform

echo "https://$(kubectl get secret loft-router-domain \
  -n "$PLATFORM_NAMESPACE" \
  -o jsonpath="{.data.domain}" \
  | base64 --decode)"
note

If you encounter an error or the secret is not found, ensure that the platform is properly installed and that you have the necessary permissions to access secrets in the specified namespace.

Default credentials​

If the username and password are not set in your values.yaml, the default credentials are:

  • Username: admin
  • Password: my-password
info

It is strongly recommended to change these default credentials for security reasons. You can reset the administrator password.

Next steps​

Create virtual clusters​

After logging into the UI, you'll be able to start creating virtual clusters immediately. You're automatically part of a project called Default Project.

Click on "New Virtual Cluster" and "Create" to spin one up to try out.

tip

Find more information about creating virtual clusters in the create virtual clusters section.

Otherwise, read more about some primary concepts:

  • Projects - How resources can be grouped together into different projects
  • Virtual Clusters - How to create and manage virtual clusters
  • Templates - How to use templates to control what type of resources that can be made
  • Host Clusters - How to add more host clusters to the platform