Skip to main content
Version: main 🚧

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​

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:

  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

  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.sh --registry ecr.io/myteam --image-list images-private-nodes.txt

  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.


    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

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.


controlPlane:
advanced:
  defaultImageRegistry: ecr.io/myteam

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