vCluster Platform

A powerful Kubernetes platform for managing virtual clusters, multi-tenancy, and cluster sharing

vCluster Platform provides a single pane of glass that lets you connect your clusters, deploy virtual clusters, configure user access, and reduce operational costs. Built on top of Kubernetes, it enables teams to efficiently share cluster resources while maintaining strong isolation and self-service capabilities.

🚀 Features

Core Platform Features

Projects: Highest organizational unit for logically grouping resources by team or division with role-based access controls (RBAC)
Clusters: Connect to and manage multiple physical Kubernetes clusters, deploying spaces, virtual clusters, and apps as needed
Virtual Clusters: Lightweight virtual Kubernetes clusters that run inside a namespace within the host physical cluster - ideal for development, testing, and production workloads
Apps: Define and deploy applications with configurable parameters across clusters, spaces, and virtual clusters using Kubernetes Manifests, bash scripts, Helm charts, and more
Cost Reduction Tools:
- Sleep Mode: Put Kubernetes namespaces to sleep (sets replicas: 0 for all replica-controlled resources), reducing cloud costs by up to 70%
- Auto Delete: Configure auto-deletion for inactive virtual clusters
- Inactivity Detection: Automatically detect and respond to namespace inactivity
Multi-Tenancy: Granular RBAC at project, space, and virtual cluster levels
GitOps Ready: All resources are defined as Custom Resource Definitions (CRDs) for GitOps workflows
RESTful API: Comprehensive OpenAPI 3.0-compliant API for programmatic access and automation

🏃 Quick Start

Prerequisites

Kubernetes cluster (v1.20+) with administrator access
Helm v3.10+ installed (Helm Installation Guide)
kubectl installed and configured (Install kubectl)
License Key: A LoftLabs license key is required (contact sales@loft.sh for a license or trial)

Resource Requirements

Pod Resources:
- Requests: memory: 256Mi, cpu: 200m
- Limits: memory: 4Gi, cpu: 2
Network Ports: Ensure the following ports are open:
- 8443 – API service extension for cluster communication (v1.cluster.loft.sh)
- 9443 – Webhook validation and enforcement (loft webhook)
- 9444 – Management API for platform administration (v1.management.loft.sh)
- 9090 – Prometheus metrics proxy for cost monitoring
Egress Traffic: Allow egress to https://admin.loft.sh/* (HTTPS, port 443) for license retrieval and validation

Installation Methods

Option 1: Using vCluster CLI (Recommended)

The vCluster CLI is the preferred method for deploying the platform. See the Quick Start Guide for detailed instructions.

# Download and install vCluster CLI
# macOS (Intel/AMD)
curl -L -o vcluster "https://github.com/loft-sh/vcluster/releases/latest/download/vcluster-darwin-amd64" && \
  sudo install -c -m 0755 vcluster /usr/local/bin && rm -f vcluster

# Verify installation
vcluster --version

# Deploy the platform
vcluster platform start

The CLI automatically opens the UI in your browser and logs you in. You'll be prompted to create an administrator user.

Option 2: Using Helm

See the Helm Installation Guide for detailed instructions.

# Add the Loft Helm repository
helm repo add loft https://charts.loft.sh
helm repo update

# Deploy vCluster Platform
RELEASE_NAME=vcluster-platform
RELEASE_NAMESPACE=vcluster-platform

helm upgrade $RELEASE_NAME vcluster-platform \
  --install \
  --repo https://charts.loft.sh/ \
  --namespace $RELEASE_NAMESPACE \
  --create-namespace \
  --set admin.username=admin \
  --set admin.password=your-secure-password

Option 3: Using ArgoCD (GitOps)

For GitOps deployments, see the ArgoCD Installation Guide for managing the platform deployment with ArgoCD or other GitOps tools.

Access the Platform

After installation, you can access the platform in several ways:

Loft Router (Default): If loftHost is not configured, a random domain is automatically provisioned. Retrieve it with:

