Kubernetes DaemonSet Controller

Kubernetes DaemonSet Controller is the control loop that ensures exactly one copy of a specified Pod runs on every node matching a given criteria, rather than maintaining an arbitrary replica count as a ReplicaSet does. Its defining characteristic is that its unit of scaling is the node, not a number: adding a node to the cluster automatically triggers creation of the DaemonSet's Pod there, and removing a node removes its corresponding Pod, with no replicas field involved at all.

Node-Bound Scheduling

One Pod Per Matching Node

Rather than being scheduled independently by the standard scheduler's scoring logic, a DaemonSet Pod is tied directly to a specific node through node affinity generated automatically by the controller, ensuring precisely one instance lands on each node that satisfies the DaemonSet's node selection criteria.

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: daemonset-controller-example
spec:
  selector:
    matchLabels:
      app: node-agent
  template:
    metadata:
      labels:
        app: node-agent
    spec:
      containers:
        - name: agent
          image: registry.example.com/node-agent:1.0.0

Restricting to a Node Subset

nodeSelector or affinity.nodeAffinity in the Pod template limits the DaemonSet to a subset of nodes, common for workloads that only need to run on nodes with specific hardware, such as GPU-equipped machines, rather than the entire cluster.

spec:
  template:
    spec:
      nodeSelector:
        accelerator: gpu

Reacting to Cluster Topology Changes

New Node Joins

When a new node joins the cluster and satisfies the DaemonSet's selection criteria, the controller creates a Pod for it automatically, without any change to the DaemonSet object itself triggering the action; the node addition alone is sufficient.

Node Removal or Cordoning

When a node is removed from the cluster, its DaemonSet Pod is garbage collected along with it. A cordoned node (marked unschedulable) does not lose its existing DaemonSet Pod, since cordoning only prevents new Pods from being scheduled, not the removal of ones already running.

kubectl get daemonset daemonset-controller-example -o jsonpath='{.status.numberReady}/{.status.desiredNumberScheduled}'

Tolerating Control Plane Taints

Reaching Nodes Other Controllers Cannot

DaemonSets commonly include tolerations for taints that would otherwise exclude normal workloads, such as the taints applied to control plane nodes, since infrastructure agents (log collectors, network plugins, monitoring exporters) frequently need to run on every node regardless of its role.

spec:
  template:
    spec:
      tolerations:
        - key: node-role.kubernetes.io/control-plane
          operator: Exists
          effect: NoSchedule

Update Strategy

RollingUpdate Per Node

The default RollingUpdate strategy replaces the Pod on each node one at a time (or in small batches bounded by maxUnavailable), ensuring the infrastructure-level function the DaemonSet provides is not simultaneously unavailable across too many nodes during an update.

spec:
  updateStrategy:
    type: RollingUpdate
    rollingUpdate:
      maxUnavailable: 1

OnDelete as a Manual Alternative

OnDelete disables automatic propagation, requiring an operator to delete each node's Pod manually to trigger its replacement with the new template, giving precise control over update timing per node.

DaemonSet Controller Diagram

This one-to-one relationship between matching nodes and Pods is what makes DaemonSets the correct abstraction for cluster-wide infrastructure concerns, node monitoring, log aggregation, network plugins, that must have a physical presence on every relevant machine rather than being satisfied by any arbitrary count of instances.