Installation

This page covers cluster creation and vNode installation for each supported environment. Before you begin, verify that your target platform meets the system requirements.

Set your environment variables

Modify the following with your specific values to replace them across the whole page:

PLATFORM_HOST

PLATFORM_ACCESS_KEY

# Platform host
PLATFORM_HOST=https://platform-your-domain.com

# Platform access key
PLATFORM_ACCESS_KEY=your-access-key

Platform running in the same cluster

If the vCluster Platform is deployed in the same cluster as vNode, set PLATFORM_HOST to the platform Service's ClusterIP, not its cluster-internal DNS name (for example, https://loft.vcluster-platform).

The vnode-manager enters the node's network namespace to configure containerd. From that namespace it uses the node's DNS resolver, which cannot resolve cluster-internal service names. kube-proxy does route ClusterIP traffic for node-originated connections, so the ClusterIP address works correctly.

Find the ClusterIP of the platform Service:

kubectl get svc loft -n vcluster-platform -o jsonpath='{.spec.clusterIP}'

Then set PLATFORM_HOST=https://<clusterIP>:443.

If a cluster-internal DNS name is used instead, the manager logs dial tcp: lookup ... no such host, containerd is never reconfigured, and tenant pods fail with FailedCreatePodSandbox: no runtime for "vnode" is configured.

If you manage vNode with Argo CD, Flux, or another GitOps tool, store the access key in a Kubernetes secret. See Provide the platform access key via a secret.

Install vNode

Select your platform for cluster setup steps. The Helm install command is the same across all supported environments.

kind

Kubernetes in Docker (kind)

Kubernetes in Docker (kind) lets you run vNode locally by creating Kubernetes clusters inside Docker containers, useful for development and testing.

Create a local kind cluster:

kind create cluster

Deploy vNode:

helm upgrade --install vnode-runtime vnode-runtime -n vnode-runtime \
--repo https://charts.loft.sh --create-namespace \
--set "config.platform.host=https://platform-your-domain.com" \
--set "config.platform.accessKey=your-access-key"

# Add the following only if your platform uses a self-signed certificate:
# --set "config.platform.insecure=true"

EKS

Amazon Elastic Kubernetes Service (EKS)

EKS is a managed Kubernetes service on AWS. vNode cannot be installed on EKS Auto Mode clusters or on nodes with a Bottlerocket base AMI.

Set your cluster configuration. EKS_AMI_FAMILY=AmazonLinux2023 is required — standard AmazonLinux AMIs use older kernels that are incompatible with vNode.

EKS_CLUSTER_NAME=vnode-runtime-test
EKS_REGION=eu-west-1
EKS_NUM_NODES=1
EKS_VERSION=1.30
EKS_MACHINE_TYPE=t3.xlarge
EKS_AMI_FAMILY=AmazonLinux2023

Create the cluster:

eksctl create cluster \
    --name $EKS_CLUSTER_NAME \
    --version $EKS_VERSION \
    --region $EKS_REGION \
    --node-type $EKS_MACHINE_TYPE \
    --node-ami-family $EKS_AMI_FAMILY \
    --nodes $EKS_NUM_NODES \
    --managed

Cluster provisioning takes 15–20 minutes.

Deploy vNode:

helm upgrade --install vnode-runtime vnode-runtime -n vnode-runtime \
--repo https://charts.loft.sh --create-namespace \
--set "config.platform.host=https://platform-your-domain.com" \
--set "config.platform.accessKey=your-access-key"

# Add the following only if your platform uses a self-signed certificate:
# --set "config.platform.insecure=true"

GKE

Google Kubernetes Engine (GKE)

GKE is a managed Kubernetes platform on Google Cloud. vNode cannot be installed on GKE clusters with Autopilot enabled.

Set your cluster configuration:

GKE_CLUSTER_NAME=vnode-runtime-test
GKE_ZONE=europe-west2-a
GKE_MACHINE_TYPE=n4-standard-4
GKE_NUM_NODES=1

Create the cluster:

gcloud container clusters create $GKE_CLUSTER_NAME \
    --zone $GKE_ZONE \
    --machine-type $GKE_MACHINE_TYPE \
    --num-nodes $GKE_NUM_NODES \
    --release-channel "regular"

Fetch credentials for kubectl:

gcloud container clusters get-credentials $GKE_CLUSTER_NAME --zone $GKE_ZONE

