Skip to main content
StatefulSets manage stateful applications that require stable network identities, persistent storage, and ordered deployment. They are ideal for databases, message queues, and other applications that maintain state.

​
Key Concepts

StatefulSet

A controller that manages pods with stable identities and persistent storage.

Stable Identity

Each pod gets a persistent hostname (e.g., mysql-0, mysql-1) that survives restarts.

Headless Service

A service that provides DNS entries for each pod without load balancing.

VolumeClaimTemplate

Template for creating PersistentVolumeClaims for each pod automatically.

​
Required Permissions

ActionPermission
View statefulsetsiam:project:infrastructure:kubernetes:read
Scale statefulsetiam:project:infrastructure:kubernetes:write
Restart statefulsetiam:project:infrastructure:kubernetes:write
Create statefulsetiam:project:infrastructure:kubernetes:write
Edit statefulsetiam:project:infrastructure:kubernetes:write
Delete statefulsetiam:project:infrastructure:kubernetes:delete

​
StatefulSet Status Values

StatusDescription
RunningAll replicas are ready
UpdatingRolling update in progress
NotReadySome replicas are not ready
Scaled to 0StatefulSet has zero replicas
UnknownStatus cannot be determined

​
StatefulSet Metrics

MetricDescription
ReplicasDesired number of pods
ReadyPods that are ready (ready/desired)
CurrentPods with current spec version
UpdatedPods updated to latest template
AvailablePods available for service

​
How to View StatefulSets

1

Select Cluster

Choose a cluster from the cluster dropdown.
2

Select Namespace

Choose a namespace or select “all” to view StatefulSets across all namespaces.
3

Filter and Search

Use the search box to find StatefulSets by name, or filter by status.

​
How to View StatefulSet Details

1

Find the StatefulSet

Locate the StatefulSet in the list.
2

Click StatefulSet Name

Click on the StatefulSet name to open the detail drawer.
3

Review Details

View StatefulSet information including:
  • Pod status and ordinal indices
  • Container specifications
  • Headless service name
  • Volume claim templates
  • Update strategy configuration

​
How to Scale a StatefulSet

1

Find the StatefulSet

Locate the StatefulSet in the list.
2

Open Actions Menu

Click the actions menu (three dots) on the StatefulSet row.
3

Click Scale

Select Scale to open the scale dialog.
4

Set Replica Count

Enter the desired number of replicas.
5

Apply

Click Scale to apply the change.
Scaling behavior:
  • Scale up: New pods are created in order (pod-0, pod-1, pod-2…)
  • Scale down: Pods are terminated in reverse order (highest ordinal first)
  • Each pod must be Running and Ready before the next is created/terminated
Scaling down does NOT delete PersistentVolumeClaims. Data persists and will be reattached if you scale back up.

​
How to Restart a StatefulSet

Restart triggers a rolling restart of all pods.
1

Find the StatefulSet

Locate the StatefulSet in the list.
2

Open Actions Menu

Click the actions menu on the StatefulSet row.
3

Click Restart

Select Restart from the menu.
4

Monitor

Watch the status change to Updating as pods are replaced in order.
Restart performs an ordered rolling restart. By default, pods are updated one at a time in reverse ordinal order (highest to lowest).

​
How to Create a StatefulSet

1

Click Create StatefulSet

Click the Create StatefulSet button in the page header.
2

Write YAML

Enter the StatefulSet manifest in YAML format. Include:
  • serviceName pointing to a headless service
  • volumeClaimTemplates if persistent storage is needed
3

Select Namespace

Choose the target namespace for the StatefulSet.
4

Create

Click Create to apply the manifest.
Create the headless service before the StatefulSet. The service must have clusterIP: None and selectors matching the StatefulSet pods.

​
How to Edit a StatefulSet

1

Open Actions Menu

Click the actions menu on the StatefulSet row.
2

Click Edit YAML

Select Edit YAML to open the editor.
3

Modify Spec

Edit the StatefulSet specification. Common changes:
  • Container image (triggers rolling update)
  • Resource requests/limits
  • Environment variables
  • Replica count
4

Save

Click Update to apply changes.
Some StatefulSet fields are immutable after creation: serviceName, podManagementPolicy, and volumeClaimTemplates. To change these, delete and recreate the StatefulSet.

​
How to Delete a StatefulSet

1

Open Actions Menu

Click the actions menu on the StatefulSet row.
2

Click Delete

Select Delete from the menu.
3

Confirm

Confirm the deletion.
Deleting a StatefulSet removes the controller and pods but does NOT delete PersistentVolumeClaims. You must manually delete PVCs to free storage.

​
Update Strategies

StatefulSets support two update strategies:
StrategyDescription
RollingUpdateUpdates pods in reverse ordinal order (default). Configurable via partition.
OnDeleteOnly updates pods when they are manually deleted.
RollingUpdate with partition:
  • Pods with ordinal >= partition are updated
  • Pods with ordinal < partition are not updated
  • Useful for canary deployments
updateStrategy:
  type: RollingUpdate
  rollingUpdate:
    partition: 2  # Only update pods 2, 3, 4... Leave 0, 1 on old version

​
Pod Management Policy

PolicyDescription
OrderedReadyCreate/delete pods one at a time in order (default)
ParallelCreate/delete all pods simultaneously
OrderedReady is recommended for most stateful applications. Use Parallel only when pods don’t depend on each other.

​
Troubleshooting

  • A pod may be failing readiness checks
  • Check pod events and logs for errors
  • Verify PVC is bound and storage is available
  • Check if previous pod terminated cleanly
  • Previous pod must be Running and Ready first
  • Check pod events for scheduling issues
  • Verify PVC binding if using persistent storage
  • Check headless service exists and selectors match
  • Verify volumeClaimTemplates is correctly defined
  • Check StorageClass exists and is default or specified
  • Verify storage provisioner is working
  • Check for quota limits on PVCs
  • Ensure PVC is correctly mounted in pod spec
  • Verify data is written to the mounted path, not container filesystem
  • Check PVC still exists and is bound
  • Verify headless service has clusterIP: None
  • Check service selector matches pod labels
  • Use full DNS name: pod-0.service-name.namespace.svc.cluster.local
  • Verify pods are Ready
  • Pods are deleted in reverse order, one at a time
  • Each pod must terminate before the next begins
  • Check for pods stuck in Terminating state
  • Verify no finalizers blocking deletion

​
FAQ

Deployments are for stateless applications where pods are interchangeable. StatefulSets provide stable identities, ordered operations, and persistent storage for stateful applications like databases.
The headless service provides DNS entries for each pod (e.g., mysql-0.mysql.default.svc.cluster.local). This allows clients to connect to specific pods by name, which is essential for stateful applications.
No. PersistentVolumeClaims are preserved to prevent data loss. You must manually delete PVCs if you want to free the storage.
Use the partition field in RollingUpdate strategy. Set partition to N to only update pods with ordinal >= N, leaving lower ordinals on the old version for testing.
Yes. Scaling to zero terminates all pods but preserves PVCs. When you scale back up, pods reattach to their original PVCs with data intact.
OrderedReady policy ensures each pod is Running and Ready before creating the next. This is crucial for applications like databases where initialization order matters.
VolumeClaimTemplates are immutable. To change storage configuration, you must delete the StatefulSet (with orphan policy to keep pods), update the manifest, and recreate it.
If using dynamically provisioned storage, the PVC remains bound. When the pod is rescheduled to another node, it reattaches to the same PV (if the storage supports it) or waits for the node to recover.