#StatefulSets

#Understanding StatefulSets

Refer to the official Kubernetes documentation: StatefulSets

StatefulSet is a Kubernetes workload API object designed to manage stateful applications by providing:

• Stable network identity: DNS hostname <statefulset-name>-<ordinal>.<service-name>.ns.svc.cluster.local.
• Stable persistent storage: via volumeClaimTemplates.
• Ordered deployment/scaling: sequential Pod creation/deletion: Pod-0 → Pod-1 → Pod-N.
• Ordered rolling updates: reverse-ordinal Pod updates: Pod-N → Pod-0.

In distributed systems, multiple StatefulSets can be deployed as discrete components to deliver specialized stateful services (e.g., Kafka brokers, MongoDB shards).

#Creating StatefulSets

#Creating a StatefulSet by using CLI

#Prerequisites

• Ensure you have kubectl configured and connected to your cluster.

#YAML file example

# example-statefulset.yaml
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: web
spec:
  selector:
    matchLabels:
      app: nginx # has to match .spec.template.metadata.labels
  serviceName: 'nginx' # this headless Service is responsible for the network identity of the Pods
  replicas: 3 # defines the desired number of Pod replicas (default: 1)
  minReadySeconds: 10 # by default is 0
  template: # defines the Pod template for the StatefulSet
    metadata:
      labels:
        app: nginx # has to match .spec.selector.matchLabels
    spec:
      terminationGracePeriodSeconds: 10
      containers:
        - name: nginx
          image: registry.k8s.io/nginx-slim:0.24
          ports:
            - containerPort: 80
              name: web
          volumeMounts:
            - name: www
              mountPath: /usr/share/nginx/html
  volumeClaimTemplates: # defines PersistentVolumeClaim (PVC) templates. Each Pod gets a unique PersistentVolume (PV) dynamically provisioned based on these templates.
    - metadata:
        name: www
      spec:
        accessModes: ['ReadWriteOnce']
        storageClassName: 'my-storage-class'
        resources:
          requests:
            storage: 1Gi
---
# example-service.yaml
apiVersion: v1
kind: Service
metadata:
  name: nginx
  labels:
    app: nginx
spec:
  ports:
    - port: 80
      name: web
  clusterIP: None
  selector:
    app: nginx

#Creating a StatefulSet via YAML

# Step 1: To create the StatefulSet defined in *example-statefulset.yaml*, execute the following command
kubectl apply -f example-statefulset.yaml

# Step 2: To verify the creation and status of your StatefulSet and its associated Pods and PVCs:
kubectl get statefulset web # View StatefulSet
kubectl get pods -l app=nginx # Check Pods managed by this StatefulSet
kubectl get pvc -l app=nginx # Check PVCs created by volumeClaimTemplates

#Creating a StatefulSet by using web console

#Prerequisites

Obtain the image address. The source of the images can be from the image repository integrated by the platform administrator through the toolchain or from third-party platforms' image repositories.

• For the former, the Administrator typically assigns the image repository to your project, and you can use the images within it. If the required image repository is not found, please contact the Administrator for allocation.

• If it is a third-party platform's image repository, ensure that images can be pulled directly from it in the current cluster.

• If the image registry requires authentication, you need to configure the corresponding image pull secret. For more information, see Add ImagePullSecrets to ServiceAccount.

#Creating a StatefulSet by using new web console

The new web console can expose StatefulSet creation from different views. Choose the entry based on whether you are working from project scope or from a concrete cluster.

• Applications view: Start from the current project. Open Workloads > StatefulSets, select the target Cluster and Namespace, and then choose the workload model or creation flow that results in a StatefulSet.
• Clusters view: Start from a concrete cluster. Open the target cluster first, enter the target namespace, and then navigate to Workloads > StatefulSets to click Create StatefulSet.

#Procedure - Configure Basic Info

1. Container Platform, navigate to Workloads > StatefulSets in the left sidebar.

2. Click Create StatefulSet.

