Kubernetes Controller Leader Election Debug Prompt
Debug operators and controllers that flap leadership, run as split-brain, or stall after a leader loses its lease — covering lease durations, clock skew, and apiserver throttling.
- Target user
- platform engineers and operator developers running controllers in production
- Difficulty
- Advanced
- Tools
- Claude, ChatGPT
The prompt
You are a senior Kubernetes engineer who has debugged leader-election failures in controller-runtime and client-go controllers, and you understand Lease objects, renewal deadlines, and what happens when an apiserver round-trip is slow. I will provide: - The controller's leader-election config (leaseDuration, renewDeadline, retryPeriod, resourceLock type) - Symptoms (frequent leader changes, two replicas acting at once, controller idle but pods healthy) - Logs around `failed to renew lease` / `successfully acquired lease` and the Lease object's `kubectl get lease -o yaml` Your job: 1. **Confirm the lock backend** — identify whether it uses `leases`, `endpoints`, or `configmaps` resource lock; recommend `leases` and explain why the older endpoint/configmap locks are deprecated and noisier. 2. **Validate the timing triad** — check the invariant `leaseDuration > renewDeadline > retryPeriod`, and explain how a renewDeadline shorter than typical apiserver latency causes constant lease loss. 3. **Diagnose flapping** — correlate `failed to renew lease` with apiserver latency, client-go QPS throttling, network blips, or CPU starvation of the controller pod that delays renewal goroutines. 4. **Rule out split-brain** — explain that controller-runtime stops the manager (and should exit) on lost leadership; if two replicas reconcile simultaneously, check `--leader-elect=true` is actually set and the lease `holderIdentity` is changing rapidly. 5. **Inspect the Lease object** — read `holderIdentity`, `renewTime`, `leaseDurationSeconds`, and `leaderTransitions` to reconstruct the timeline. 6. **Recommend fixes** — propose tuned durations for the cluster's latency, adequate CPU requests for the controller, and `--leader-elect-resource-lock=leases`; note when to widen leaseDuration for high-latency clusters. Output as: a root-cause statement, the corrected leader-election parameters, and a timeline reconstructed from the Lease and logs. Never widen leaseDuration so far that a genuinely dead leader holds the lease for minutes — that delays failover and reconciliation.
Run this prompt with AI
Test it, get an AI-improved version, or compare models — live in the Prompt Workspace. No copy-paste.
Related prompts
-
Kubernetes Operator Reconcile Loop Debug Prompt
Debug operator reconciliation issues — finalizers stuck, status not updating, requeue storms, owner references, leader election.
-
Kubernetes CRD Conversion Webhook Design Prompt
Design a CRD conversion webhook to migrate stored objects across API versions safely, choosing a hub version and avoiding lossy round-trips and storage-version traps.
-
Kubernetes OOMKilled Memory Limit Diagnosis Prompt
Diagnose why containers are OOMKilled — distinguish container limit kills from node-level memory pressure, working-set growth, and JVM/heap-vs-RSS gaps, then right-size limits.
-
Helm Release Rollback & Stuck Release Debug Prompt
Recover from a Helm release stuck in `pending-install` / `pending-upgrade` / `failed`, roll back safely, and avoid Helm-secret bloat that breaks future operations.
More Kubernetes & Helm prompts & error guides
Browse every Kubernetes & Helm prompt and troubleshooting guide in one place.
Reading prompts? Get all 500 in one free PDF
500 battle-tested, copy-paste AI prompts engineered by a senior systems engineer — every one with fill-in placeholders and safety/back-out notes. Drop your email and it's yours.
- 500 prompts: Linux · Kubernetes · Terraform · OpenStack · GitLab · Docker · Monitoring · Incident Response
- Instant PDF download — yours free, forever
- Plus one practical AI-workflow email a week (no spam)
Single opt-in · unsubscribe anytime · no spam.