vcluster

Create a virtual cluster in a specific namespace

$ vcluster create [vcluster_name] [[-n|--namespace]] [namespace]

$ vcluster connect [vcluster_name] [[-n|--namespace]] [namespace] --local-port [port] --insecure

$ vcluster list

$ vcluster delete [vcluster_name]

$ vcluster platform list

$ vcluster platform create [vcluster_name] [[-n|--namespace]] [namespace]

$ vcluster platform connect [vcluster_name] [[-n|--namespace]] [namespace]

$ vcluster platform delete [vcluster_name] [[-n|--namespace]] [namespace]

vcluster [command] [flags]
vcluster create [vcluster-name] [flags]
vcluster connect [vcluster-name] [flags]
vcluster delete [vcluster-name] [flags]
vcluster list [flags]

[vcluster-name]
    The name of the virtual cluster to operate on.

-n, --namespace [namespace]
    Specifies the host cluster namespace where the vcluster is located or will be created. Defaults to 'vcluster' or current kube-context's namespace.

--kube-config [path]
    Path to the kubeconfig file to use for the host cluster or to write vcluster connection details.

--context [context-name]
    The Kubernetes context on the host cluster to use.

--set [key=value]
    Used with 'create' to set Helm chart values for the vcluster deployment (e.g., `--set controlPlane.distro=k3s`). Can be specified multiple times.

-d, --distro [distro]
    Specifies the Kubernetes distribution for the virtual cluster (e.g., 'k3s', 'k8s', 'eks', 'microk8s', 'kind'). Used with 'create'.

--version [version]
    Specifies the version of the vcluster Helm chart to deploy. Used with 'create'.

--expose
    Exposes the vcluster API server via an ingress or service on the host cluster. Used with 'create'.

--connect
    Automatically connects to the virtual cluster after creation, updating the local kubeconfig. Used with 'create'.

--update-current
    Updates the current kube-context to connect to the vcluster. Used with 'connect'.

--server [port]
    Specifies the local port for the proxy server when connecting to a vcluster. Used with 'connect'.

--debug
    Enables debug logging for more verbose output.

--help
    Displays help information for the command or subcommand.

vcluster is a powerful open-source tool that enables the creation of highly efficient, isolated virtual Kubernetes clusters within a single, larger host Kubernetes cluster. Instead of provisioning separate, full-fledged Kubernetes clusters for each team, project, or development environment, vcluster allows multiple virtual clusters to share the underlying resources of a host cluster while maintaining complete isolation at the API level. Each vcluster provides its own API server, controller manager, and data store, appearing to users as a regular, dedicated Kubernetes cluster. This architecture significantly reduces resource consumption, operational overhead, and spin-up times compared to traditional cluster provisioning. It's an ideal solution for multi-tenancy, enabling developers to work in isolated sandboxes, facilitating CI/CD pipelines with ephemeral environments, and significantly lowering infrastructure costs. Workloads within a vcluster are transformed and run as pods and other resources directly within a designated namespace on the host cluster, ensuring efficient resource utilization and simplified management.

While vcluster provides strong isolation at the API level, it's important to remember that all virtual cluster workloads run as pods within the host cluster's namespace. This means that host cluster resources (CPU, memory, network) are shared, and resource quotas are applied at the host namespace level. Advanced network policies, CNI plugins, or storage class configurations on the host might require specific attention or configuration within the vcluster to function as expected. vcluster is not designed for complete hypervisor-level isolation and relies on Kubernetes' native multi-tenancy capabilities and network segmentation.

A vcluster operates by deploying a dedicated pod in the host cluster that contains its own API server, controller manager, and a lightweight data store (e.g., sqlite or etcd). When users interact with the vcluster's API, the vcluster controller intercepts these requests and transforms the virtual resources (e.g., a virtual pod) into corresponding host resources (a real pod in the host namespace). This 'synchronization' ensures that workloads defined within the vcluster run as actual pods on the host cluster, while providing the user with the illusion of a fully dedicated cluster.

The primary use cases for vcluster include multi-tenancy scenarios where different teams or projects require isolated Kubernetes environments without the overhead of dedicated clusters. It's highly beneficial for CI/CD pipelines to create fast, ephemeral testing environments. Developers can use vcluster to get personal, isolated sandboxes for application development and testing, ensuring their changes don't interfere with others. It also provides a cost-effective way to manage numerous Kubernetes environments for demos, training, or transient workloads.

vcluster was developed by Loft Labs, an organization focused on developer tooling for Kubernetes. It was open-sourced to address the growing need for lightweight, isolated development and CI/CD environments in Kubernetes. Prior to vcluster, achieving such isolation often required provisioning expensive and resource-intensive full Kubernetes clusters. vcluster gained rapid adoption due to its efficiency and the ease with which it allows developers to obtain personal, ephemeral clusters without significant overhead. Its development focuses on providing a familiar Kubernetes experience while optimizing resource utilization on a shared host.

kubectl(1): The primary command-line tool for interacting with Kubernetes clusters., helm(1): A package manager for Kubernetes, used by vcluster for deploying virtual clusters., k3s(8): A lightweight Kubernetes distribution often used as a backend for virtual clusters., kind(1): Kubernetes IN Docker, a tool for running local Kubernetes clusters that shares some conceptual similarities for local development.