kubectl get secret loft-router-domain \
  -n vcluster-platform \
  -o jsonpath="{.data.domain}" | base64 --decode

Custom Ingress: If you configured an ingress, access via your custom domain

Port Forward: For local access:

kubectl port-forward -n vcluster-platform svc/vcluster-platform 8080:80

Default Credentials

If not set in your values.yaml, the default credentials are:

Username: admin
Password: my-password

⚠️ Security Note: It is strongly recommended to change these default credentials immediately after first login.

🏗️ Architecture

vcluster Platform consists of several key components:

Platform Controller: Core orchestration engine managing virtual clusters, accounts, and resources
API Server: RESTful API server exposing OpenAPI-compliant endpoints
Webhook Server: Validating and mutating webhooks for resource management
Agent: Lightweight agent deployed to managed clusters for multi-cluster operations

┌─────────────────────────────────────────────────────────┐
│                  vcluster Platform                      │
│                                                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
│  │   API Server │  │  Controller  │  │   Webhook    │ │
│  └──────────────┘  └──────────────┘  └──────────────┘ │
│                                                          │
│  ┌──────────────────────────────────────────────────┐   │
│  │         Virtual Cluster Management               │   │
│  │  • Create/Delete Virtual Clusters                │   │
│  │  • Sleep/Wake Operations                         │   │
│  │  • Resource Quotas & Limits                      │   │
│  └──────────────────────────────────────────────────┘   │
│                                                          │
│  ┌──────────────────────────────────────────────────┐   │
│  │         Multi-Tenancy & Isolation                │   │
│  │  • Account Management                            │   │
│  │  • Namespace Templates                           │   │
│  │  • RBAC & Security Policies                      │   │
│  └──────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

📦 Installation & Configuration

Recommended Configuration

When deploying with Helm, it's recommended to explicitly set these values:

admin:
  username: my-own-username
  password: my-secure-password

config:
  audit:
    enabled: true
  loftHost: vcluster-platform.mytld.com  # Publicly resolvable hostname

ingress:
  enabled: true
  host: vcluster-platform.mytld.com
  tls:
    enabled: true

# Environment variables for proxy configuration (if needed)
env:
  NO_PROXY: localhost,127.0.0.1,.svc,.svc.cluster.local,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16
  no_proxy: localhost,127.0.0.1,.svc,.svc.cluster.local,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16

Loft Router

vCluster Platform provides a hosted domain service called Loft Router that enables you to trial the platform using a hosted domain. This is enabled by default and particularly useful when you cannot use your own DNS.

To disable Loft Router, either:

Explicitly set config.loftHost and config.devPodSubDomain, or
Set the environment variable DISABLE_LOFT_ROUTER=true

Air-Gapped Installation

For environments without internet access, see the Air-Gapped Installation Guide for detailed instructions on:

Setting up a private OCI-compliant registry
Populating the registry with container images and Helm charts
Configuring vCluster Platform and agents for offline use

See chart/values.yaml for all available configuration options.

📚 API Documentation

vCluster Platform exposes a comprehensive RESTful API that is fully OpenAPI 3.0 compliant. The API documentation is automatically generated and synced to this repository.

API Specs

OpenAPI Specification: api/openapi-spec/openapi.yaml
Swagger JSON: api/openapi-spec/swagger.json
Swagger Paths: api/openapi-spec/swagger.paths.json

API Endpoints

The API provides endpoints for:

Management API (/apis/management.loft.sh/v1/): Core platform management operations
Cluster API (/apis/v1.cluster.loft.sh/): Cluster communication and management
Virtual Cluster API: Virtual cluster lifecycle management
Project API: Project and resource management
User & Access API: User management and access control

Using the API

# Get API versions
curl https://your-vcluster-platform/api/apis/

# List virtual clusters
curl -H "Authorization: Bearer $TOKEN" \
  https://your-vcluster-platform/api/a

Loft

Install / Use

README