DOCSEARCHbyAlgolia
Submit Docs

vCluster Platform Documentation

website·Indexed 35 days ago

https://www.vcluster.com/docs/

Documentation for vCluster Platform, covering deployment, configuration, and management of virtual clusters. Includes guides on multi-region deployment on AWS EKS, external database integration (v4.8.0+), OIDC provider setup, KubeVirt integration, and automated cluster registration using Terraform.

Tokens
693.6K
Snippets
2.9K
Records
4.6K
Agent score
66%

What's inside vCluster Platform

  1. Overview of Versioning Template Parameters

    Template parameters allow platform administrators to expose specific configuration fields (e.g., replica counts, image tags, ingress domains) to users during tenant cluster creation without granting access to the full configuration. These parameters are used in SpaceTemplate, App, and ArgoCDApplicationTemplate resources. Values provided by the user are injected into the rendered configuration using Go templating syntax: {{ .Values.parameterName }}.

  2. Overview of vCluster, vCluster Platform, and vMetal

    The vCluster ecosystem consists of three primary components that manage compute clusters from the tenant request down to the physical infrastructure:

    • vCluster: Provides managed Kubernetes, Slurm, inference, and other compute clusters with high isolation and reliability.
    • vCluster Platform: A management layer for self-service tenant management, capacity management, templates, multi-tenant observability, policy, and access control.
    • vMetal: An infrastructure abstraction layer that exposes physical and virtual machines (including GPUs) through a stable Machine API using pluggable provisioning and network drivers.

    In summary, vCluster and vCluster Platform handle the cluster and tenant management, while vMetal connects those clusters to the underlying physical or virtual hardware.

  3. Overview of vCluster Edge Collectors

    Edge collectors are OpenTelemetry Collectors deployed near workloads to scrape or receive metrics and forward them via OTLP to the Write Gateway. Every collector request must include a bearer token and scope headers that correspond to a metrics-writer access key. Collectors should only be deployed after the observability gateway is running and a metrics-writer key has been created.

  4. Overview of vCluster Auto Sleep

    Auto sleep is an Enterprise feature designed for pre-production workloads. It reduces compute resource consumption by putting idle tenant clusters to sleep based on inactivity, a cron schedule, or specific HTTP traffic. Note that sleeping interrupts workloads and deletes standalone Pods that are not managed by a controller.

  6. Overview of vCluster air-gapped deployment

    Deploying vCluster in an air-gapped environment requires that all artifacts typically retrieved from the internet be hosted in a private OCI-compliant registry accessible to the Kubernetes control plane cluster. This includes the vCluster Helm chart and all container images referenced within that chart.

    Critical Constraints:

    • This is an Enterprise-only feature and requires the vCluster Platform to be deployed in air-gapped mode to enable enterprise capabilities.
    • The config.experimental.deploy.vcluster.helm setting does not work with external Helm repositories in air-gapped environments; custom Helm charts from external repositories (e.g., charts.bitnami.com) cannot be used for tenant cluster deployments.

  7. Overview of vCluster VPN

    vCluster VPN enables connectivity between private worker nodes and the vCluster control plane via the vCluster Platform. It is powered by Tailscale (used as a library) and Wireguard, allowing it to traverse complex NAT setups. The primary requirement is that both the control plane and worker nodes can reach the vCluster Platform URL (e.g., https://platform.my-domain.com).

  8. Overview of the vCluster Observability Gateway

    The observability gateway runs in the vCluster Platform namespace and consists of two primary components:

    • otel-gateway: A Write Gateway that receives OTLP metrics.
    • query-proxy: A read proxy that provides a Prometheus-compatible query API for PromQL reads.

    The gateway is configured via an observability connector Secret which defines the metrics backend endpoints and TLS settings.

  9. Overview of GPU and inference autoscaling with Private Nodes

    When using vCluster with Private Nodes, workloads run on dedicated physical nodes. This allows the NVIDIA DCGM Exporter to access real GPU hardware via the NVIDIA Management Library (NVML), ensuring that HPA scaling decisions are based on actual hardware utilization rather than virtualized values.

    There are two primary scaling signal types:

    1. Hardware Metrics: Used for capacity signals (e.g., GPU utilization, memory pressure). The pipeline is: GPU Node $\rightarrow$ DCGM Exporter $\rightarrow$ Prometheus $\rightarrow$ Prometheus Adapter $\rightarrow$ HPA.
    2. Serving Metrics: Used for demand signals (e.g., request concurrency, queue depth, latency). The pipeline is: Inference Pod $\rightarrow$ Prometheus $\rightarrow$ either Prometheus Adapter (for HPA) or KEDA (direct query).

  10. Overview of vcluster Node Providers

    Node providers allow the platform to automatically configure sources for private nodes for tenant clusters. When a tenant cluster requests a node via a node claim, the platform matches the requirements to the cheapest available node type defined in the provider.

    Supported providers include:

    • Terraform (via OpenTofu)
    • KubeVirt (VM-backed nodes)
    • Nvidia Base Command Manager
    • vMetal (Bare metal via Metal3/Ironic)
    apiVersion: management.loft.sh/v1
kind: NodeProvider
metadata:
  name: terraform-example
spec:
  terraform:
    nodeTemplate:
      git:
        repository: https://github.com/my-org/my-repo.git
  nodeTypes:
    - name: medium
      resources:
        cpu: "2"
        memory: 4Gi
      properties:
        instance-type: medium
    - name: large
      resources:
        cpu: "4"
        memory: 8Gi
      properties:
        instance-type: large

  11. Overview of vCluster Standalone mode

    vCluster Standalone is an architecture where the control plane runs as a binary directly on your infrastructure (bare-metal or VM) instead of as a pod in a shared Control Plane Cluster. This provides the strictest tenant isolation. In this mode, the control plane runs on its own independent node, and any additional worker nodes must be configured as private nodes.

  12. Overview of vCluster Platform Audit Logging

    Audit logging provides a chronological record of actions generated by users and applications using the platform API. It tracks activities related to management instance changes (e.g., creating tenant clusters or spaces), changes within tenant clusters, and changes within connected clusters.

    Each request generates audit events at specific stages:

    • RequestReceived: Event generated when the audit handler receives the request.
    • ResponseComplete: Event generated when the response body is completed.
    • Panic: Event generated when a panic occurs.

    Note: Enabling audit logging increases platform memory consumption as context for each request is stored.