KubeDeploymentGenerationMismatch

You changed a Deployment, but the deployment controller has not acknowledged the change, so nothing is rolling out.


Severity	warning
Source	kube-state-metrics v2.x
Key metrics	`kube_deployment_metadata_generation`, `kube_deployment_status_observed_generation`

What it means

Every write to a Deployment’s spec bumps metadata.generation. When the deployment controller in kube-controller-manager processes that version, it copies the number into status.observedGeneration. The alert fires when the two have disagreed for several minutes.

That gap is almost never a problem with the Deployment itself. It means the controller is not doing its job: new images, replica changes and rollbacks are all silently ignored. If more than one Deployment is affected, treat it as a control plane issue.

Common causes

kube-controller-manager down or crash looping, or no instance holds the leader lease.
API server overloaded: the controller’s requests are throttled or time out, so its work queue backs up.
etcd latency making status writes slow or failing.
A burst of changes (a mass redeploy by GitOps tooling) that the controller is still working through.

First checks

Confirm the gap on the object itself:

kubectl -n <namespace> get deploy <deployment> \
  -o jsonpath='{.metadata.generation} {.status.observedGeneration}{"\n"}'

Check how widespread it is. If many Deployments and StatefulSets show it, go straight to the controller.

Is the controller manager running, and who is leader?

kubectl -n kube-system get pods -l component=kube-controller-manager
kubectl -n kube-system get lease kube-controller-manager -o jsonpath='{.spec.holderIdentity}{"\n"}'

Look at its work queue and logs (self-managed clusters):

workqueue_depth{name="deployment"}

kubectl -n kube-system logs <controller-manager-pod> | grep -iE "deployment|throttl|error" | tail -50

On managed clusters (EKS, GKE, AKS) you cannot see the controller manager. Check the provider’s status page and control plane logs.

Fixing it

Restore kube-controller-manager: fix its static pod manifest or certificates, or restart it. If the API server or etcd is struggling, fix that first, since the controller recovers on its own once requests succeed. A burst of changes clears by itself; confirm workqueue_depth is falling.

KubeStatefulSetGenerationMismatch: the same symptom for StatefulSets, usually with the same cause.
KubeDeploymentRolloutStuck: the controller saw the change but the rollout cannot progress.
KubeControllerManagerDown: the most common root cause.