StatefulSets

A Kubernetes StatefulSet runs replicated application pods that need stable pod names, ordered rollout behavior, or per-replica persistent storage. Use StatefulSets for databases, queues, model caches, and other workloads where each replica owns identity or data.

Use kubectl with your namespace kubeconfig to create and manage StatefulSets on RemoteGPU. Include the RemoteGPU runtime SKU label in the pod template so the workload can be scheduled with the right plan.

Choose a workflow

Use kubectl when your team manages StatefulSets from manifests or CI. Create the governing service and StatefulSet in the same namespace.

Use the console to create the namespace and download kubeconfig.

When to use a StatefulSet

A StatefulSet is useful for:

• Workloads that need stable pod names such as redis-0 or worker-0.
• Applications that need one persistent volume per replica.
• Stateful services that rely on ordered startup, update, or termination.
• Long-running workloads where each replica owns a stable identity.

For stateless HTTP apps or workers, use a Deployment. For one-off or scheduled batch work, use a Job or CronJob.

Supported StatefulSet profile

StatefulSets use the standard namespace Kubernetes workflow with these RemoteGPU requirements.

Area	Description
Resource type	apps/v1 StatefulSet
Access path	kubectl with namespace kubeconfig
Plan selection	remotegpu.ai/runtime-sku label on the pod template
Storage	volumeClaimTemplates and existing PVC mounts must use a supported RemoteGPU storage profile
Networking	ClusterIP services; use clusterIP: None when the app needs stable pod DNS
Scaling	Standard statefulsets/scale behavior with kubectl scale

Create a StatefulSet

Create a manifest that includes a service and a StatefulSet. The example uses a headless service for stable pod DNS and a storage-standard volume claim template for per-replica storage.

apiVersion: v1
kind: Service
metadata:
  name: redis
spec:
  clusterIP: None
  selector:
    app: redis
  ports:
    - name: redis
      port: 6379
      targetPort: 6379
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: redis
spec:
  replicas: 1
  serviceName: redis
  selector:
    matchLabels:
      app: redis
  template:
    metadata:
      labels:
        app: redis
        remotegpu.ai/runtime-sku: cpu-shared-8g
    spec:
      automountServiceAccountToken: false
      containers:
        - name: redis
          image: redis:7-alpine
          args: ["redis-server", "--appendonly", "yes"]
          ports:
            - name: redis
              containerPort: 6379
          volumeMounts:
            - name: data
              mountPath: /data
  volumeClaimTemplates:
    - metadata:
        name: data
      spec:
        storageClassName: storage-standard
        accessModes: ["ReadWriteOnce"]
        volumeMode: Filesystem
        resources:
          requests:
            storage: 8Gi

Apply the manifest with your namespace kubeconfig:

kubectl --kubeconfig ./kubeconfig-team-ml.yaml apply -f statefulset.yaml
kubectl --kubeconfig ./kubeconfig-team-ml.yaml rollout status statefulset/redis

Use persistent storage

volumeClaimTemplates creates one PVC for each StatefulSet replica. The Redis example creates data-redis-0 for the first replica.

Each claim template must use a supported storage class, access mode, volume mode, and size. Read Storage for the supported storage profiles and fixed sizes.

Deleting a StatefulSet does not delete its PVCs. Delete the generated PVCs only when you no longer need the stored data. Generated PVCs continue to accrue storage usage while they exist, including after the StatefulSet is deleted or scaled to 0.

Operate StatefulSets

Scale a StatefulSet with kubectl scale:

kubectl --kubeconfig ./kubeconfig-team-ml.yaml scale statefulset/redis --replicas=2

Scale to 0 to stop pods while keeping the StatefulSet and PVCs:

kubectl --kubeconfig ./kubeconfig-team-ml.yaml scale statefulset/redis --replicas=0

Inspect the StatefulSet, pods, and generated PVCs:

kubectl --kubeconfig ./kubeconfig-team-ml.yaml get statefulset,pod,pvc -l app=redis

Delete the StatefulSet and service when you no longer need them:

kubectl --kubeconfig ./kubeconfig-team-ml.yaml delete statefulset redis
kubectl --kubeconfig ./kubeconfig-team-ml.yaml delete service redis

Troubleshooting

Symptom	What to check
kubectl apply is rejected	Confirm the pod template includes one RemoteGPU runtime SKU label and the service is a ClusterIP service
Pods stay pending	Check the selected plan, namespace quota, storage class, and pod events with kubectl describe pod
PVC creation is rejected	Confirm the storage class, size, access mode, volume mode, and namespace storage quota match a supported storage profile
Stable pod DNS does not resolve	Confirm spec.serviceName matches the service name and the service selector matches the pod labels
Scaling is rejected	Confirm the API key has Kubernetes exec access and the command uses the namespace kubeconfig
Data appears missing after cleanup	Confirm whether the generated PVCs were deleted; StatefulSet deletion keeps PVCs by default

Read next

• Read Storage to choose a PVC storage profile.
• Read Services to expose a StatefulSet inside the cluster.
• Read Deployments for stateless long-running workloads.
• Read Kubernetes overview for the overall access model.