Debian 11: kubelet not starting due to cgroup driver mismatch

📖 ~1 min read

Table of contents

1. Symptom & Impact
2. Environment & Reproduction
3. Root Cause Analysis
4. Quick Triage
5. Step-by-Step Diagnosis
6. Solution – Primary Fix
7. Solution – Alternative Approaches
8. Verification & Acceptance Criteria
9. Rollback Plan
10. Prevention & Hardening
11. Related Errors & Cross-Refs
12. References & Further Reading

Symptom & Impact

Kubelet fails to run because its cgroup driver does not match the container runtime setting.

Environment & Reproduction

Node remains NotReady and kubelet logs include cgroup driver mismatch warnings.

Root Cause Analysis

Compare kubelet config under `/var/lib/kubelet/config.yaml` with runtime config and `journalctl -u kubelet -b`.

Quick Triage

Configuration drift after upgrades or bootstrap scripts set different cgroup drivers.

Step-by-Step Diagnosis

Set matching cgroup driver values for kubelet and runtime, reload systemd, and restart services.

Solution – Primary Fix

Confirm kubelet is active and node reports Ready state in cluster status checks.

Solution – Alternative Approaches

Template both runtime and kubelet configs from a single source in cluster automation.

Verification & Acceptance Criteria

Return to previously known-good node config and rejoin the node if needed.

Rollback Plan

Run conformance checks after upgrades to detect driver mismatch before workloads are scheduled.

Prevention & Hardening

`journalctl -u kubelet -b`; `systemctl status kubelet`; `sudo cat /var/lib/kubelet/config.yaml`

Related Errors & Cross-Refs

Attach kubelet config, runtime config, and node bootstrap logs for cluster operations review.

Related tutorial: View the step-by-step tutorial for debian-11.

View all debian-11 tutorials on the Tutorials Hub →

Browse all common problems & solutions on the Tutorials Hub.

References & Further Reading

Control plane upgrades should include worker node configuration validation as a release gate.