Last reviewed: November 8, 2026 (UTC); official Kubernetes references checked November 8, 2026.

Direct answer

Review a Kubernetes StatefulSet patch as a change to identity, ordering, and storage at the same time. Render the StatefulSet with its governing headless Service and volume claim templates, then verify the ordinal-to-Pod and ordinal-to-volume mapping before considering the update strategy. Exercise a healthy update, an intentionally unready Pod, a partitioned rollout when one is proposed, and a scale or deletion case that could affect claims. Keep StatefulSet controller observations separate from application replication and storage durability evidence.

The StatefulSets reference defines sticky Pod identity, Pod management policies, rolling updates, partitions, unavailable-Pod limits, revision history, and persistent-volume-claim retention. The StatefulSet basics tutorial demonstrates the headless-Service and volume-claim pattern. The Persistent Volumes reference explains how claims bind to provisioned or pre-created volumes. Together they describe the controller contract; they do not prove that a particular database, queue, or storage backend is safe for a proposed change.

Who this is for

Use this workflow when a coding agent edits an apps/v1 StatefulSet, its Pod template, serviceName, podManagementPolicy, updateStrategy, volumeClaimTemplates, replica count, or the Helm and Kustomize values that render those fields. It is intended for stateful workloads whose Pods are distinguishable and may have durable per-ordinal data. A stateless Deployment, a storage operator, and a database’s own replication protocol require separate review.

Give the agent the supported Kubernetes version, the identity and storage contract, the minimum serving or quorum requirement, the headless Service name, and the approved recovery procedure. Ask it to render every environment and identify which ordinals, claims, and controller revisions can change. The examples below are review fixtures and proposed acceptance checks; no authenticated cluster test or deployment was performed for this article.

Key takeaways

  • Treat the ordinal, stable network name, and persistent-volume claim as one identity contract.
  • Check the governing headless Service and selectors before inspecting rollout settings.
  • OrderedReady is the default Pod management policy; Parallel preserves identity while relaxing creation and termination ordering.
  • A rolling update proceeds from the largest ordinal toward the smallest and waits for the updated Pod to be Running and Ready; minReadySeconds adds another wait.
  • A partition stages only ordinals at or above its value, while an unavailable-Pod limit changes how much of an update can proceed together.
  • Test PVC binding, retention, scaling down, deletion, and recovery separately from Pod readiness.
  • A reverted template may still require deleting Pods that were created with a broken revision; controller status alone is not an application recovery result.

Sources checked

Three primary Kubernetes references were retrieved successfully on November 8, 2026 UTC:

  • StatefulSets defines sticky identity, the required headless-Service relationship, Pod management policies, update strategies, partitions, maximum unavailable Pods, ControllerRevisions, and claim-retention behavior. The page reports a modification on October 12, 2026.
  • StatefulSet basics demonstrates a headless Service, ordinal Pods, volumeClaimTemplates, scaling, and update operations. The page reports a modification on April 12, 2026.
  • Persistent Volumes defines PersistentVolume and PersistentVolumeClaim binding, storage classes, provisioning, and the need to observe claims that remain unbound. The page reports a modification on June 17, 2026.

These maintained technical pages support an evergreen review task. Match the documented behavior and API fields to the target control-plane version, storage provisioner, and database or queue compatibility requirements.

Contract details to verify

Establish identity before changing the template

Render the StatefulSet and the governing Service from the exact candidate values. Confirm the namespace, immutable selector, serviceName, Pod labels, and whether the Service is headless. The StatefulSet reference describes each Pod identity as an ordinal, a stable network identity, and stable storage. For a set named ledger with three replicas, the expected Pod names are ledger-0, ledger-1, and ledger-2; their DNS names depend on the governing Service and cluster domain. A Service with the wrong name or selector can leave valid Pods without the intended discovery path.

Inspect every container and init container in the rendered template. Record the service account, probes, resource requests, termination behavior, and any sidecar that reads or writes the claim. Use the health-probe review guide when the patch changes readiness or liveness. A Pod that is Running but not Ready can block an ordered rollout while its process still holds a volume.

Treat a change to volumeClaimTemplates as a storage migration decision. Compare storage class, access mode, requested capacity, selectors, data source, filesystem expectations, and mount path. A larger request may require backend support and cannot make an existing volume grow by itself. A changed claim name or mount can point a new revision at different data. Preserve a before-and-after table keyed by ordinal and claim name; do not infer the mapping from a Pod count.

For a review fixture named ledger, capture controller and Pod state against the exact rendered namespace and selector. These read-only commands expose the identity fields to compare; they do not establish quorum or data consistency:

