What is a Kubernetes node?
A Kubernetes node is a virtual machine or physical server that runs Pods for the cluster. Each node runs three components: the kubelet, which starts and monitors containers, a container runtime such as containerd, and a network proxy that routes Service traffic. The control plane decides which Pods go to which node. The nodes do the actual work.
What runs on a node
| Component | What it does |
|---|---|
kubelet |
Registers the node, receives the Pods assigned to it, starts their containers through the runtime, runs health checks and reports status back to the API server. |
| Container runtime | Pulls images and runs containers. Kubernetes talks to it through the Container Runtime Interface (CRI). containerd and CRI-O are the common choices. |
kube-proxy |
Programs the node’s networking so that traffic to a Service reaches one of its Pods. Some network plugins, such as Cilium, replace it entirely with eBPF. |
Nodes also run a network plugin (CNI) that gives every Pod an IP address, plus cluster add-ons such as log and metrics agents, usually as DaemonSets with one Pod per node.
Node vs Pod
A node is a machine. A Pod is the smallest unit Kubernetes schedules: one or more containers that share a network address and storage. One node runs many Pods. Upstream Kubernetes is designed for no more than 110 Pods per node and 5,000 nodes per cluster. When a node fails, its Pods are not moved. Their controllers create new Pods on other nodes.
How a node joins a cluster
By default the kubelet registers itself with the API server and creates a Node object named after the machine. Two Nodes cannot have the same name at the same time. On registration the node gets labels that describe it, such as its architecture, operating system and, on a cloud, its instance type. Once the node reports Ready, the scheduler can place Pods on it.
Node health and heartbeats
A node proves it is alive in two ways: it updates the .status of its Node object, and it renews a Lease object in the kube-node-lease namespace. The node controller in the control plane checks every node every 5 seconds by default.
If a node stops reporting, the controller sets its Ready condition to Unknown and taints it so that the scheduler places no new Pods there. By default it then waits 5 minutes before it starts evicting the node’s Pods so that they can be recreated elsewhere. Containers on the unreachable node keep running in the meantime. For what this means at edge sites and during control plane outages, see what happens to workloads when the control plane connection drops.
Cordon and drain
Before maintenance, you take a node out of service in two steps:
kubectl cordon <node>marks the node unschedulable. New Pods stop landing there, and existing Pods keep running.kubectl drain --ignore-daemonsets <node>evicts the Pods so their controllers recreate them elsewhere. According to the drain documentation, evictions let containers terminate gracefully and respect your PodDisruptionBudgets.
After maintenance, kubectl uncordon <node> allows scheduling again. Node autoscalers and upgrade tooling run the same cordon and drain sequence automatically.
Node pools and auto-provisioned nodes
Clusters get their nodes in one of three ways:
| Model | How nodes are created | Who chooses the machine type |
|---|---|---|
| Static nodes | You install the kubelet on machines and join them | You |
| Node pools | A cluster autoscaler grows and shrinks predefined groups of identical machines | You, per pool |
| Node auto-provisioning | A provisioner creates a node that fits the pending Pods | The provisioner, within your constraints |
Node pools work well when workloads are uniform. Auto-provisioning removes the need to predict instance types for every workload. Both are explained in how Kubernetes autoscaling works.
Topology labels and nodes in different places
The well-known labels topology.kubernetes.io/region and topology.kubernetes.io/zone record where a node runs. On cloud infrastructure, the kubelet or the cloud controller manager sets them from provider data, and you can set them yourself elsewhere. The scheduler uses them to spread replicas across zones and to keep Pods in the same zone as their volumes.
Kubernetes does not require all nodes to sit in one data center or one cloud. A node needs a network path to the API server and to the other nodes’ Pod network. With a network layer that connects sites, one cluster can hold nodes from several providers and on-premises locations, labeled by region and zone. The design questions are covered in whether one cluster can span multiple clouds.
Kubelet version skew
The kubelet does not have to match the control plane version exactly. The version skew policy says the kubelet “must not be newer than kube-apiserver” and may be up to three minor versions older. That is why clusters upgrade the control plane first and nodes afterwards, and why nodes cannot fall too far behind.
Nodes on Cloudfleet
Cloudfleet Kubernetes Engine (CFKE) provisions nodes automatically in AWS, GCP and Hetzner Cloud accounts, and accepts self-managed Linux servers from other clouds, data centers and edge sites as nodes in the same cluster. See how Cloudfleet provisions nodes.