kubernetes
/
website
mirror of https://github.com/kubernetes/website.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

completes move of statefulset to controllers 

shortens intro in favor of another Components section
reviewable/pr1839/r3
Kenneth Owens 2016-11-17 15:23:07 -08:00 committed by Devin Donnelly
parent 19907287d9
commit ef783ec028
1 changed files with 28 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

65
docs/concepts/object-metadata/statefulsets.md → docs/concepts/controllers/statefulsets.md
View File

@ -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,