kubectl --context review-cluster --namespace agent-review \
  get statefulset ledger -o json |
  jq '{uid: .metadata.uid,
       generation: .metadata.generation,
       observedGeneration: .status.observedGeneration,
       serviceName: .spec.serviceName,
       podManagementPolicy: .spec.podManagementPolicy,
       updateStrategy: .spec.updateStrategy,
       claims: .spec.volumeClaimTemplates,
       currentRevision: .status.currentRevision,
       updateRevision: .status.updateRevision,
       replicas: .status.replicas,
       readyReplicas: .status.readyReplicas,
       updatedReplicas: .status.updatedReplicas}'

kubectl --context review-cluster --namespace agent-review \
  get pods -l app=ledger -o json |
  jq '[.items[] | {name: .metadata.name,
       uid: .metadata.uid,
       revision: .metadata.labels["controller-revision-hash"],
       phase: .status.phase,
       conditions: [.status.conditions[]? | select(.type == "Ready") | {status, reason}],
       volumes: .spec.volumes}]'

kubectl --context review-cluster --namespace agent-review get pvc -o json |
  jq '[.items[] | {name: .metadata.name,
       phase: .status.phase,
       capacity: .status.capacity,
       storageClassName: .spec.storageClassName,
       volumeName: .spec.volumeName,
       accessModes: .spec.accessModes,
       owners: .metadata.ownerReferences}]'

Replace the sample context, namespace, and Pod selector with values from the approved fixture and rendered StatefulSet selector. The Pod and claim names should be joined using the volume-claim-template name, StatefulSet name, and ordinal, then compared with the observed volumeName and owner references.

Check management policy and replica ownership

OrderedReady is the default podManagementPolicy. It creates or terminates Pods in ordinal order and waits for the earlier Pod to be Running and Ready before proceeding. Parallel launches or terminates all Pods without those readiness and termination waits, while the unique identities remain. Choose the policy from the application’s bootstrap and quorum protocol. Parallel creation is not evidence that replicas have joined a quorum, and OrderedReady does not guarantee that the application has replicated its data.

Inventory every writer of .spec.replicas. If an HPA manages the StatefulSet, do not leave a fixed replica value in a regularly applied manifest; the controller reference warns that a manifest can overwrite manual scaling. The HPA review guide covers that ownership question for autoscaled workloads. Record the minimum safe replica count, quorum, zone placement, and disruption budget before approving a scale change.

Review update order, partitions, and availability

The default RollingUpdate strategy deletes and recreates Pods from the largest ordinal to the smallest. The control plane waits for an updated Pod to be Running and Ready before updating its predecessor; minReadySeconds adds a required ready interval. This order can be incompatible with a leader-first or follower-first application protocol, so state the protocol assumption in the review.

A partition updates only Pods whose ordinals are greater than or equal to the partition. With three replicas and partition: 2, ordinal 2 can become the canary while ordinals 0 and 1 remain on the prior template. If the partition exceeds the replica count, a template update is not propagated to Pods. Deleting a lower ordinal during a partition does not promote it to the new template; it is recreated at the previous version. Test the exact deletion and recreation behavior before using a partition as a staged release control.

Kubernetes 1.37 documents rollingUpdate.maxUnavailable as a beta field. It accepts an absolute number or a percentage rounded up, cannot be zero, defaults to one, and applies to Pods in the ordinal range from zero through replicas - 1. With podManagementPolicy: Parallel and a value greater than one, several Pods can be terminated and recreated together. These settings describe controller concurrency, not application availability or data safety. Check capacity, quorum, PDB policy, and client routing separately. The PDB review guide covers voluntary disruption as a separate contract.

Use an explicit review fixture such as:

replicas: 3
podManagementPolicy: OrderedReady
updateStrategy:
  type: RollingUpdate
  rollingUpdate:
    partition: 2
    maxUnavailable: 1
minReadySeconds: 30
revisionHistoryLimit: 5

These values illustrate a canary and timing policy, not universal defaults. A reviewer should calculate which ordinals change, how long each must remain ready, and whether the workload can tolerate the permitted unavailable count. Capture the StatefulSet generation, observed generation, Pod UIDs, controller revision hashes, and current and ready counts before and after each step.

Verify PVC binding, retention, and recovery

For every volumeClaimTemplates entry, map the expected claim name to the ordinal and inspect its namespace, phase, capacity, storage class, access modes, volume name, and owner references. The Persistent Volumes reference explains that a claim can remain Pending when a matching volume or dynamic provisioner is unavailable. A StatefulSet rollout that waits on an unbound claim is a storage or cluster-capacity failure, not proof that the new image is broken.

