A Node is a cluster-scoped v1 object that stands for one machine. You rarely write it : the kubelet creates its own Node when it starts, then keeps its status fresh.
On the machine : the kubelet, a container runtime and kube-proxy (see Architecture).
The name is unique in the cluster. Delete a rebuilt machine's old Node before it joins again.
The object is a record, not the machine : deleting it stops nothing.
The kubelet signs in as system:node:<name>, group system:nodes. Ready stays False until the runtime answers and the network plugin is up.
Cloud : the cloud-controller-manager adds providerID, zone, region and instance type, and deletes the Node once the instance is gone. Karpenter and Cluster API make nodes on demand.
2.What the object holds
Field
Holds
spec.podCIDR
this node's Pod address range, if the cluster gives one per node
Stock kubelet : allocatable memory is capacity minus 100Mi, CPU is all of it. Managed services reserve more.
The scheduler adds up requests against allocatable, never usage.
pods is 110 by default (maxPods). Cloud CNIs often change it.
4.Labels and roles
Label
Set by
kubernetes.io/hostname, /os, /arch
kubelet
topology.kubernetes.io/zone, /region
cloud, or you
node.kubernetes.io/instance-type
cloud
node-role.kubernetes.io/<role>
kubeadm, or you
Old guides say node-role.kubernetes.io/master : it is control-plane now.
ROLES is only labels
The column lists the <role> part of each node-role label, or <none>. The value is ignored.
kubeadm sets control-plane. Any other is yours : kubectl label node n3 node-role.kubernetes.io/worker=
A kubelet cannot give itself a role : NodeRestriction forbids it.
5.Reading kubectl describe node
Part, in print order
What to read there
Roles, Labels, Taints, Unschedulable
which Pods may land here, and whether it is cordoned
Lease, Conditions
is it alive : each condition has a reason and a message. A healthy Ready : kubelet is posting ready status
Addresses, Capacity, Allocatable, System Info
where it is, how big, which kernel, runtime and kubelet
Non-terminated Pods, Allocated resources
every Pod here, then the sum of their requests and limits. Not usage : a node can be 95% allocated and idle (for usage, kubectl top node needs metrics-server)
Events
recent history, such as RegisteredNode and NodeReady
In short : A Node is the kubelet's own record of its machine. Pods are scheduled against allocatable, which is capacity minus reservations and the eviction threshold.
1.Two heartbeats
Heartbeat
How often
Lease renewTime
every 10s
Node status
on a change, else every 5 min
One Lease per node in kube-node-lease, so a healthy node need not rewrite a large status every 10s.
No change for 50s (40s before v1.32) : the node lifecycle controller calls the node late.
2.NotReady means two things
Ready False
Ready Unknown
Written by
the kubelet
the controller
Means
here, but cannot run Pods (runtime down, no CNI)
nobody has heard from the kubelet
Taint
not-ready
unreachable
get nodes
NotReady
NotReady
Other conditions : MemoryPressure, DiskPressure, PIDPressure, NetworkUnavailable. Reason and message : describe node.
3.A node dies : the timeline
No controller setting moves the Pods. The 300s is tolerationSeconds: 300, added at admission to each Pod without its own. It starts when the taint lands.
The containers may still run on the lost machine. Kubelet back : Ready turns True, both taints go by themselves, deleted Pods' containers are killed.
Faster failover : give the Pods their own unreachable and not-ready tolerations with a smaller tolerationSeconds. Lab, with 20s : deleted 73s after the last heartbeat.
replaced at once : a Pod marked for deletion no longer counts
stuck Terminating, not replaced : its name is still taken
never evicted : it tolerates both taints with no time limit
4.The node protects itself
Node-pressure eviction : past a threshold the kubelet sets a condition, the controller adds a NoSchedule taint, and the kubelet evicts Pods. At once, no PodDisruptionBudget asked.
Memory : Pods using more than they requested go first, then by priority. No QoS class is safe, only critical Pods are spared.
The evicted Pod stays listed : phase Failed, reason Evicted, STATUS often Error.
Signal
Evict under
Condition
memory.available
100Mi
MemoryPressure
nodefs.available
10%
DiskPressure
nodefs.inodesFree
5%
imagefs.available
15%
imagefs.inodesFree
5%
pid.available
no default
PIDPressure
Hard defaults on Linux. Setting one key in evictionHard drops the others. The condition stays True 5 min after the pressure ends.
API eviction (drain)
Taint eviction
Node-pressure
OOM kill
Who
you, through the API server
taint-eviction controller
kubelet
Linux kernel
Budgets (PDB)
honoured
ignored
ignored
not involved
Pod afterwards
deleted
dead node : Terminating till it returns
Failed, Evicted, stays listed
same Pod, container restarted
5.Shutdown
Graceful node shutdown is on and still does nothing : shutdownGracePeriod and shutdownGracePeriodCriticalPods are both 0. Set them (say 30s and 10s) and the kubelet holds the systemd shutdown to stop ordinary Pods, then critical ones.
Power lost : the out-of-service taintkubectl taint nodes n3 node.kubernetes.io/out-of-service=nodeshutdown:NoExecute gets its Pods deleted, stuck and DaemonSet ones too, and volumes detached at once. Only when the node is really off : if not, old containers run beside the new. Remove the taint yourself.
In short : A node is alive while its Lease is renewed. After 50s of silence it is tainted, and each Pod's own 300s toleration decides when it is deleted. Deployments replace, StatefulSet Pods wait.
1.Cordon, drain, uncordon
cordon sets spec.unschedulable. Running Pods stay, DaemonSet Pods still land.
drain cordons, then evicts each Pod through the Eviction API, which asks its PodDisruptionBudget. A refusal is retried every 5s, for ever unless --timeout is set.
uncordon clears the flag, no Pod moves back. Drain never stops the kubelet or deletes the Node.
2.What drain refuses
Pod on the node
drain says
Flag, and what it costs
DaemonSet Pod
cannot delete DaemonSet-managed Pods
--ignore-daemonsets : leaves them running
uses an emptyDir
cannot delete Pods with local storage
--delete-emptydir-data : that data is lost
no controller
cannot delete Pods that declare no controller
--force : the Pod is gone for good
budget would break
Cannot evict pod as it would violate the pod's disruption budget.
fix the budget or add replicas (--disable-eviction ignores budgets)
The first three stop the drain before anything is evicted. One replica with minAvailable: 1 blocks it for ever.
Drain, kubectl delete node, then kubeadm reset on the machine.
delete node removes only the object. Its Pods go about a minute later, no budget asked.
A running kubelet does not register again. After a restart it is back in seconds, without hand-added labels, taints or the cordon.
5.Version skew and upgrades
A kubelet may be up to three minors older than the API server, never newer. Control plane first.
Then node by node : new kubeadm, kubeadm upgrade node, drain, new kubelet and restart, uncordon.
What a kubelet may do
Only its own Node and Pods : NodeRestriction and the Node authorizer see to it. But get on nodes/proxy reaches the kubelet API, exec included : treat it as admin (RBAC).
A Pod with the host root at /host. Delete it after
In short : Cordon blocks new Pods, drain evicts through budgets, and deleting the Node removes only the record. Upgrade the control plane first, then one drained node at a time.