Deploy vNode:

helm upgrade --install vnode-runtime vnode-runtime -n vnode-runtime \
--repo https://charts.loft.sh --create-namespace \
--set "config.platform.host=https://platform-your-domain.com" \
--set "config.platform.accessKey=your-access-key"

# Add the following only if your platform uses a self-signed certificate:
# --set "config.platform.insecure=true"

AKS

Azure Kubernetes Service (AKS)

AKS is a managed Kubernetes environment on Microsoft Azure. vNode requires Linux kernel 6.1 or later; on AKS this means Kubernetes 1.32.0 or later with the --os-sku AzureLinux flag.

Set your cluster configuration:

AKS_RESOURCE_GROUP=my-resource-group
AKS_CLUSTER_NAME=my-cluster
AKS_NODE_COUNT=1
AKS_MACHINE_TYPE=Standard_D4s_v6
AKS_LOCATION=westeurope
AKS_KUBERNETES_VERSION=1.32.0

Create the cluster:

az aks create --yes \
  --resource-group $AKS_RESOURCE_GROUP \
  --name $AKS_CLUSTER_NAME \
  --node-count $AKS_NODE_COUNT \
  --node-vm-size $AKS_MACHINE_TYPE \
  --location $AKS_LOCATION \
  --kubernetes-version $AKS_KUBERNETES_VERSION \
  --os-sku AzureLinux \
  --generate-ssh-keys

Fetch credentials for kubectl:

az aks get-credentials --overwrite-existing \
  --resource-group $AKS_RESOURCE_GROUP \
  --name $AKS_CLUSTER_NAME

Deploy vNode:

helm upgrade --install vnode-runtime vnode-runtime -n vnode-runtime \
--repo https://charts.loft.sh --create-namespace \
--set "config.platform.host=https://platform-your-domain.com" \
--set "config.platform.accessKey=your-access-key"

# Add the following only if your platform uses a self-signed certificate:
# --set "config.platform.insecure=true"

Other

Other distributions

The following distributions are generally compatible with vNode:

• K3s — lightweight Kubernetes for resource-constrained environments
• K3d — K3s in Docker, useful for local development
• Rancher RKE — Rancher Kubernetes Engine
• Custom self-managed Kubernetes installations

Before installing on any distribution not listed here, verify that:

• The distribution uses containerd as its container runtime.
• The kernel version is 6.1 or later.
• The Kubernetes version is 1.24 or later.

Docker Desktop and Orbstack use cri-dockerd, and OpenShift uses cri-o — none of these are supported.

Deploy vNode:

helm upgrade --install vnode-runtime vnode-runtime -n vnode-runtime \
--repo https://charts.loft.sh --create-namespace \
--set "config.platform.host=https://platform-your-domain.com" \
--set "config.platform.accessKey=your-access-key"

# Add the following only if your platform uses a self-signed certificate:
# --set "config.platform.insecure=true"

Non-standard containerd paths

If your cluster uses non-standard paths for containerd, kubelet, or CNI components, override them in your Helm values:

config:
  # The root directory of containerd. Default: /var/lib/containerd
  containerdRoot: ""
  # The state directory of containerd. Default: /run/containerd
  containerdState: ""
  # The config path for containerd. Default: /etc/containerd/config.toml
  containerdConfig: ""
  # The directory where to copy the shims to. Default: /usr/local/bin
  containerdShimDir: ""
  # The root path for the kubelet. Default: /var/lib/kubelet
  kubeletRoot: ""
  # The root path for the kubelet pod logs. Default: /var/log
  kubeletLogRoot: ""
  # The directory where the cni configuration is stored. Default: /etc/cni/net.d
  cniConfDir: ""
  # The directory where the cni binaries are stored. Default: /opt/cni/bin
  cniBinDir: ""

Use with Nvidia GPU Operator

vNode is compatible with the Nvidia GPU Operator. The only requirement is that CDI must be enabled.

Enable CDI during GPU Operator installation:

helm upgrade gpu-operator nvidia/gpu-operator --install \
    -n gpu-operator --create-namespace \
    --set cdi.enabled=true

Or patch an existing GPU Operator installation:

kubectl patch clusterpolicies.nvidia.com/cluster-policy --type='json' \
    -p='[{"op": "replace", "path": "/spec/cdi/enabled", "value":true}]'