> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sambanova.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-tenancy with vCluster

> [!NOTE]
>
> 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](https://www.vcluster.com/docs/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](https://docs.sambanova.ai/docs/en/v2.3.2/sambastack/getting-started/on-prem.md). What differs between the two models is how the tenant gets worker nodes.

> [!NOTE]
>
> **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](https://docs.sambanova.ai/docs/en/v2.3.2/sambastack/service-administration/model-deployment/deploying-models-and-bundles/deployment-configurations.md). 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.

| | Shared nodes | Private nodes |
| :- | :- | :- |
| Node membership | The node stays in the host cluster, labeled for one tenant | The node joins the tenant control plane only. The host never lists it |
| Who schedules tenant pods | The host scheduler, after the syncer copies pods into the host namespace | The tenant's own scheduler |
| Pod visibility | Tenant pods exist in the host namespace, visible to host admins | Tenant pods exist only in the tenant |
| CNI, kube-proxy, kubelet | The host's | The tenant's own, installed by vCluster |
| Host DaemonSets (monitoring, node feature discovery) | Run on the tenant's node | Don't reach the node |
| Kubernetes version | Tenant API server version is independent; kubelets stay on the host version | Fully independent |
| Where the SambaStack platform runs | The tenant's RDU nodes | The tenant's own CPU nodes, separate from its RDU nodes |
| vCluster edition | Open source | vCluster Platform (free plan, with usage limits) |
| Isolation boundary | A scheduling rule, enforced by the syncer | The node itself |

> [!NOTE]
>
> A dedicated, labeled node pool is still the shared-node model. vCluster's [production guide](https://www.vcluster.com/docs/vcluster/production-guide/choose-worker-node-model) 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

> [card] [Shared nodes](https://docs.sambanova.ai/docs/en/v2.3.2/sambastack/reference-architecture/multi-tenancy/shared-nodes.md)
>
> Label host RDU nodes for a tenant and expose the tenant API through a TLS passthrough gateway. Open-source vCluster.

> [card] [Private nodes](https://docs.sambanova.ai/docs/en/v2.3.2/sambastack/reference-architecture/multi-tenancy/private-nodes.md)
>
> Join dedicated CPU and RDU nodes directly to a tenant control plane. vCluster Platform.

## Additional resources

* [vCluster documentation](https://www.vcluster.com/docs/vcluster/)
* [vCluster production guide: choose a worker node model](https://www.vcluster.com/docs/vcluster/production-guide/choose-worker-node-model)
* [SambaStack quickstart, on-prem](https://docs.sambanova.ai/docs/en/v2.3.2/sambastack/getting-started/on-prem.md)