Choose a worker node model

Shared and private nodes aren't interchangeable settings you tune for cost or performance. They're a security boundary decision, and vCluster locks it at deployment time. Make this decision before you pick a production path or deploy a worker node model, not after.

Private nodes dedicate worker nodes to a single tenant clusterTenant clusterA fully isolated Kubernetes environment provisioned for a single tenant. Each tenant cluster has its own API server, controller manager, and resource namespace, backed by a virtualized control plane hosted on a control plane cluster. From the tenant's perspective it behaves exactly like a standard Kubernetes cluster.Related: Control plane cluster, Tenant cluster, so no other tenant's workloads share that node or its kernel. Shared nodes run multiple tenant clusters' workloads on the same worker nodes, isolated from each other at the control plane, API, and namespace level, but not at the kernel. See Architecture for the full mechanics.

Provisioning through a vCluster Platform template?

This decision may already be made for you. Templates fix privateNodes.enabled in the underlying vcluster.yaml. You'll see the resolved config before confirming creation, but you can only change it if the template allows customization. Check with whoever owns the template, or see Create templates if you administer them yourself.

This page covers customer-facing and other production offerings where tenants aren't your own trusted staff. "Trusted" here means an explicit, enforced trust domain, not just familiarity. If your tenants are internal and meet that bar, skip to trusted internal tenants for the full criteria.

Decide with three questions

For a customer-facing offering, use private nodes if the answer to any of these is yes.

1. Are you building Kubernetes-as-a-Service, Slurm-as-a-Service, or otherwise delivering a cluster or scheduler environment to the customer?
2. Does the customer get direct access to that cluster or scheduler, whether Kubernetes, Slurm, or an inference control plane, beyond narrowly scoped, read-only visibility such as viewing logs or status for their own jobs or pods?
3. Can the customer run custom workloads, whether by supplying images, code, or model artifacts directly, or by defining jobs, pods, or other workload resources through a higher-level API?

Shared nodes may be suitable only when all three answers are no. You own the workload definitions and the cluster or scheduler's configuration and operations, and the customer only consumes your application or API. Treat "may be suitable" as provisional, not final, until you apply the shared node hardening guide and explicitly accept the shared-kernel exposure.

Decision tree for choosing between private and shared nodes

Any "yes" to the first three questions routes to private nodes, regardless of the other answers. Three "no" answers proceed to the hardening and risk-acceptance gate, where "yes" selects shared nodes and "no" selects private nodes. Hardening reduces risk on an accepted shared-node deployment. It never turns a "private nodes" result from the three questions into "shared nodes."

What counts as narrowly scoped read-only visibility

This means an explicitly limited visibility surface, for example status and logs for the customer's own jobs or pods. It doesn't include:

• Creating, updating, patching, or deleting Kubernetes resources, Slurm jobs, or other scheduler-managed workloads
• exec, attach, or port-forward (or the equivalent job-shell access on other schedulers)
• Reading Secrets, service account tokens, or broad cluster or node metadata
• Writing custom resources
• Permissions that can indirectly cause workloads or host-side resources to be created

If a customer-facing offering needs any of these types of access, choose private nodes.

What each result requires

Result	Immediate requirements	Next step
Shared nodes	Existing Kubernetes worker capacity on the control plane cluster. Requires a CNI that enforces NetworkPolicy.	Shared Nodes quick start
Private nodes	vCluster Platform (free mode supported), plus dedicated Linux worker capacity per tenant cluster, joined manually or provisioned automatically through a node provider.	Private Nodes quick start

Service models

You might describe your product in these terms rather than the three questions above. Match it to the row that fits for the same guidance.

Service model	Typical customer capability	Worker-node guidance
Kubernetes-as-a-Service / Cluster-as-a-Service	Customer receives direct API access to the cluster or scheduler (Kubernetes, Slurm, or similar) and commonly administers workloads	Private nodes
Namespace-as-a-Service	Customer can usually create Pods, controllers, Services, and other resources within a namespace, or jobs within a Slurm partition or queue	Private nodes, with a separate tenant cluster per customer. A namespace or Slurm partition doesn't isolate customers from each other within one cluster. Private nodes dedicate compute to the tenant cluster itself, not to namespaces or partitions inside it.
Container-as-a-Service	Customer supplies an image, code, or job script, even if you hide the underlying cluster or scheduler from them	Private nodes, because the customer controls workload execution
SaaS / provider-operated application	Customer uses your application or API. You own the images and workload definitions	Shared nodes may be suitable when access is tightly limited and the platform is hardened
Trusted internal platform	Employees or teams may have direct cluster or scheduler write access and run arbitrary workloads under an accepted trust model	Shared nodes are supported with hardening. Use private nodes for stronger isolation, or where compliance or infrastructure isolation requires it.

Hybrids and edge cases

• A "SaaS" product that lets customers supply plugins, notebooks, images, models that execute code, or arbitrary jobs isn't provider-controlled for this decision. Treat it like Container-as-a-Service and use private nodes.
• A portal that creates Deployments, Slurm jobs, or other scheduled workloads on a customer's behalf still gives the customer workload authority, even if the customer never sees kubectl or a scheduler CLI directly. Use private nodes.
• Read-only diagnostic access doesn't make a product Kubernetes-as-a-Service or Slurm-as-a-Service by itself, as long as it's genuinely narrow and can't mutate or execute anything.
• What the product is named matters less than the effective permissions and workload authority it grants. Judge by the three questions, not by the marketing category.

Shared and private nodes as security boundaries

• Private nodes are the security boundary for tenants with cluster, scheduler, or workload execution access. See Private Nodes for the full architecture.
• 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. See Architecture for the full architecture.

A dedicated, labeled node pool selected from the control plane clusterControl plane clusterThe Kubernetes cluster that hosts the virtualized control planes for tenant clusters. The control plane cluster is operated by the platform provider and is completely invisible to tenants. There are no shared control plane nodes, no in-cluster agent pods, and no lateral path between tenant environments. With shared nodes, this cluster also runs tenant workloads alongside the control plane pods — the same node pool is used for both.Related: Tenant cluster, Control plane cluster, Tenant cluster is still the shared-node architecture. It scopes placement, not isolation, and it doesn't become private nodes.

	Private nodes	Shared nodes
Kernel and node isolation	Dedicated per tenant	Shared across tenants
CNI / CSI	Dedicated per tenant	Shared, tenant traffic isolated by policy
Suitable when the tenant controls cluster or scheduler access or workload execution	Yes	No
Suitable for trusted internal tenants	Yes	Yes, with hardening
Additional runtime isolation	Optional, recommended for privileged or untrusted workloads	vNode recommended for stronger per-tenant boundaries

Examples

• A managed Kubernetes service reselling clusters to external customers is delivering a Kubernetes environment to the customer. Use private nodes, regardless of how the accounts are billed or resold.
• An internal CI/CD platform that creates ephemeral clusters for your own engineering teams is a trusted internal tenant. Shared nodes are appropriate, hardened according to the shared node hardening guide.
• A SaaS inference API where customers call your endpoint and never see Kubernetes answers no to all three questions. Shared nodes may be suitable when hardened and using tightly scoped access.
• A self-service portal that lets external customers deploy their own container images through a form, even without kubectl, gives the customer workload authority. Use private nodes.

Trusted internal tenants are a separate model

The three-question tree above is for customer-facing and other untrusted-tenant production offerings. Trusted internal teams, such as development, testing, CI/CD, and internal platform tenants, are a separate threat model.

Treat a tenant as trusted only when all of the following hold:

• Every workload owner belongs to an organization you've explicitly accepted into a common trust domain, not an external account.
• You accept that tenant workloads share a kernel and worker nodes with each other, and that shared-kernel exposure is documented.
• No contract, regulation, or internal policy requires dedicated infrastructure for these workloads.
• You can enforce and verify the shared-node hardening baseline before onboarding, not just declare it in vcluster.yaml.

If any of these don't hold, use private nodes, even for a team you'd otherwise call internal.

Shared nodes remain supported when all four hold, with hardening applied and the architecture decision documented per the hardening guide's own checklist. Private nodes remain the right choice for internal tenants too, when compliance or infrastructure isolation requires it.

Shared nodes are for trusted tenants

Shared nodes are a supported, common model for trusted tenants. They give each tenant control-plane, API, and namespace isolation, but tenant workloads share the same kernel and physical nodes. They aren't a security boundary for untrusted tenants with Kubernetes access or arbitrary workload execution. Good fits are development, testing, CI/CD, and internal engineering teams.

Use private nodes for external, resale, regulated, or otherwise untrusted tenant offerings, optionally with vNode for runtime isolation.

NetworkPolicy is an added isolation layer worth enabling even for trusted tenants. vCluster can create the policies for you through policies.networkPolicy, and your control plane cluster's CNI enforces them. Confirm your CNI supports enforcement, since some accept NetworkPolicy resources without acting on them. See the security baseline.

If you accept shared nodes for a trusted-tenant use case, follow the shared-node hardening guide as the required next step.

The external-tenant line in the note above states the general default, not an override. The provider-operated SaaS exception from the three questions still holds. An external SaaS or inference-API offering where the customer has no cluster or scheduler access and can't run custom workloads can still use shared nodes.

Where this decision gets set

There's no separate toggle for this decision. privateNodes.enabled in vcluster.yaml is the actual switch, set at initial installation. Leave it unset or false for shared nodes, or set it true for private nodes. It can't change after creation without redeploying. See Private Nodes for the full configuration.

Next steps

• Answered "private nodes"? Continue to Private Nodes and Deploy vCluster. Private nodes need dedicated worker capacity per tenant. If that capacity isn't available yet, close the infrastructure gap or reconsider what you're offering customers, not fall back to shared nodes as a workaround.
• Answered "shared nodes may be suitable"? Continue to the Shared Nodes quick start or Nodes from the Control Plane Cluster to deploy, then apply the shared node hardening guide and document your acceptance of the shared-kernel exposure, per the guide's own checklist, before treating the decision as final.
• Match your answer to a concrete path in Build for Production.