diff --git a/docs/concepts/object-metadata/statefulsets.md b/docs/concepts/controllers/statefulsets.md similarity index 89% rename from docs/concepts/object-metadata/statefulsets.md rename to docs/concepts/controllers/statefulsets.md index 99d0228bca..8818241f46 100644 --- a/docs/concepts/object-metadata/statefulsets.md +++ b/docs/concepts/controllers/statefulsets.md @@ -4,22 +4,38 @@ {% capture overview %} **Stateful Sets are a beta feature in 1.5. This feature replaces the deprecated Pet Sets feature from 1.4. Users of Pet Sets are referred to the 1.5 -[Upgrade Guide](docs/tasks/stateful-sets/upgrade-pet-sets-to-stateful-sets.md) +[Upgrade Guide](/docs/tasks/stateful-set/upgrade-from-petsets-to-stateful-sets/) for further information on how to upgrade existing Pet Sets to Stateful Sets.** -A Stateful Set is a Controller that ensures that, at most, a given number of -replicas of a Pod are running at a time. Pods in a Stateful Set have an ordinal -(a unique integer index in the Stateful Set), a stable, unique network id that is -available in DNS, and stable, persistent storage. +A Stateful Set is a Controller that ensures that provides a unique identity to +its Pods, and provides garuantees about the ordering of deployment and scaling. +{% endcapture %} -For a Stateful Set with N replicas, when Pods are being deployed, they are -created sequentially, in order from {0..N-1}. Before a new Pod is deployed, all -of its predecessors must be [Running and Ready](/docs/user-guide/pod-states). -When Pods are being deleted, they are terminated in reverse order, from {N-1..0}, -and no pod is terminated until its successors have been terminated and are -completely shutdown or their[Termination Grace Periods](/docs/user-guide/pods/index#termination-of-pods) -has elapsed. +{% capture body %} +### When to Use a Stateful Set +Stateful Sets are valuable for applications that require one or more of the +following. + +* Stable, unique network identifiers. +* Stable, persistent storage. +* Ordered, graceful deployment and scaling. +* Ordered, graceful deletion and termination. + +As it is generally easier to manage, if an application doesn't require any of +the above guarantees, and if it is feasible to do so, it should be deployed as +a set of stateless replicas. + +### Limitations +* Stateful Set is a beta resource, not available in any Kubernetes release prior to 1.5. +* As with all alpha/beta resources, it can be disabled through the `--runtime-config` option passed to the apiserver. +* The only mutable field on a Stateful Set is `replicas` +* The storage for a given Pod must either be provisioned by a [Persistent Volume Provisioner](http://releases.k8s.io/{{page.githubbranch}}/examples/experimental/persistent-volume-provisioning/README.md) based on the requested `storage class`, or pre-provisioned by an admin. +* Deleting and/or scaling a Stateful Set down will *not* delete the volumes associated with the Stateful Set. This is done to ensure safety first, your data is more valuable than an auto purge of all related Stateful Set resources. **Deleting the Persistent Volume Claims will result in a deletion of the associated volumes**. +* Stateful Sets currently require a [Headless Service](/docs/user-guide/services/#headless-services) to be responsible for the network identity of the Pods. The user is responsible for this Service. +* Updating an existing Stateful Set is currently a manual process, meaning you either need to deploy a new Stateful Set with the new image version, or orphan Pods one by one, update their image, and join them back to the cluster. + +### Components The example below demonstrates the components of a Stateful Set. * A [Headless Service](/docs/user-guide/services/#headless-services), named nginx, is used to control the network domain. @@ -79,31 +95,6 @@ spec: storage: 1Gi ``` -{% endcapture %} - -{% capture body %} -### When to Use a Stateful Set -Stateful Sets are valuable for applications that require one or more of the -following. - -* Stable, unique network identifiers. -* Stable, persistent storage. -* Ordered, graceful deployment and scaling. -* Ordered, graceful deletion and termination. - -As it is generally easier to manage, if an application doesn't require any of -the above guarantees, and if it is feasible to do so, it should be deployed as -a set of stateless replicas. - -### Limitations -* Stateful Set is a beta resource, not available in any Kubernetes release prior to 1.5. -* As with all alpha/beta resources, it can be disabled through the `--runtime-config` option passed to the apiserver. -* The only mutable field on a Stateful Set is `replicas` -* The storage for a given Pod must either be provisioned by a [Persistent Volume Provisioner](http://releases.k8s.io/{{page.githubbranch}}/examples/experimental/persistent-volume-provisioning/README.md) based on the requested `storage class`, or pre-provisioned by an admin. -* Deleting and/or scaling a Stateful Set down will *not* delete the volumes associated with the Stateful Set. This is done to ensure safety first, your data is more valuable than an auto purge of all related Stateful Set resources. **Deleting the Persistent Volume Claims will result in a deletion of the associated volumes**. -* Stateful Sets currently require a [Headless Service](/docs/user-guide/services/#headless-services) to be responsible for the network identity of the Pods. The user is responsible for this Service. -* Updating an existing Stateful Set is currently a manual process, meaning you either need to deploy a new Stateful Set with the new image version, or orphan Pods one by one, update their image, and join them back to the cluster. - ### Pod Identity Stateful Set Pods have a unique identity that is comprised of an ordinal, a stable network identity, and stable storage. The identity sticks to the Pod,