About StatefulSets in GKE

This page describes the use of StatefulSet objects in Google Kubernetes Engine (GKE). You can also learn how to Deploy a stateful application.

About StatefulSets

StatefulSets represent a set of Pods with unique, persistent identities, and stable hostnames that GKE maintains regardless of where they are scheduled. The state information and other resilient data for any given StatefulSet Pod is maintained in persistent volumes associated with each Pod in the StatefulSet. StatefulSet Pods can be restarted at any time.

For stateless applications, use Deployments.

StatefulSets function similarly in GKE and in Kubernetes. This document describes any GKE-specific considerations. To learn how StatefulSets work, see the Kubernetes documentation about StatefulSets.

Plan networking for StatefulSets

StatefulSets provide persistent storage in the form of a PersistentVolume and a unique network identity (hostname). The following table includes the caveats that application operators should be aware of when configuring a StatefulSet:

Networking caveat Description Best practice
GKE Services instead of fixed IP addresses

Although Pod replicas have a unique ordinal index, support per-replica volumes, and network identity (hostname), the IP addresses that are assigned to a replica can change if GKE reschedules or evicts a Pod.

To mitigate networking issues, the architecture should use Kubernetes Service resources. For more information, see Types of Kubernetes Services.
Headless Services

When initialized, a StatefulSet is paired with a matching headless service.

Ensure that the `metadata.name` in your Service matches the serviceName field in your StatefulSet. This enables each Pod in your application to be addressed at a unique, well-defined network address. Additionally, the headless service provides a multi-IP record for each replica in your StatefulSet, allowing full peer discovery.
Peer discovery

Stateful applications require a minimum number (quorum) of replicas to function with full availability.

As Pods can crash, be rescheduled, or evicted, each replica in a StatefulSet should be able to leave and rejoin quorum. Applications that require peering should have the capability to discover other peers through headless Services in Kubernetes.
Health check based on readiness probes and liveness probes

Your application should have properly configured readiness, liveness, and startup probes where applicable. Selecting timeouts for each probe is dependent on the requirements of your application.

For readiness probes, follow these best practices to configure your application to mark readiness when it is ready to serve traffic:

  • Liveness probes: You can use liveness probes to signal if a container is healthy. For example, a database replica can use a liveness probe to indicate that GKE should restart the replica, such as deadlock condition
  • Readiness probes: You can use readiness probes to remove a replica from serving traffic temporarily. For example, if you have a database replica that needs to perform a backup, you might use a readiness probe to temporarily stop receiving requests.
  • Startup probe: You can use startup probes to delay health checks until long running initializations are complete. For example, if you have a database replica, you might use a startup probe to wait for initialization of stored data from disk.

To read more about probes, see Configure Liveness, Readiness, and Startup Probes.

Work with StatefulSets

To learn how to deploy StatefulSets in your GKE cluster and interact with them, see the Kubernetes documentation about StatefulSet basics.

What's next