3. Select or Input an image, and click Confirm.

In the Basic Info section, configure declarative parameters for StatefulSet workloads:

#Procedure - Configure Pod

Pod section, please refer to Deployment - Configure Pod

#Procedure - Configure Containers

Containers section, please refer to Deployment - Configure Containers

#Procedure - Create

Click Create.

#When to use a StatefulSet in the Applications view

Use a StatefulSet when the workload depends on per-replica identity, stable naming, ordered lifecycle behavior, or persistent storage that should stay associated with a specific replica.

A StatefulSet is usually the better fit when:

• each replica should keep a stable ordinal identity
• the workload depends on stable network naming or a related headless Service
• each replica needs its own persistent volume claim
• startup, shutdown, or update order matters to the application

If the workload can be treated as interchangeable stateless replicas, review Deployments instead.

#Stateful workload review points

Before creating or updating a StatefulSet, review the following carefully:

• Whether the selected project, cluster, and namespace are the intended runtime scope
• Whether each replica requires stable identity
• Whether persistent storage is required for each replica
• Whether the workload depends on ordered startup, shutdown, or scaling behavior
• Whether the referenced storage settings are available in the target environment
• Whether configuration changes could affect data continuity or replica replacement behavior
• Whether the workload also expects a stable network identity through a related Service

#Heath Checks

• Health checks YAML file example
• Health checks configuration parameters in web console

#Managing StatefulSets

#Managing a StatefulSet by using CLI

#Viewing a StatefulSet

You can view a StatefulSet to get information of your application.

• Check the StatefulSet was created.

  kubectl get statefulsets

• Get details of your StatefulSet.

  kubectl describe statefulsets

#Scaling a StatefulSet

• To change the number of replicas for an existing StatefulSet:

  kubectl scale statefulset <statefulset-name> --replicas=<new-replica-count>

• Example:

  kubectl scale statefulset web --replicas=5

#Updating a StatefulSet (Rolling Update)

When you modify the Pod template of a StatefulSet (e.g., changing the container image), Kubernetes performs a rolling update by default (if updateStrategy is set to RollingUpdate, which is the default).

• First, edit the YAML file (e.g., example-statefulset.yaml) with the desired changes, then apply it:

  kubectl apply -f example-statefulset.yaml

• Then, you can monitor the progress of the rolling update:

  kubectl rollout status statefulset/<statefulset-name>

#Deleting a StatefulSet

To delete a StatefulSet and its associated Pods:

kubectl delete statefulset <statefulset-name>

By default, deleting a StatefulSet does not delete its associated PersistentVolumeClaims (PVCs) or PersistentVolumes (PVs) to prevent data loss. To also delete the PVCs, you must do so explicitly:

kubectl delete pvc -l app=<label-selector-for-your-statefulset> # Example: kubectl delete pvc -l app=nginx

Alternatively, if your volumeClaimTemplates use a StorageClass with a reclaimPolicy of Delete, the PVs and underlying storage will be deleted automatically when the PVCs are deleted.

#Managing a StatefulSet by using web console

#Viewing a StatefulSet

1. Container Platform, and navigate to Workloads > StatefulSets.
2. Locate the StatefulSet you wish to view.
3. Click the statefulSet name to see the Details, Topology, Logs, Events, Monitoring, etc.

#Updating a StatefulSet

1. Container Platform, and navigate to Workloads > StatefulSets.
2. Locate the StatefulSet you wish to update.
3. In the Actions drop-down menu, select Update to view the Edit StatefulSet page, you can update Replicas, image, updateStrategy, etc.

#Deleting a StatefulSet

1. Container Platform, and navigate to Workloads > StatefulSets.
2. Locate the StatefulSet you wish to delete.
3. In the Actions drop-down menu, Click the Delete button in the operations column and confirm.

StatefulSet deletion and scaling can have storage consequences that differ from stateless workloads. Before deleting or scaling down, confirm that the removed replicas do not still hold required data or cluster membership.