Enterprise-Only Feature

This feature is an Enterprise feature. See our pricing plans or contact our sales team for more information.

Deploy Private Nodes in an air-gapped environment

This document explains how to deploy Private Nodes in environments without internet access, known as air-gapped environments.

important

Enterprise features require the vCluster Platform.

If you deploy a vCluster in an air-gapped environment and want to use enterprise features, you must also deploy the platform in air-gapped mode and connect the vCluster to it.

Overview

When deploying Private Nodes, there are artifacts that are typically accessed using an internet connection, but without access to the internet, these artifacts need to be available to the Kubernetes cluster through a private registry:

• Kubernetes Control-Plane image—Pulled from loft-sh/kubernetes registry.

After ensuring that Kubernetes Control-Plane image is present on the server which you want to use as Private Node, and uploading the required images to your private registry, create the vcluster.yaml configuration file and follow the installation steps.

Prerequisites

• Access to a node that satisfies the node requirements

Registry requirements

• OCI-compliant private registry - A private registry accessible to the Private Nodes, vCluster Control-Plane and a separate, internet-connected machine.
• Ability to push images to your private registry.

Deployment requirements

Ensure you have the following:

• Access to pull the images from the private registry

• On the internet-connected machine for populating the registry:

  • wget installed
  • docker installed
  • You are logged into GitHub Container Registry

Populate images to a private registry

Each vCluster release includes multiple assets to help you upload the images to your private registry.

• images-private-nodes.txt - The required images to run Private Node, which assumes using the default Kubernetes version.
• images-private-nodes-optional.txt - An optional set of images needed for worker node daemonsets and agents.
• download-images.sh - A bash script that quickly iterates over all the images files to pull them and package them into a tarball to a machine that has internet access.
• push-images.sh - A bash script that takes the tarball generated from the download script to push them to your private registry.

Pull and push images

Modify the following with your specific values to replace on the whole page and generate copyable commands:

VCLUSTER_VERSION

REGISTRY

1. Download the assets from the vCluster GitHub release and make the scripts executable.

   note

   The images-private-nodes.txt contains all required images for the default Kubernetes version.

   
   wget https://github.com/loft-sh/vcluster/releases/download/v0.29.1/images-private-nodes.txt
   wget https://github.com/loft-sh/vcluster/releases/download/v0.29.1/download-images.sh
   wget https://github.com/loft-sh/vcluster/releases/download/v0.29.1/push-images.sh
   
   chmod +x ./download-images.sh
   chmod +x ./push-images.sh
       

2. Run download-images.sh to pull all images and create a tarball of the images.

   Review the output to confirm all images were pulled successfully and packaged in the tarball.

   Download and package images

   ./download-images.sh --image-list images-private-nodes.txt

   Multi-platform support

   If you need to support multiple CPU architectures (e.g., AMD64 and ARM64), use the --platforms flag to specify which platforms to download. This is useful when your cluster has nodes with different architectures.

   Download images for multiple platforms

   ./download-images.sh --platforms "linux/amd64,linux/arm64" --image-list images-private-nodes.txt

3. Run push-images.sh to upload all required images to your private registry.

   When pushing images into your private registry, the public private registry is removed and only the repository and image name are pushed. This allows vCluster to set your private registry to use for all images used in deploying vCluster.

   Push images to private registry

   
   ./push-images.sh --registry ecr.io/myteam --image-list images-private-nodes.txt
       

   Additional push options

   Multi-platform support: If you downloaded images for multiple platforms, specify the same --platforms flag when pushing:

   
   ./push-images.sh --registry ecr.io/myteam --image-list images-private-nodes.txt --platforms "linux/amd64,linux/arm64"

   Insecure registry: If your private registry uses HTTP instead of HTTPS, add the --insecure flag:

   
   ./push-images.sh --registry ecr.io/myteam --image-list images-private-nodes.txt --insecure

4. Optional: By default, Private Node uses Flannel for CNI and Local Path Provisioner. To download and push these, download the images-private-nodes-optional.txt file.

   The images-private-nodes-optional.txt includes images for various optional configurations. You can edit the file and keep only the images you need, removing those for unused features or versions.

   note

   The images-private-nodes-optional.txt may include multiple Kubernetes distributions, versions, or other feature-dependent images. You can edit the file to retain only what's necessary for your deployment.

   Pull, package, and push all optional images

   
   wget https://github.com/loft-sh/vcluster/releases/download/v0.29.1/images-private-nodes-optional.txt
   
   ./download-images.sh --image-list images-private-nodes-optional.txt --images vcluster-images-optional.tar.gz
   ./push-images.sh --registry ecr.io/myteam --image-list images-private-nodes-optional.txt
       

   tip

   You can also use the --platforms and --insecure flags with these commands if needed, as described in the previous steps.

Configure vCluster

The vcluster.yaml file contains all configuration settings for your vCluster deployment.

Use a private registry without credentials

Set the default private registry that doesn't have authentication. Authenticated private registries are not supported in this version.

Setting the private registry

controlPlane:
advanced:
  defaultImageRegistry: ecr.io/myteam

Redirect workload image pulls on joined nodes

The defaultImageRegistry setting above only affects the images vCluster deploys for its own control plane components. Workloads scheduled onto joined Private Nodes pull their images through each node's containerd runtime, which reaches out to public registries such as docker.io and ghcr.io by default. In an air-gapped environment, those pulls fail.

To redirect them to your private registry, configure containerd registry mirrors through privateNodes.joinNode.containerd.registry. As each node joins, vCluster renders these settings into a containerd hosts.toml file on the node, following the containerd registry host model.

Joined nodes only

This mechanism applies to real Private Nodes joined through kubeadm, such as bare-metal servers or cloud VMs. It does not apply to vind, whose Docker driver ignores this setting and serves images through a host-cache registry proxy instead. For vind, see Deploy vind in an air-gapped environment.

Add the following to your vcluster.yaml. Each key under mirrors is the registry you want to redirect, and each hosts[].server entry is the mirror endpoint that containerd contacts in its place. If you omit capabilities, containerd defaults to pull and resolve.

Modify the following with your specific values to generate a copyable command:

MIRROR_ENDPOINT

Configure containerd registry mirrors

privateNodes:
  joinNode:
    containerd:
      registry:
        mirrors:
          # Redirect Docker Hub pulls to your internal registry
          "docker.io":
            hosts:
              - server: https://registry.internal
                capabilities: ["pull", "resolve"]
          # Redirect GitHub Container Registry pulls to your internal registry
          "ghcr.io":
            hosts:
              - server: https://registry.internal
                capabilities: ["pull", "resolve"]

If your private registry requires authentication, add an auth section keyed by the registry host. vCluster writes these credentials into the node's containerd configuration.

Modify the following with your specific values to generate a copyable command:

REGISTRY_HOST

USERNAME

PASSWORD

Authenticate to the mirror registry

privateNodes:
  joinNode:
    containerd:
      registry:
        auth:
          # Credentials for your internal registry
          "registry.internal":
            username: my-user
            password: my-password

After your private registry is populated with the required images, you can proceed with adding Private Nodes.

Installation

For further steps follow the primary guide