How to fix StatefulSet partition in Kubernetes

KubernetesADVANCEDMEDIUMUpdated Dec 6, 2025· 128 views

StatefulSet partition controls phased rolling updates by specifying which pod ordinals receive new versions. Misconfigured partitions can prevent updates from propagating or leave StatefulSets stuck in non-ready states. Fix by correctly configuring the updateStrategy.rollingUpdate.partition value relative to replicas.

Quick fix

Fixes StatefulSet partition

kubectl get statefulset <name> -o jsonpath='{.spec.updateStrategy.rollingUpdate.partition}'
# Should return a number or null (0)

kubectl get statefulset <name> -o yaml | grep -A 5 updateStrategy

kubectl get pods -l app=<app-label> --sort-by=.metadata.name
  1. Verify current StatefulSet partition configuration
  2. Understand partition semantics
  3. Reset partition to allow all updates
  4. For staged rollout, use partition correctly
kubernetes — error
kubectl get statefulset <name> -o jsonpath='{.spec.updateStrategy.rollingUpdate.partition}'
# Should return a number or null (0)
kubectl get statefulset <name> -o yaml | grep -A 5 updateStrategy
kubectl get pods -l app=<app-label> --sort-by=.metadata.name
StatefulSet partition

What this error means

StatefulSets support partitioned rolling updates via the .spec.updateStrategy.rollingUpdate.partition field. This allows staged deployments: pods with ordinals >= partition receive new template versions, while pods with ordinals < partition retain the old version. This is useful for canary deployments and phased rollouts. Issues occur when the partition value is misconfigured relative to the number of replicas, preventing updates or blocking pod readiness.

Typical symptoms

  • StatefulSet pods not updating despite template changes
  • StatefulSet stuck in "not ready" state after partition changes
  • Pods with lower ordinals keeping old configuration while others update
  • kubectl describe statefulset shows incorrect partition values (pointer instead of value)
  • Rolling update fails to complete when partition is adjusted
  • Some pods never become ready in OrderedReady pod management policy
  • Canary deployment not working as expected with partition strategy

Common causes

  1. Partition value >= replicas, preventing any pod updates
  2. Partition changed mid-deployment, causing inconsistent pod states
  3. Pod template configured to never become Ready (bad binary or config)
  4. Kubernetes version with partition bug (pre-1.28 had various partition issues)
  5. Misunderstanding partition semantics (thinking >= means "exclude" instead of "include")
  6. Network partition or control plane issues during partition updates
  7. OrderedReady policy waiting for lower-ordinal pods that are stuck

How to fix "StatefulSet partition"

1Verify current StatefulSet partition configuration

Check the StatefulSet spec and current pod states:

bash
kubectl get statefulset <name> -o jsonpath='{.spec.updateStrategy.rollingUpdate.partition}'
# Should return a number or null (0)

kubectl get statefulset <name> -o yaml | grep -A 5 updateStrategy

kubectl get pods -l app=<app-label> --sort-by=.metadata.name

Note the current partition value and number of replicas.

2Understand partition semantics

StatefulSet partition works as follows:

bash
replicas: 3 (pods: app-0, app-1, app-2)
partition: 2

Result:
- Pods app-2 (ordinal >= 2): Get NEW template
- Pods app-0, app-1 (ordinal < 2): Keep OLD template

If partition is greater than or equal to replicas, NO pods receive updates:

bash
replicas: 3
partition: 3  # BUG - no pods update
partition: 5  # BUG - no pods update
3Reset partition to allow all updates

If StatefulSet is stuck, reset partition to 0 (all pods get updated):

bash
kubectl patch statefulset <name> -p '{"spec":{"updateStrategy":{"type":"RollingUpdate","rollingUpdate":{"partition":0}}}}'

# Verify patch applied
kubectl get statefulset <name> -o jsonpath='{.spec.updateStrategy.rollingUpdate.partition}'

This forces the rolling update to proceed for all pods.

4For staged rollout, use partition correctly

To update only pods with ordinal >= N:

bash
# Test update on pod-2 only (3 replicas, partition=2)
kubectl patch statefulset web -p '{"spec":{"updateStrategy":{"type":"RollingUpdate","rollingUpdate":{"partition":2}}}}'

# Update pod template
kubectl set image statefulset/web web=myapp:v2

# Monitor pod-2 update
kubectl rollout status statefulset/web

# Once pod-2 is healthy, allow pod-1
kubectl patch statefulset web -p '{"spec":{"updateStrategy":{"type":"RollingUpdate","rollingUpdate":{"partition":1}}}}'

# Finally, allow pod-0
kubectl patch statefulset web -p '{"spec":{"updateStrategy":{"type":"RollingUpdate","rollingUpdate":{"partition":0}}}}'
5Debug stuck pods with OrderedReady policy

If pods are stuck despite partition reset, check pod readiness:

bash
# Check why pods aren't ready
kubectl describe pod <name-0>
# Look for: conditions, events, and recent restarts

kubectl logs <name-0> --previous  # If pod was killed

kubectl get pod <name-0> -o yaml | grep -A 10 conditions

OrderedReady waits for pod N before updating pod N+1. If pod-0 never becomes Ready, pod-1 and pod-2 won't update. Fix the pod template (bad binary, missing config, resource limits, etc.) first.

6Verify partition changes propagate

Monitor partition update progress:

bash
# Watch partition field and pod updates
kubectl get statefulset <name> -w

# Check individual pod templates
kubectl get pod <name-2> -o jsonpath='{.spec.containers[0].image}'

# For kubectl describe displaying incorrect partition (pre-1.27 bug)
kubectl describe statefulset <name> | grep Partition
# Ignore if it shows a large number; check with jsonpath instead
7Upgrade Kubernetes if experiencing partition bugs

Several partition-related bugs were fixed in recent Kubernetes versions:

- v1.28+: Improved partition status reporting in rollout progress
- v1.27: Fixed kubectl describe showing pointer instead of partition value
- v1.26+: More reliable partition state transitions

If running older versions:

bash
kubectl version --short  # Check your version

# Consider upgrading via kubeadm or cloud provider tools

Check your cluster's upgrade path and plan the upgrade.

Advanced notes

Partition enables canary deployments and staged rollouts without templating tools. For complex rollout strategies, consider using tools like Flagger, Argo Rollouts, or cloud provider features (GKE Autopilot rollout policies). Note: partition works with RollingUpdate strategy only (not OnDelete). When partition equals or exceeds replicas, updates don't propagate—a common mistake. OrderedReady policy makes partition debugging harder since pod N-1 must be Ready before pod N updates. For stateless workloads or rapid iteration, consider Deployment instead of StatefulSet.

Frequently asked questions

What does "StatefulSet partition" mean?
partition field. This allows staged deployments: pods with ordinals >= partition receive new template versions, while pods with ordinals < partition retain the old version. This is useful for canary deployments and phased rollouts.
How do I fix "StatefulSet partition"?
StatefulSet partition controls phased rolling updates by specifying which pod ordinals receive new versions. Misconfigured partitions can prevent updates from propagating or leave StatefulSets stuck in non-ready states. Fix by correctly configuring the updateStrategy.rollingUpdate.partition value relative to replicas.
What causes "StatefulSet partition"?
Partition value >= replicas, preventing any pod updates Partition changed mid-deployment, causing inconsistent pod states Pod template configured to never become Ready (bad binary or config)
Is the "StatefulSet partition" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading