vcluster

README

Website • Quickstart • Documentation • Blog • Twitter • Slack

Create fully functional virtual Kubernetes clusters - Each vcluster runs inside a namespace of the underlying k8s cluster. It's cheaper than creating separate full-blown clusters and it offers better multi-tenancy and isolation than regular namespaces.

Why Virtual Kubernetes Clusters?

• Cost Efficient: much cheaper than "real" clusters (single pod and shared resources just like for namespaces)
• Fast Provisioning: can be created and cleaned up again in seconds (great for CI/CD or testing)
• Cluster Scoped Resources: more powerful than simple namespaces (virtual clusters allow users to use CRDs etc.)
• Cluster Wide Permissions: allow users to install apps which require cluster-wide permissions while being limited to actually just one namespace within the host cluster
• Strict isolation: complete separate Kubernetes control plane and access point for each vcluster while still being able to share certain services of the underlying host cluster
• Great for Testing: allow you to test different Kubernetes versions inside a single host cluster which may have a different version than the virtual clusters

Learn more on www.vcluster.com.

Architecture

Learn more in the documentation.

⭐️ Do you like vcluster? Support the project with a star ⭐️

Features

• Certified Kubernetes Distribution - vcluster itself is a certified Kubernetes distribution and is 100% Kubernetes API conform. Everything that works in a regular Kubernetes cluster works in vcluster
• Lightweight & Low-Overhead - Based on k3s, bundled in a single pod and with super-low resource consumption. Other distributions such as k0s or vanilla k8s are also supported
• No Performance Degradation - Pods are scheduled in the underlying host cluster, so they get no performance hit at all while running
• Reduced Overhead On Host Cluster - Split up large multi-tenant clusters into smaller vcluster to reduce complexity and increase scalability. Since most vcluster api requests and objects will not reach the host cluster at all, vcluster can greatly decrease pressure on the underlying Kubernetes cluster
• Easy Provisioning - Create via vcluster CLI, helm, kubectl, Argo or any of your favorite tools (it is basically just a StatefulSet)
• No Admin Privileges Required - If you can deploy a web app to a Kubernetes namespace, you will be able to deploy a vcluster as well
• Single Namespace Encapsulation - Every vcluster and all of its workloads are inside a single namespace of the underlying host cluster
• Easy Cleanup - Delete the host namespace and the vcluster plus all of its workloads will be gone immediately
• Flexible & Versatile - vcluster supports different storage backends (such as sqlite, mysql, postgresql & etcd), customizable sync behaviour, vcluster within vcluster setups, rewriting of kubelet metrics and has many more additional configuration options to fit a multitude of use cases

Quick Start

To learn more about vcluster, open the full getting started guide.

1. Download vcluster CLI

Use one of the following commands to download the vcluster CLI binary from GitHub:

Mac (Intel/AMD)

curl -s -L "https://github.com/loft-sh/vcluster/releases/latest" | sed -nE 's!.*"([^"]*vcluster-darwin-amd64)".*!https://github.com\1!p' | xargs -n 1 curl -L -o vcluster && chmod +x vcluster;
sudo mv vcluster /usr/local/bin;

Mac (Silicon/ARM)

curl -s -L "https://github.com/loft-sh/vcluster/releases/latest" | sed -nE 's!.*"([^"]*vcluster-darwin-arm64)".*!https://github.com\1!p' | xargs -n 1 curl -L -o vcluster && chmod +x vcluster;
sudo mv vcluster /usr/local/bin;

Linux (AMD)

curl -s -L "https://github.com/loft-sh/vcluster/releases/latest" | sed -nE 's!.*"([^"]*vcluster-linux-amd64)".*!https://github.com\1!p' | xargs -n 1 curl -L -o vcluster && chmod +x vcluster;
sudo mv vcluster /usr/local/bin;

Linux (ARM)

curl -s -L "https://github.com/loft-sh/vcluster/releases/latest" | sed -nE 's!.*"([^"]*vcluster-linux-arm64)".*!https://github.com\1!p' | xargs -n 1 curl -L -o vcluster && chmod +x vcluster;
sudo mv vcluster /usr/local/bin;

Windows (Powershell)

md -Force "$Env:APPDATA\vcluster"; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]'Tls,Tls11,Tls12';
Invoke-WebRequest -UseBasicParsing ((Invoke-WebRequest -URI "https://github.com/loft-sh/vcluster/releases/latest" -UseBasicParsing).Content -replace "(?ms).*`"([^`"]*vcluster-windows-amd64.exe)`".*","https://github.com/`$1") -o $Env:APPDATA\vcluster\vcluster.exe;
$env:Path += ";" + $Env:APPDATA + "\vcluster";
[Environment]::SetEnvironmentVariable("Path", $env:Path, [System.EnvironmentVariableTarget]::User);

If you get the error that Windows cannot find vcluster after installing it, you will need to restart your computer, so that the changes to the PATH variable will be applied.

Alternatively, you can download the binary for your platform from the GitHub Releases page and add this binary to your PATH.

2. Create a vcluster

# By default vcluster will connect via port-forwarding
vcluster create vcluster-1 -n host-namespace-1 --connect

# OR: Use --expose to create a vcluster with an externally accessible LoadBalancer
vcluster create vcluster-1 -n host-namespace-1 --connect --expose 

Take a look at the vcluster docs to see how to deploy a vcluster using Helm or Kubectl instead.

3. Use the vcluster

Run in a separate terminal:

export KUBECONFIG=./kubeconfig.yaml

# Run any kubectl, helm, etc. command in your vcluster
kubectl get namespace
kubectl get pods -n kube-system
kubectl create namespace demo-nginx
kubectl create deployment nginx-deployment -n demo-nginx --image=nginx
kubectl get pods -n demo-nginx

4. Cleanup

vcluster delete vcluster-1 -n host-namespace-1

Alternatively, you could also delete the host-namespace using kubectl.

Contributing

Thank you for your interest in contributing! Please refer to CONTRIBUTING.md for guidance.

---

This project is open-source and licensed under Apache 2.0, so you can use it in any private or commercial projects.