Skip to main content
Version: v4.x (Stable: v4.2.0)

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​

note

Although the platform might 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

  • Ensure that the required network ports are open.

    info

    The platform requires open ports for API extensions, webhooks, and cost monitoring. In private GKE clusters, ensure firewall rules allow traffic from the Kubernetes master to platform components.

    • 8443 – API service extension for cluster communication (v1.cluster.loft.sh)
    • 9443 – Webhook validation and enforcement (loft webhook)
    • 9444 – Management API for platform administration (v1.management.loft.sh)
    • 9090 – Prometheus metrics proxy for cost monitoring

    For more information, see Networking to learn about port and firewall rules.

Deployment​

Offline images​

For clusters unable to pull images from Docker Hub, you must 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 or upgrade command.

Log in​

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 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.
  • Sleep and wakeup - How to temporarily scale down unused virtual clusters and bring them back up.