StatefulSet Basics [page]deterministic

This tutorial provides an introduction to managing applications with [StatefulSets](#gloss:statefulset). It demonstrates how to create, delete, scale, and update the Pods of StatefulSets.

##

Before you begin this tutorial, you should familiarize yourself with the following Kubernetes concepts:

* [Pods](/docs/concepts/workloads/pods/) * [Cluster DNS](/docs/concepts/services-networking/dns-pod-service/) * [Headless Services](/docs/concepts/services-networking/service/#headless-services) * [PersistentVolumes](/docs/concepts/storage/persistent-volumes/) * [PersistentVolumes Provisioning](/docs/concepts/storage/dynamic-provisioning/) * The [kubectl](/docs/reference/kubectl/kubectl/) command line tool

You should configure `kubectl` to use a context that uses the `default` namespace. If you are using an existing cluster, make sure that it's OK to use that cluster's default namespace to practice. Ideally, practice in a cluster that doesn't run any real workloads.

It's also useful to read the concept page about [StatefulSets](/docs/concepts/workloads/controllers/statefulset/).

This tutorial assumes that your cluster is configured to dynamically provision PersistentVolumes. You'll also need to have a [default StorageClass](/docs/concepts/storage/storage-classes/#default-storageclass). If your cluster is not configured to provision storage dynamically, you will have to manually provision two 1 GiB volumes prior to starting this tutorial and set up your cluster so that those PersistentVolumes map to the PersistentVolumeClaim templates that the StatefulSet defines.

##

StatefulSets are intended to be used with stateful applications and distributed systems. However, the administration of stateful applications and distributed systems on Kubernetes is a broad, complex topic. In order to demonstrate the basic features of a StatefulSet, and not to conflate the former topic with the latter, you will deploy a simple web application using a StatefulSet.

After this tutorial, you will be familiar with the following.

* How to create a StatefulSet * How a StatefulSet manages its Pods * How to delete a StatefulSet * How to scale a StatefulSet * How to update a StatefulSet's Pods

## Creating a StatefulSet

Begin by creating a StatefulSet (and the Service that it relies upon) using the example below. It is similar to the example presented in the [StatefulSets](/docs/concepts/workloads/controllers/statefulset/) concept. It creates a [headless Service](/docs/concepts/services-networking/service/#headless-services), `nginx`, to publish the IP addresses of Pods in the StatefulSet, `web`.

You will need to use at least two terminal windows. In the first terminal, use [`kubectl get`](/docs/reference/generated/kubectl/kubectl-commands/#get) to [watch](#gloss:watch) the creation of the StatefulSet's Pods.

```shell # use this terminal to run commands that specify --watch # end this watch when you are asked to start a new watch kubectl get pods --watch -l app=nginx ```

In the second terminal, use [`kubectl apply`](/docs/reference/generated/kubectl/kubectl-commands/#apply) to create the headless Service and StatefulSet:

```shell kubectl apply -f https://k8s.io/examples/application/web/web.yaml ``` ``` service/nginx created statefulset.apps/web created ```

The command above creates two Pods, each running an [NGINX](https://www.nginx.com) webserver. Get the `nginx` Service... ```shell kubectl get service nginx ``` ``` NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE nginx ClusterIP None <none> 80/TCP 12s ``` ...then get the `web` StatefulSet, to verify that both were created successfully: ```shell kubectl get statefulset web ``` ``` NAME READY AGE web 2/2 37s ```

### Ordered Pod creation

A StatefulSet defaults to creating its Pods in a strict order.

For a StatefulSet with _n_ replicas, when Pods are being deployed, they are created sequentially, ordered from _{0..n-1}_. Examine the output …(trimmed)