Skip to main content
vCluster is a third-party product. SambaNova doesn’t maintain, endorse, or audit it. This reference architecture is provided for informational purposes and may become outdated as vCluster changes.
A SambaStack installation serves one organization: one API endpoint, one user directory, one set of model deployments. When several teams or customers each need their own SambaStack, you can give each one a virtual cluster on the same host Kubernetes cluster instead of a separate physical cluster. vCluster runs a tenant’s Kubernetes control plane (API server, controller manager, etcd) as pods in a namespace of the host cluster. The tenant gets its own kubeconfig and installs SambaStack with the standard on-prem procedure. What differs between the two models is how the tenant gets worker nodes.
Target audience: Platform teams that operate one SambaStack host cluster for more than one tenant, such as internal teams, business units, or customers of a managed inference service.

​
What every tenant gets

  • Its own Kubernetes API. Tenant users and automation use a tenant kubeconfig. They never see the host cluster or other tenants.
  • Its own SambaStack. Each tenant installs the SambaStack Helm charts into its virtual cluster, with its own hostnames, TLS certificates, user directory, and model deployments.
  • Whole RDU nodes. A SambaStack deployment occupies whole nodes, and nodes are never shared between tenants. On SambaRack SN40L-16, the smallest tenant is one node with 16 RDUs. Plan two nodes for a tenant whose model must survive a node failure, and at least four for the high-throughput disaggregated configuration. With private nodes, add at least two CPU nodes per tenant for the SambaStack platform.
  • Control plane off the RDUs. Tenant control planes run on a CPU node pool of the host cluster, so they consume none of the tenant’s RDU capacity.

​
Two node models

vCluster has two ways to give a tenant worker nodes. The choice is made at tenant creation (privateNodes.enabled) and can’t be changed without redeploying the tenant.
A dedicated, labeled node pool is still the shared-node model. vCluster’s production guide states that shared nodes are “a supported model for trusted tenants, not a security boundary for untrusted tenants with cluster or scheduler access or arbitrary workload execution.”

​
Choosing a model

Choose private nodes if any of these is true:
  • Tenants are external: customers, partners, or resold capacity.
  • Tenants get cluster-admin or scheduler access to their virtual cluster.
  • Tenants run workloads you don’t control, or a regulation requires node-level separation.
  • RDU maintenance must not interrupt the tenant’s API, UI, or login.
Choose shared nodes when tenants are trusted teams inside your organization and the platform team keeps the tenant’s cluster-admin kubeconfig. Shared nodes need less setup: no vCluster Platform, no node joining, and the host’s RDU node software stays in place.

​
Reference setups

Shared nodes

Label host RDU nodes for a tenant and expose the tenant API through a TLS passthrough gateway. Open-source vCluster.

Private nodes

Join dedicated CPU and RDU nodes directly to a tenant control plane. vCluster Platform.

​
Additional resources