What Is the Difference Between a Deployment and a StatefulSet?

Detailed Answer

Kubernetes offers different workload controllers because not all applications have the same requirements. The two most commonly compared are Deployments and StatefulSets. Understanding when to use each is a fundamental skill for designing production Kubernetes architectures.

Side-by-Side Comparison

| Feature | Deployment | StatefulSet | |---|---|---| | Pod identity | Random hash suffix (e.g., web-5d7b9f6c4-xk2p9) | Ordinal index (e.g., web-0, web-1) | | Pod ordering | No guaranteed order | Created in order 0, 1, 2... Deleted in reverse | | Storage | Shared PVC (or emptyDir) | Per-Pod PVC via volumeClaimTemplates | | Network identity | None (use Service) | Stable DNS via headless Service | | Rollout style | All Pods interchangeable | Ordered, one at a time by default | | Primary use case | Stateless apps (web servers, APIs) | Stateful apps (databases, message queues) |

Deployment Example -- Stateless Web Server

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-server
spec:
  replicas: 3
  selector:
    matchLabels:
      app: api-server
  template:
    metadata:
      labels:
        app: api-server
    spec:
      containers:
        - name: api
          image: api-server:2.1
          ports:
            - containerPort: 8080
          env:
            - name: DB_HOST
              value: "postgres-0.postgres.default.svc.cluster.local"

Every replica is identical. If api-server-7b8d5c-abc12 dies, its replacement api-server-7b8d5c-xyz99 is functionally equivalent. No state is lost.

StatefulSet Example -- Database Cluster

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: postgres
spec:
  serviceName: postgres
  replicas: 3
  selector:
    matchLabels:
      app: postgres
  template:
    metadata:
      labels:
        app: postgres
    spec:
      containers:
        - name: postgres
          image: postgres:16
          ports:
            - containerPort: 5432
          volumeMounts:
            - name: data
              mountPath: /var/lib/postgresql/data
  volumeClaimTemplates:
    - metadata:
        name: data
      spec:
        accessModes: ["ReadWriteOnce"]
        storageClassName: fast-ssd
        resources:
          requests:
            storage: 50Gi

This creates:

• postgres-0 with PVC data-postgres-0
• postgres-1 with PVC data-postgres-1
• postgres-2 with PVC data-postgres-2

Each Pod has its own dedicated storage. If postgres-1 is rescheduled to another node, it reattaches to data-postgres-1 and recovers its data.

Stable Network Identity

A StatefulSet requires a headless Service (clusterIP: None):

apiVersion: v1
kind: Service
metadata:
  name: postgres
spec:
  clusterIP: None
  selector:
    app: postgres
  ports:
    - port: 5432

Each Pod gets a stable DNS record:

postgres-0.postgres.default.svc.cluster.local
postgres-1.postgres.default.svc.cluster.local
postgres-2.postgres.default.svc.cluster.local

This predictable naming is essential for database replication where nodes need to discover and communicate with specific peers.

Ordering Guarantees

StatefulSets start Pods sequentially: postgres-0 must be Running and Ready before postgres-1 is created. This matters for databases where the primary (ordinal 0) must initialize before replicas join.

During deletion or scaling down, Pods are terminated in reverse order: postgres-2 first, then postgres-1.

Deployments have no such ordering. All Pods are started and stopped concurrently (subject to maxSurge/maxUnavailable).

When to Use Each

Use a Deployment when:

• Your application is stateless or stores state externally (e.g., in a managed database or object storage).
• Pods are interchangeable and do not need unique identities.
• You want fast rollouts and easy horizontal scaling.
• Examples: REST APIs, web frontends, microservices, workers pulling from a queue.

Use a StatefulSet when:

• Each Pod needs its own persistent volume.
• Pods require stable, predictable hostnames.
• The application requires ordered startup, shutdown, or rolling updates.
• Examples: PostgreSQL, MySQL, MongoDB, Kafka, ZooKeeper, Elasticsearch.

Common Mistakes

1. Using a Deployment for a database because it is "simpler." This works for single-replica dev setups but breaks down when scaling or when a Pod is rescheduled and loses its data.

2. Using a StatefulSet for a stateless app because it seems "safer." This adds unnecessary complexity and slows down rollouts due to ordered updates.

3. Forgetting the headless Service for a StatefulSet. Without it, Pods do not get stable DNS records.

4. Assuming StatefulSet volumes are deleted on scale-down. PVCs are retained by default. You must delete them manually to reclaim storage.

Rollout Behavior Differences

Deployments create a new ReplicaSet and gradually shift traffic. StatefulSets update Pods in reverse ordinal order by default (highest ordinal first):

# StatefulSet update strategy
spec:
  updateStrategy:
    type: RollingUpdate
    rollingUpdate:
      partition: 0     # Update all Pods
      maxUnavailable: 1

The partition field lets you do canary-style updates. Setting partition: 2 means only Pods with ordinal >= 2 are updated, leaving postgres-0 and postgres-1 on the old version.

Summary

Deployments and StatefulSets solve different problems. Deployments are optimized for stateless workloads where Pods are disposable and interchangeable. StatefulSets are designed for stateful workloads that need stable identities, dedicated storage, and ordered lifecycle operations. Choosing the right one is not a matter of preference -- it is a matter of correctness.