Review the StatefulSet’s persistentVolumeClaimRetentionPolicy when present. The current reference defines whenDeleted and whenScaled, each set to Retain or Delete; Retain is the default behavior. A Delete policy can remove claims associated with deleted or scaled-down Pods after termination. Verify the exact owner references and garbage-collection result in a disposable namespace before accepting a destructive policy. Keep backup and restore evidence outside the StatefulSet review: retaining a PVC does not prove that its application data is consistent or recoverable.

The retention policy is stable and enabled by default in Kubernetes v1.32 and later. For older clusters, confirm feature-gate availability and the API server and controller-manager configuration before relying on these fields.

StatefulSet ControllerRevisions retain prior Pod templates for version tracking and rollback. Check revisionHistoryLimit against the recovery requirement; setting it too low, including zero, removes rollback history. Preview the target revision and inspect the full template, but remember that a template rollback does not reverse a schema migration or an external configuration change. With the default OrderedReady policy, a broken Pod can leave a rollout waiting; reverting the template alone may not be enough, and Pods attempted with the bad revision may need explicit deletion through the approved recovery procedure.

Exercise a bounded test matrix

Run the candidate only through the authorized disposable-cluster workflow. Establish a healthy baseline and record the identity and claim of every Pod. Then isolate one condition at a time:

Controlled caseEvidence to retain
Healthy template updateCandidate revision, ordinal order, readiness timeline, claim identity, and harmless application checks
One updated Pod never becomes ReadyStalled ordinal, controller conditions, events, old and new revision hashes, and recovery decision
Partitioned canaryWhich ordinals changed, which stayed old, and the result of deleting and recreating each relevant Pod
Claim or provisioner unavailablePVC phase and events, storage-class diagnostics, Pod scheduling state, and restored binding
Scale down or StatefulSet deletionPod termination order, claim owner references, retained or deleted claims, and data validation plan
Approved rollbackTarget ControllerRevision, new revision created by recovery, readiness, and application compatibility checks

Keep a baseline after each mutation. Record timestamps and exit statuses from read-only inspections, and identify every observation by StatefulSet UID, Pod UID, claim name, and controller revision. A green kubectl condition is one signal; it is not a replication, durability, or client-traffic result.

Failure modes

A Deployment-style rollout assumption is applied to a StatefulSet. The controller preserves ordinal identity and normally updates from the largest ordinal downward. Recalculate the sequence and application compatibility.

The Service is present but not governing the StatefulSet. Check serviceName, headless configuration, selectors, and per-Pod DNS before accepting network evidence.

Parallel management is treated as quorum. It removes controller ordering waits; it does not prove that the application members joined or that writes are safe.

A partition is described as a global canary switch. It applies to ordinals at or above its value. Test lower-ordinal deletion and recreation under the partition.

A Pending claim is blamed on the new image. Inspect PVC binding, storage class, provisioner events, and node constraints separately.

A template revert is called a complete rollback. Review retained ControllerRevisions, Pods already created with the bad template, database compatibility, and claim data before recovery.

A scale-down policy deletes durable data unexpectedly. Verify whenScaled and whenDeleted, owner references, and the storage team’s retention requirement in a disposable namespace.

FAQ

Does a StatefulSet guarantee database replication?

No. It gives Pods stable identities and controller ordering. The database or queue must establish membership, replication, fencing, and recovery, and those outcomes need application-level checks.

Is OrderedReady always safer than Parallel?

No. OrderedReady reduces controller concurrency but can block behind one unhealthy ordinal. Parallel can be appropriate when the application handles independent startup and termination. Choose and test the policy against the workload protocol.

Does a partition update only one Pod?

It can. With a partition equal to the highest ordinal, only that ordinal is eligible. A partition lower than the replica count updates every ordinal at or above it, and a partition above the count propagates no template change to existing Pods.

Does retaining a PVC prove the data is recoverable?

No. Retention keeps the claim and its volume according to the policy. Validate filesystem, application consistency, backups, and restore procedures separately.

Can a StatefulSet rollback undo a schema migration?

No. A ControllerRevision restores the Pod-template portion. Coordinate application schema, external configuration, and data compatibility with the owner before recovering the template.

Reader next step

Choose one agent-written StatefulSet patch. Render the governing Service, Pod template, update strategy, and claim templates, then write the ordinal-to-DNS-to-PVC table. In a disposable environment, collect a healthy update, an unready-ordinal stall, a partition or unavailable-Pod case if used, and a scale or deletion retention result. Attach StatefulSet and Pod UIDs, controller revisions, PVC events, claim owner references, and application checks to the pull request so each conclusion refers to the exact candidate.