Cluster nodes
A cluster can take dedicated bare metal capacity. You declare how many nodes you want and which hardware they come from, and the platform provisions servers and joins them to the cluster as worker nodes. There's no manual kubeadm join and no agent to install.
These are private nodes. The platform allocates each server to one cluster at a time, so no other tenant shares the hardware. For how the join works underneath, see Cluster attachment.
Before you begin​
This guide uses the Metal3 driver. For NVIDIA Infra Controller (NICo) capacity, follow Supply cluster nodes with Auto Nodes instead.
Work through the Metal3 get started walkthrough steps 1 through 4 first, so you have a NodeProvider and at least one BareMetalHost in available state. Step 5 there is a branch point that routes to one of three guides. This is the one for servers that join a cluster as workers, and it picks up where step 4 ends.
The cluster's own configuration and its NodeClaim commands run against the management cluster. Commands that inspect, cordon, or drain Kubernetes nodes run against the cluster itself. Keep a separate management-cluster shell open after connecting to the cluster.
You also need a cluster to attach the nodes to. If its control plane should also run on vMetal hardware rather than on an existing Kubernetes cluster, set that up first. See Control plane instances, since that choice can't be changed later.
1. Define a node type for worker capacity​
Node types are defined on the NodeProvider. Add one describing the hardware you want clusters to draw from.
nodeTypes:
- name: "compute-node"
displayName: "Compute Node"
resources:
cpu: "32"
memory: 128Gi
machines:
selector:
matchLabels:
role: compute
properties:
vcluster.com/os-image: ubuntu-noble
vcluster.com/ssh-keys: ops-key-x7k2p
Include vcluster.com/ssh-keys even though these nodes are reachable through Kubernetes. Keys are injected at provision time and can't be added afterwards, and SSH is how you inspect a node whose kubelet never came up. See Define node types for the full set of node type fields.
2. Request nodes from the cluster​
Set privateNodes in the cluster's configuration. This is the canonical form. Other pages that show this block are showing a variation on it.
privateNodes.autoNodes is deprecatedprivateNodes.autoNodes is deprecated in vCluster v0.38. It still works, and no removal date is set. For new clusters, request nodes with node pools instead.
privateNodes:
enabled: true
autoNodes:
- provider: metal3-provider
static:
- name: compute-nodes
quantity: 3
nodeTypeSelector:
- property: vcluster.com/node-type
value: metal3-provider.compute-node
provideris the NodeProvider to claim servers from.staticis a list of named pools. Each pool holds a fixed node count, which is what makes it static.quantityis how many nodes that pool should have. The platform creates and deletes instances to match it.nodeTypeSelectormatches the node type by property.vcluster.com/node-typecarries the node type's fully qualified name, which the platform generates as<provider>.<node type>. A bare node type name still matches today, but the platform is migrating to the qualified form, and that's what the API and the platform UI show you. List them withkubectl --context <management-context> get nodetypes.
The platform creates one instance per requested node, each claiming an eligible server. Instances wait for the cluster to be online before they provision, because a node needs a live API server to join. For every field this block accepts, see the Auto Nodes configuration reference.
Use servers assigned to your tenant​
When the cluster belongs to a tenant, its instances draw only from servers the node type's machine allocation policy allows:
Assigned: only servers owned by or exclusively assigned to your tenant. This is the default for Metal3 and NICo.OnDemand: only unassigned servers, which no tenant owns or holds. Your tenant's reserved servers aren't used.
Neither policy ever places your instances on another tenant's server. You choose servers through the node type, as in the example above. A node type's machines.selector decides which servers it covers, but users in a tenant don't see the selector, so ask an operator which node type covers your assigned hardware. A platform admin assigns servers to a tenant as described in Assign dedicated resources. Server pinning narrows a pool to one named server, but only among the servers the node type and its policy already allow.
To confirm where an instance landed, read the BareMetalHost it claimed. The matching Machine is named <provider>.<host>.
kubectl --context <management-context> get nodeclaims -n loft-p-my-project \
-o custom-columns='NAME:.metadata.name,HOST:.metadata.annotations.machines\.vcluster\.com/machine-id'
An instance that finds no eligible server waits with reason InsufficientCapacity. Check whether the Scheduled or Provisioned condition reports the wait.
- A capacity wait during scheduling retries without a time limit. The platform checks your tenant's free reserved capacity before selecting an
Assignednode type. - A capacity wait during provisioning fails after 30 minutes by default. Under
OnDemand, free reserved servers remain unused. The message names the Machine pool setting and suggests Reserved hosts only when reserved servers are free.
For an Assigned request, free a reserved server or ask an operator to assign another. For an OnDemand request, free an unassigned server or use an Assigned node type to consume reserved capacity. See Instance stays pending without a server.
3. Verify the nodes joined​
# Run from a management-cluster shell; this opens a tenant-cluster context.
vcluster connect my-cluster
kubectl get nodes
Each provisioned server appears as a standard Kubernetes node. Watch the instances from the platform side at the same time:
kubectl --context <management-context> get nodeclaims \
-n loft-p-my-project
An instance reaching Available with its Joined condition true means the server registered with the cluster. If an instance provisions but never joins, the server booted but the bootstrap script didn't complete. Follow Worker instance is provisioned but not joined.
4. Change how many nodes you have​
Edit quantity and apply. The platform adds instances to reach a higher count and deletes them to reach a lower one.
Scale-down drains before it destroys. When the platform deletes an instance for a joined worker, it deletes the corresponding cluster Node first. Karpenter owns a termination finalizer on that Node, so deleting it cordons the node, evicts its pods, and waits. The platform polls until the drain finishes, then destroys the server.
The platform skips the drain and destroys immediately in these cases:
- You set the
vcluster.com/skip-node-drainannotation on theNodeClaim, which is what Force delete in the platform UI does. - The instance is a control plane instance. Those aren't drained this way.
- The instance never joined a cluster, so there's no Node to drain. This covers independently provisioned instances.
- The drain has run for 30 minutes without finishing. That backstop exists so a stuck or absent Karpenter can't block teardown forever.
The 30-minute limit is a hard stop, not a target. A node pool configured with terminationGracePeriod: Never, or a pod that refuses to evict, outlasts it and has its server destroyed mid-drain.
For workloads that can't tolerate that, drain the node yourself and confirm the workloads rescheduled before you scale down.
# Cluster context
kubectl cordon <node-name>
kubectl drain <node-name> --ignore-daemonsets --delete-emptydir-data
To keep node counts tracking demand instead of managing quantity by hand, use Auto Nodes, which adds and removes nodes against configurable resource requirements. For the manual node operations available on a running cluster, see Manage private nodes.
5. Release the nodes​
Set quantity to zero, remove the pool, or delete the cluster. Each removes the instances it owns.
The driver then cleans each server and returns it to the available pool. A later instance can claim it, including one belonging to a different project or cluster. Deleting an instance never deletes the BareMetalHost. For what the server itself does during cleanup, see Server lifecycle.
Releasing nodes is a scale-down to zero, so the same drain behavior and the same 30-minute backstop apply.
Related tasks​
| If you want to | Go to |
|---|---|
| Understand how the join works and what the platform generates | Cluster attachment |
| Apply reusable taints and labels to joined nodes | Node profiles |
| Attach GPU servers instead of general compute | GPU quickstart |
| Pin a node to one specific physical server | Server pinning |
| Restrict which node types a project may claim | Manage allowed node types |
| Inspect a node's underlying server | Check fleet capacity |