Skip to main content
Version: main 🚧

Cluster Attachment

When a cluster requests nodes, vMetal provisions servers and joins them to that cluster automatically. Each server appears in the cluster as a standard Kubernetes node. For the driver-neutral instance model behind this, see Instance and server concepts.

This page describes what happens when an instance joins a cluster as a worker. Two related cases are covered elsewhere. For instances requested without any cluster, see Independently provisioned instances. For instances that run a cluster's own control plane rather than joining one, see Control plane instances.

Private nodes​

When vMetal provisions capacity for a cluster, the resulting Kubernetes worker is a private node. The platform assigns that node exclusively to one cluster at a time. The infrastructure boundary depends on the driver: Metal3 can provide an entire physical server, while KubeVirt and Terraform can provide a VM whose physical host might run other VMs.

Private nodes appear in the cluster alongside any virtual nodes from vCluster. Schedule workloads to private nodes using standard Kubernetes node selectors and resource requests.

How joining works​

The platform generates cloud-init user data for each instance. For private nodes, cloud-init runs a bootstrap script downloaded from the vCluster server. The script installs the container runtime and kubelet, then runs kubeadm join with a dedicated join token for the target cluster. After the driver finishes creating or preparing the host, cloud-init runs the script automatically.

The server registers with the cluster's API server and begins accepting workloads. The join happens without manual intervention. This is a different, automated path from joining a manually provisioned node, which uses a CLI-issued join token and a script you run yourself.

Instance lifecycle and cluster lifecycle​

An instance exists for as long as the cluster needs that node. When scale-down removes a node or the cluster is deleted, the platform deletes the corresponding NodeClaim. This triggers deprovisioning through the driver. For example, the Metal3 driver cleans the server and returns it to the available pool.

If an instance fails, it isn't automatically replaced. Investigate the server's status conditions, resolve the issue, and return it to an available state before the platform can use it again. See Bare metal server lifecycle for the Metal3 driver's states.

Cluster requests nodeMachine claims BareMetalHostPXE boot and OS installNode joins tenant clusteron scale-down or cluster deleteMachine deletedBareMetalHost cleanedReturned to available pool

Node resources​

After joining, the server is a standard Kubernetes node. The resources it advertises depend on what software runs on it.

vMetal doesn't set GPU or accelerator resources. Device plugins running on the node advertise them to the kubelet. For GPU nodes, deploy the NVIDIA GPU Operator or an equivalent. vMetal provisions the server with the correct OS. The device plugin discovers the hardware and reports it to the scheduler.

To target GPU nodes, use standard Kubernetes resource requests:

resources:
limits:
nvidia.com/gpu: "1"

Node profiles​

A NodeProfile is reusable node configuration that the platform applies when a server joins a cluster. Profiles are cluster-scoped and shared, so one profile can serve many clusters and many projects. The same profile applies whether the node arrives through an instance, through Auto Nodes, or through a manual join.

A profile sets taints, startup taints, node labels, and node annotations on the joined node. Everything it sets is a Kubernetes node property, so profiles do nothing for independently provisioned instances, which never become Kubernetes nodes. Use node type properties for anything those instances need at provision time.

The platform resolves which profile a node gets in this order, taking the first one it finds:

  1. An explicit spec.profileRef on the instance, which is per-node selection.
  2. The cluster's own privateNodes.defaultProfile value.
  3. The project's spec.defaultNodeProfile.

If none of the three is set, the node joins with no profile. The platform records which profile configured a node by labeling it vcluster.com/node-profile with the profile name. A node joined without a profile carries no such label, so that label is also how you tell the two apart after the fact.

For what a profile configures and how to create one, see Node profiles. For restricting which profiles a project may use, see Manage allowed node profiles.

Configure private nodes​

Private nodes are configured on the cluster, not on the NodeProvider. See Cluster nodes for the configuration and the task around it.