SS concept #1719

kow3ns · 2016-11-18T00:18:30Z

Adds statefulsets.md to concepts and updates the concepts index.md to contain Stateful Sets

This change is

StatefulSet referneces to Stateful Set and all PetSet references to Pet Set

moves statefulset.md into controllers update _data/concepts.yml to show a TOC based on the above

shortens intro in favor of another Components section

foxish · 2016-11-18T00:26:00Z

docs/concepts/controllers/statefulsets.md

+### 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`


We can change the PodTemplateSpec IIRC. Perhaps we should remove this assertion.

foxish · 2016-11-18T00:27:33Z

docs/concepts/controllers/statefulsets.md

+* 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**.


Maybe mention that if we provision our PVs manually, it does not exhibit this behavior?

foxish · 2016-11-18T00:45:51Z

docs/concepts/controllers/statefulsets.md

+  - metadata:
+      name: www
+      annotations:
+        volume.alpha.kubernetes.io/storage-class: anything


volume.beta....

foxish · 2016-11-18T00:47:48Z

docs/concepts/controllers/statefulsets.md

+are created based on the `volumeClaimTemplates` field of the Stateful Set. In the 
+example above, each Pod will receive a single persistent volume with a storage 
+class of anything and 1 Gib of provisioned storage. When a Pod is (re)scheduled,
+its volume(s) are available on the node on which it is launched. Note that, the 


volume(s) are available on the node
should probably be rephrased.

janetkuo · 2016-11-18T00:42:59Z

docs/concepts/index.md

-[Annotations](/docs/concepts/object-metadata/annotations/)
+
+* [Annotations](/docs/concepts/object-metadata/annotations/)
+* [Stateful Sets](/docs/concepts/controllers/statefulsets/)


Need to update this to reflect new nav

I'm not sure that I follow. The link works. This is the correct location of the asset. Did you mean something else?

janetkuo · 2016-11-18T00:48:49Z

docs/concepts/controllers/statefulsets.md

+* The volumeClaimTemplates, will provide stable storage using [Persistent Volumes](/docs/user-guide/volumes/) provisioned by a 
+ [Persistent Volume Provisioner](http://releases.k8s.io/{{page.githubbranch}}/examples/experimental/persistent-volume-provisioning/README.md).
+
+```yaml


Use something like {% include code.html language="yaml" file="petset.yaml" ghlink="/docs/user-guide/petset.yaml" %} instead. We may need to rename the file and/or move the file here also

The annotations example includes its YAML inline. I did the same so that the concepts pages are uniform in how they present structural examples. I'm in favor of using inline for concepts because the include produces a copy to clipboard button, and I don't think we want users copying and pasting from the concepts. If the consensus is that we want to use includes, then we should update the annotations concept for consistency.

foxish · 2016-11-18T17:25:13Z

docs/concepts/controllers/statefulsets.md

@@ -0,0 +1,163 @@
+---


Add assignees here, so we know when this doc has issues raised against it:

--- assignees: - bprashanth - enisoc - erictune - foxish - janetkuo - kow3ns - smarterclayton ---

Thanks for the list. We should have the same list of assignees in all StatefulSet docs

adds assignees clarifies stable storage description

enisoc · 2016-11-18T21:47:17Z

Reviewed 2 of 3 files at r1, 1 of 1 files at r2.
Review status: all files reviewed at latest revision, 16 unresolved discussions.

docs/concepts/index.md, line 10 at r1 (raw file):

Previously, kow3ns (Kenneth Owens) wrote…

I'm not sure that I follow. The link works. This is the correct location of the asset. Did you mean something else?

I think she means since you added a Controllers section in `concepts.yml` you should also add a new `#### Controllers` heading here. Currently you've put Stateful Sets under the `Object Metadata` heading.

docs/concepts/controllers/statefulsets.md, line 13 at r2 (raw file):

{% capture overview %}
**Stateful Sets are a beta feature in 1.5. This feature replaces the deprecated

Usually "deprecated" means it still exists but you should migrate away. It would be more honest to call Pet Sets "retired" or something like that. Personally I'm fond of the phrase "deprecated with extreme prejudice" but that's too obscure for public docs. :)

docs/concepts/controllers/statefulsets.md, line 18 at r2 (raw file):

for further information on how to upgrade existing Pet Sets to Stateful Sets.**

A Stateful Set is a Controller that ensures that provides a unique identity to

Remove "ensures that".

docs/concepts/controllers/statefulsets.md, line 19 at r2 (raw file):

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.

guarantees*

docs/concepts/controllers/statefulsets.md, line 28 at r2 (raw file):

following.

* Stable, unique network identifiers.

"Stable" is a bit of an overloaded term. We should at least note below this list that in this case "stable" means "survives pod rescheduling" or something like that.

docs/concepts/controllers/statefulsets.md, line 43 at r2 (raw file):

* 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.

TODO: link to Task for doing manual updates (IIRC we plan to write one?).

docs/concepts/controllers/statefulsets.md, line 111 at r2 (raw file):

For a Stateful Set with N replicas, each Pod in the Stateful Set will be 
assigned a integer ordinal, in the range [0,N), that is unique over the Set.

"an integer"*

docs/concepts/controllers/statefulsets.md, line 113 at r2 (raw file):

assigned a integer ordinal, in the range [0,N), that is unique over the Set. 

__Stable Network Id__

Either capitalize "ID" or use "Identity". Unless we are providing stable network id. :)

docs/concepts/controllers/statefulsets.md, line 144 at r2 (raw file):

are created based on the `volumeClaimTemplates` field of the Stateful Set. In the 
example above, each Pod will receive a single persistent volume with a storage 
class of anything and 1 Gib of provisioned storage. When a Pod is (re) scheduled onto

anything should be backtick quoted for clarity. BTW, I've seen both anything and default used here. Does anyone know the difference?

docs/concepts/controllers/statefulsets.md, line 146 at r2 (raw file):

class of anything and 1 Gib of provisioned storage. When a Pod is (re) scheduled onto
a node, its `volumeMounts` mount the Persistent Volumes associated with its 
Persistent Volume Claims. That is, the Note that, the Persistent Volumes associated with the

"The is, the Note that," needs an edit.

Comments from Reviewable

kow3ns · 2016-11-18T23:09:46Z

docs/concepts/index.md, line 10 at r1 (raw file):

Previously, enisoc (Anthony Yeh) wrote…

I think she means since you added a Controllers section in concepts.yml you should also add a new #### Controllers heading here. Currently you've put Stateful Sets under the Object Metadata heading.

https://github.com/kow3ns/kubernetes.github.io/blob/7aa8c5d2e6253739a2da144d933b9daa1804ec36/_data/concepts.yml#L10-L13 It is already there

Comments from Reviewable

kow3ns · 2016-11-18T23:09:57Z

docs/concepts/controllers/statefulsets.md, line 32 at r1 (raw file):

Previously, kow3ns (Kenneth Owens) wrote…

We should.

Done.

Comments from Reviewable

kow3ns · 2016-11-18T23:20:06Z

docs/concepts/controllers/statefulsets.md, line 43 at r2 (raw file):

Previously, enisoc (Anthony Yeh) wrote…

TODO: link to Task for doing manual updates (IIRC we plan to write one?).

The implementation of manual updates to an existing Stateful Set will differ based on the system.

Comments from Reviewable

kow3ns · 2016-11-18T23:20:21Z

docs/concepts/controllers/statefulsets.md, line 90 at r1 (raw file):

Previously, foxish (Anirudh Ramanathan) wrote…

volume.beta....

Done.

Comments from Reviewable

enisoc · 2016-11-18T23:29:02Z

Review status: all files reviewed at latest revision, 16 unresolved discussions.

docs/concepts/controllers/statefulsets.md, line 43 at r2 (raw file):

Previously, kow3ns (Kenneth Owens) wrote…

The implementation of manual updates to an existing Stateful Set will differ based on the system.

I checked and it is indeed in our plan for docs to write: "Task: updating an app that uses an SS"

If you don't think we should write one, comment on the doc plan.

Comments from Reviewable

Removes deprecation from comment wrt PetSets Creates separate section in concepts/index.md for Controllers Fixes grammer "an integer" Removes claim about persistent storage being auto-deleted Clarifies stability Adds call out tick around attributes

kow3ns · 2016-11-18T23:40:39Z

docs/concepts/controllers/statefulsets.md, line 43 at r2 (raw file):

Previously, enisoc (Anthony Yeh) wrote…

I checked and it is indeed in our plan for docs to write: "Task: updating an app that uses an SS"

If you don't think we should write one, comment on the doc plan.

We could write an example if it is in the plan, but we need to pick one system that is simple and apply the general concept. I would also think that the scope of this would be a tutorial ... we don't have a kubectl update that will do this atomically.

Comments from Reviewable

kow3ns · 2016-11-18T23:42:39Z

Review status: 1 of 3 files reviewed at latest revision, 16 unresolved discussions.

docs/concepts/controllers/statefulsets.md, line 32 at r1 (raw file):

Previously, kow3ns (Kenneth Owens) wrote…

Done.

Done.

docs/concepts/controllers/statefulsets.md, line 34 at r1 (raw file):

guarantees
Actually I looked into my GCP account and it never deletes the volumes. This should be removed.

docs/concepts/controllers/statefulsets.md, line 139 at r1 (raw file):

Previously, foxish (Anirudh Ramanathan) wrote…

volume(s) are available on the node

should probably be rephrased.

Done.

docs/concepts/controllers/statefulsets.md, line 13 at r2 (raw file):

Previously, enisoc (Anthony Yeh) wrote…

Usually "deprecated" means it still exists but you should migrate away. It would be more honest to call Pet Sets "retired" or something like that. Personally I'm fond of the phrase "deprecated with extreme prejudice" but that's too obscure for public docs. :)

I'll just remove deprecated

docs/concepts/controllers/statefulsets.md, line 18 at r2 (raw file):

Previously, enisoc (Anthony Yeh) wrote…

Remove "ensures that".

Done.

docs/concepts/controllers/statefulsets.md, line 19 at r2 (raw file):

Previously, enisoc (Anthony Yeh) wrote…

guarantees*

Done.

docs/concepts/controllers/statefulsets.md, line 28 at r2 (raw file):

Previously, enisoc (Anthony Yeh) wrote…

"Stable" is a bit of an overloaded term. We should at least note below this list that in this case "stable" means "survives pod rescheduling" or something like that.

Done.

docs/concepts/controllers/statefulsets.md, line 111 at r2 (raw file):

Previously, enisoc (Anthony Yeh) wrote…

"an integer"*

Done.

docs/concepts/controllers/statefulsets.md, line 113 at r2 (raw file):

Previously, enisoc (Anthony Yeh) wrote…

Either capitalize "ID" or use "Identity". Unless we are providing stable network id. :)

Done.

docs/concepts/controllers/statefulsets.md, line 144 at r2 (raw file):

Previously, enisoc (Anthony Yeh) wrote…

anything should be backtick quoted for clarity. BTW, I've seen both anything and default used here. Does anyone know the difference?

I haven't found any direct documentation as to the difference between anything and default. I could make a guess based on what is in the documentation, but we should probably dig through the code for an answer.

docs/concepts/controllers/statefulsets.md, line 146 at r2 (raw file):

Previously, enisoc (Anthony Yeh) wrote…

"The is, the Note that," needs an edit.

Done.

Comments from Reviewable

kow3ns · 2016-11-21T21:17:19Z

Review status: 1 of 3 files reviewed at latest revision, 16 unresolved discussions.

docs/concepts/controllers/statefulsets.md, line 34 at r1 (raw file):

Previously, kow3ns (Kenneth Owens) wrote…

> > guarantees > Actually I looked into my GCP account and it never deletes the volumes. This should be removed.

Done.

docs/concepts/controllers/statefulsets.md, line 46 at r1 (raw file):

Previously, kow3ns (Kenneth Owens) wrote…

> The annotations example includes its YAML inline. I did the same so that the concepts pages are uniform in how they present structural examples. I'm in favor of using inline for concepts because the include produces a copy to clipboard button, and I don't think we want users copying and pasting from the concepts. If the consensus is that we want to use includes, then we should update the annotations concept for consistency.

Done.

docs/concepts/controllers/statefulsets.md, line 13 at r2 (raw file):

Previously, kow3ns (Kenneth Owens) wrote…

> I'll just remove deprecated

Done.

docs/concepts/controllers/statefulsets.md, line 43 at r2 (raw file):

Previously, kow3ns (Kenneth Owens) wrote…

> We could write an example if it is in the plan, but we need to pick one system that is simple and apply the general concept. I would also think that the scope of this would be a tutorial ... we don't have a kubectl update that will do this atomically.

Done.

Comments from Reviewable

kow3ns · 2016-11-21T21:19:20Z

Reviewed 2 of 2 files at r3.
Review status: all files reviewed at latest revision, 16 unresolved discussions.

docs/concepts/index.md, line 10 at r1 (raw file):

Previously, kow3ns (Kenneth Owens) wrote…

> https://github.com/kow3ns/kubernetes.github.io/blob/7aa8c5d2e6253739a2da144d933b9daa1804ec36/_data/concepts.yml#L10-L13 > It is already there

Done.

Comments from Reviewable

enisoc · 2016-11-21T21:30:38Z

Review status: all files reviewed at latest revision, 10 unresolved discussions.

docs/concepts/controllers/statefulsets.md, line 90 at r1 (raw file):

Previously, kow3ns (Kenneth Owens) wrote…

> Done.

It turns out the behavior we want here only works with the "alpha" annotation. See https://github.com/kubernetes/kubernetes/issues/37239

docs/concepts/controllers/statefulsets.md, line 18 at r2 (raw file):

Previously, kow3ns (Kenneth Owens) wrote…

> Done.

You removed one too many *that*s.

docs/concepts/controllers/statefulsets.md, line 144 at r2 (raw file):

Previously, kow3ns (Kenneth Owens) wrote…

> I haven't found any direct documentation as to the difference between anything and default. I could make a guess based on what is in the documentation, but we should probably dig through the code for an answer.

It turns out the value you give is irrelevant. All that matters is the existence of the alpha annotation.

Comments from Reviewable

kow3ns · 2016-11-22T23:33:07Z

Review status: all files reviewed at latest revision, 10 unresolved discussions.

docs/concepts/controllers/statefulsets.md, line 90 at r1 (raw file):

Previously, enisoc (Anthony Yeh) wrote…

> It turns out the behavior we want here only works with the "alpha" annotation. See https://github.com/kubernetes/kubernetes/issues/37239

For the concept I'm getting rid of the annotation altogether. Its not really relevant here. I'm going to keep it as alpha for the tutorial.

Comments from Reviewable

Removes storage annotation

kow3ns · 2016-11-22T23:53:52Z

Review status: 2 of 3 files reviewed at latest revision, 10 unresolved discussions.

docs/concepts/controllers/statefulsets.md, line 90 at r1 (raw file):

Previously, kow3ns (Kenneth Owens) wrote…

> For the concept I'm getting rid of the annotation altogether. Its not really relevant here. I'm going to keep it as alpha for the tutorial.

Done.

docs/concepts/controllers/statefulsets.md, line 18 at r2 (raw file):

Previously, enisoc (Anthony Yeh) wrote…

> You removed one too many *that*s.

Done.

docs/concepts/controllers/statefulsets.md, line 144 at r2 (raw file):

Previously, enisoc (Anthony Yeh) wrote…

> It turns out the value you give is irrelevant. All that matters is the existence of the alpha annotation.

Done.

Comments from Reviewable

erictune

looks good. couple comment.

erictune · 2016-11-27T20:45:21Z

docs/concepts/controllers/statefulsets.md

+In the above, by stable, we mean persistent across Pod (re) schedulings.
+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.


"such as with Deployment (link to Deployment docs)".

erictune · 2016-11-27T20:49:32Z

docs/concepts/controllers/statefulsets.md

+* 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. 
+* 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.


Maybe just say: "Updating an existing Stateful Set is currently a manual process: the pod template cannot be updated.". Leave the explanation of how you might manually update for later.

erictune · 2016-11-27T20:51:17Z

docs/concepts/controllers/statefulsets.md

+* A [Headless Service](/docs/user-guide/services/#headless-services), named nginx, is used to control the network domain. 
+* The Stateful Set, named web, has a Spec that indicates that 3 replicas of the nginx container will be launched in unique Pods.
+* The volumeClaimTemplates, will provide stable storage using [Persistent Volumes](/docs/user-guide/volumes/) provisioned by a 
+ [Persistent Volume Provisioner](http://releases.k8s.io/{{page.githubbranch}}/examples/experimental/persistent-volume-provisioning/README.md).


You already linked to Persistent Volume Provisioner above. Not needed here?

enisoc · 2016-11-29T00:31:08Z

Review status: 2 of 3 files reviewed at latest revision, 14 unresolved discussions.

docs/concepts/controllers/statefulsets.md, line 153 at r4 (raw file):

* For a Stateful Set with N replicas, when Pods are being deployed, they are created sequentially, in order from {0..N-1}. 
* When Pods are being deleted, they are terminated in reverse order, from {N-1..0}.
* Before a scaling operation is applied to a Pod, all of its predecessors must be Running and Ready.

As discussed offline, this item is misleading as currently worded. The actual behavior is: Before any Pod is created, all existing Pods must be Running and Ready.

See: https://github.com/kubernetes/kubernetes/blob/1dfd64f4378ad9dd974bbfbef8e90127dce6aafe/pkg/controller/petset/pet.go#L128

Comments from Reviewable

Removes redundant hyperlinks Makes statement about updates limitation more terse

kow3ns · 2016-11-29T00:39:10Z

Reviewed 1 of 3 files at r1, 1 of 1 files at r4, 1 of 1 files at r5.
Review status: all files reviewed at latest revision, 14 unresolved discussions.

docs/concepts/controllers/statefulsets.md, line 36 at r4 (raw file):

Previously, erictune (Eric Tune) wrote…

> "such as with Deployment (link to Deployment docs)".

Done.

docs/concepts/controllers/statefulsets.md, line 44 at r4 (raw file):

Previously, erictune (Eric Tune) wrote…

> Maybe just say: "Updating an existing Stateful Set is currently a manual process: the pod template cannot be updated.". Leave the explanation of how you might manually update for later.

Done.

docs/concepts/controllers/statefulsets.md, line 52 at r4 (raw file):

Previously, erictune (Eric Tune) wrote…

> You already linked to Persistent Volume Provisioner above. Not needed here?

Done.

docs/concepts/controllers/statefulsets.md, line 153 at r4 (raw file):

Previously, enisoc (Anthony Yeh) wrote…

> As discussed offline, this item is misleading as currently worded. The actual behavior is: Before any Pod is created, all existing Pods must be Running and Ready. > > See: https://github.com/kubernetes/kubernetes/blob/1dfd64f4378ad9dd974bbfbef8e90127dce6aafe/pkg/controller/petset/pet.go#L128

This item is true. We will have to add an additional limitation with respect to potential deadlock due to petSyncers current implementation.

Comments from Reviewable

enisoc · 2016-11-29T02:12:30Z

Review status: all files reviewed at latest revision, 13 unresolved discussions.

docs/concepts/controllers/statefulsets.md, line 153 at r4 (raw file):

Previously, kow3ns (Kenneth Owens) wrote…

> This item is true. We will have to add an additional limitation with respect to potential deadlock due to petSyncers current implementation.

The item is technically true, but my point is that phrasing it in terms of "scaling" is misleading. The actual logic is in terms of "creation" at any time, regardless of whether any scaling is happening. The fact that this item is true for scaling is just a coincidence because at that time there happen to not be any Pods with ordinal greater than N yet.

Comments from Reviewable

StatefulSet and Persistent Volume becomes PersistentVolume)

kow3ns · 2016-12-01T19:40:14Z

Reviewed 3 of 3 files at r6.
Review status: all files reviewed at latest revision, 11 unresolved discussions.

Comments from Reviewable

devin-donnelly · 2016-12-01T22:56:25Z

This is solid; I have some writerly comments to be addressed.

Also, there is an "abstractions" directory under "concepts"; I'd like to nest "controllers" underneath there. This differentiates it from the "control-plane" stuff (which also has its own directory).

devin-donnelly · 2016-12-01T22:35:47Z

docs/concepts/controllers/statefulsets.md

+
+{% capture overview %}
+**StatefulSets are a beta feature in 1.5. This feature replaces the 
+Pet Sets feature from 1.4. Users of Pet Sets are referred to the 1.5 


Address the user directly.

"If you've been using PetSet in your cluster in version 1.4, see the Upgrade Guide for further information on how to upgrade existing Pet Sets to StatefulSets."

devin-donnelly · 2016-12-01T22:40:33Z

docs/concepts/controllers/statefulsets.md

+* Ordered, graceful deployment and scaling.
+* Ordered, graceful deletion and termination.
+
+In the above, by stable, we mean persistent across Pod (re) schedulings.


Avoid "we" constructs. Rephrase:

"Both the unique network identifiers and the persistent storage associated with a StatefulSet are "stable" in the sense that they are persistent across Pod scheduling or re-scheduling."

devin-donnelly · 2016-12-01T22:42:10Z

docs/concepts/controllers/statefulsets.md

+* Ordered, graceful deletion and termination.
+
+In the above, by stable, we mean persistent across Pod (re) schedulings.
+As it is generally easier to manage, if an application doesn't require any of 


"If an application doesn't require any stable identifiers or ordered deployment, deletion, or scaling, you should deploy your application with a controller that provides a set of stateless replicas. Such controllers, such as [Deployment] or [ReplicaSet], are generally easier to manage and may be better suited to your needs."

devin-donnelly · 2016-12-01T22:43:52Z

docs/concepts/controllers/statefulsets.md

+
+### Limitations
+* StatefulSet 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.


Avoid pronouns. "It" -> "StatefulSet".

Avoid passive voice. "It can be disabled" -> "You can disable StatefulSet through the --runtime-config option that you pass to the Kubernetes apiserver."

devin-donnelly · 2016-12-01T22:44:48Z

docs/concepts/controllers/statefulsets.md

+* StatefulSet 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 storage for a given Pod must either be provisioned by a [PersistentVolume 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 StatefulSet down will *not* delete the volumes associated with the StatefulSet. This is done to ensure safety first, your data is more valuable than an auto purge of all related StatefulSet resources. 


"This is done to ensure data safety, which is generally more valuable than an automatic purge of all related StatefulSet resources."

devin-donnelly · 2016-12-01T22:46:21Z

docs/concepts/controllers/statefulsets.md

+stable network identity, and stable storage. The identity sticks to the Pod, 
+regardless of which node it's (re) scheduled on.
+
+__Ordinal Index__


Is this a heading?

devin-donnelly · 2016-12-01T22:52:11Z

docs/concepts/controllers/statefulsets.md

+__Ordinal Index__
+
+For a StatefulSet with N replicas, each Pod in the StatefulSet will be 
+assigned an integer ordinal, in the range [0,N), that is unique over the Set. 


Trailing parenthesis should be a square bracket.

devin-donnelly · 2016-12-01T22:52:58Z

docs/concepts/controllers/statefulsets.md

+
+__Stable Network ID__
+
+The hostname of a Pod in a StatefulSet is derived from the name of the 


"Each Pod in a StatefulSet derives its hostname from the name of the StatefulSet and the ordinal of the Pod."

devin-donnelly · 2016-12-01T22:54:24Z

docs/concepts/controllers/statefulsets.md

+
+__Stable Storage__
+
+[PersistentVolumes](/docs/user-guide/volumes/), one for each Volume Claim Template, 


"Kubernetes creates one [PersistentVolume] for each Volume Claim Template, as specified in the StatefulSet's volumeClaimTemplates field."

devin-donnelly · 2016-12-01T22:55:06Z

docs/concepts/index.md

+* [Annotations](/docs/concepts/object-metadata/annotations/)
+
+#### Controllers
+* [StatefulSets](/docs/concepts/controllers/statefulsets/)


There is an "abstractions" directory inside concepts that I'd like "controllers" to be nested under.

kow3ns · 2016-12-02T21:10:01Z

Review status: all files reviewed at latest revision, 22 unresolved discussions.

docs/concepts/controllers/statefulsets.md, line 36 at r4 (raw file):

Previously, kow3ns (Kenneth Owens) wrote…

Done.

Done.

docs/concepts/controllers/statefulsets.md, line 109 at r6 (raw file):

Previously, devin-donnelly wrote…

Is this a heading?

Yes

docs/concepts/controllers/statefulsets.md, line 112 at r6 (raw file):

Previously, devin-donnelly wrote…

Trailing parenthesis should be a square bracket.

No it should not [ indicates that the interval includes 0
) indicates that N is not included

Comments from Reviewable

kow3ns · 2016-12-02T21:54:28Z

Reviewed 4 of 4 files at r7.
Review status: all files reviewed at latest revision, 22 unresolved discussions.

docs/concepts/index.md, line 12 at r6 (raw file):

Previously, devin-donnelly wrote…

There is an "abstractions" directory inside concepts that I'd like "controllers" to be nested under.

Done.

docs/concepts/controllers/statefulsets.md, line 14 at r6 (raw file):

Previously, devin-donnelly wrote…

PetSet as one word?

Done.

docs/concepts/controllers/statefulsets.md, line 33 at r6 (raw file):

Previously, devin-donnelly wrote…

Avoid "we" constructs. Rephrase:

"Both the unique network identifiers and the persistent storage associated with a StatefulSet are "stable" in the sense that they are persistent across Pod scheduling or re-scheduling."

Done.

docs/concepts/controllers/statefulsets.md, line 34 at r6 (raw file):

Previously, devin-donnelly wrote…

"If an application doesn't require any stable identifiers or ordered deployment, deletion, or scaling, you should deploy your application with a controller that provides a set of stateless replicas. Such controllers, such as [Deployment] or [ReplicaSet], are generally easier to manage and may be better suited to your needs."

Done.

docs/concepts/controllers/statefulsets.md, line 42 at r6 (raw file):

Previously, devin-donnelly wrote…

Avoid pronouns. "It" -> "StatefulSet".

Avoid passive voice. "It can be disabled" -> "You can disable StatefulSet through the --runtime-config option that you pass to the Kubernetes apiserver."

Done.

docs/concepts/controllers/statefulsets.md, line 44 at r6 (raw file):

Previously, devin-donnelly wrote…

"This is done to ensure data safety, which is generally more valuable than an automatic purge of all related StatefulSet resources."

Done.

docs/concepts/controllers/statefulsets.md, line 45 at r6 (raw file):

Previously, devin-donnelly wrote…

Address the user directly. "The user is responsible for this Service" -> "You must provide this service for your StatefulSet."

Done.

docs/concepts/controllers/statefulsets.md, line 116 at r6 (raw file):

Previously, devin-donnelly wrote…

"Each Pod in a StatefulSet derives its hostname from the name of the StatefulSet and the ordinal of the Pod."

Done.

docs/concepts/controllers/statefulsets.md, line 142 at r6 (raw file):

Previously, devin-donnelly wrote…

"Kubernetes creates one [PersistentVolume] for each Volume Claim Template, as specified in the StatefulSet's volumeClaimTemplates field."

Done.

Comments from Reviewable

devin-donnelly · 2016-12-02T23:01:35Z

Awesome, @kow3ns . Thanks. Merging now.

Kenneth Owens added 4 commits November 17, 2016 16:12

Initial commit of statefulsets concept.

41114fd

adds sclaing and deployment section. fixes spelling errors. changes all

f2e18d0

StatefulSet referneces to Stateful Set and all PetSet references to Pet Set

updates directory structure to add controllers directory

d6ea2b2

moves statefulset.md into controllers update _data/concepts.yml to show a TOC based on the above

completes move of statefulset to controllers

8f0e37b

shortens intro in favor of another Components section

googlebot added the cla: yes label Nov 18, 2016

kow3ns mentioned this pull request Nov 18, 2016

Stateful Sets concept #1715

Closed

k8s-github-robot assigned janetkuo Nov 18, 2016

foxish reviewed Nov 18, 2016

View reviewed changes

janetkuo added this to the 1.5 milestone Nov 18, 2016

foxish reviewed Nov 18, 2016

View reviewed changes

janetkuo reviewed Nov 18, 2016

View reviewed changes

foxish reviewed Nov 18, 2016

View reviewed changes

Kenneth Owens added 2 commits November 18, 2016 10:13

removes legacy claim about mutability of stateful set

26f0e6e

upgrades the version of storage class to beta

7aa8c5d

adds assignees clarifies stable storage description

Fixes typo in guarantees

094a51f

Removes deprecation from comment wrt PetSets Creates separate section in concepts/index.md for Controllers Fixes grammer "an integer" Removes claim about persistent storage being auto-deleted Clarifies stability Adds call out tick around attributes

k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label Nov 18, 2016

Fixes typo

6e65abe

idvoretskyi mentioned this pull request Nov 21, 2016

StatefulSets kubernetes/enhancements#137

Closed

23 tasks

Changes introduction wording

77dc8f9

Removes storage annotation

erictune reviewed Nov 27, 2016

View reviewed changes

Gives examples of Deployment and ReplicaSet as Stateful Set alternative

92f8d24

Removes redundant hyperlinks Makes statement about updates limitation more terse

Changes all API Objects to CamelCase (e.g Stateful Set becomes

349e41f

StatefulSet and Persistent Volume becomes PersistentVolume)

devin-donnelly added the Docs Review: Open Issues label Dec 1, 2016

devin-donnelly suggested changes Dec 1, 2016

View reviewed changes

enisoc mentioned this pull request Dec 2, 2016

Add replicated MySQL tutorial #1722

Merged

Kenneth Owens added 2 commits December 2, 2016 13:51

Address editorial comments

1bc1017

Moved statefulset concept to abstractions

2b35e21

devin-donnelly approved these changes Dec 2, 2016

View reviewed changes

devin-donnelly added Docs LGTM and removed Docs Review: Open Issues labels Dec 2, 2016

devin-donnelly merged commit 1ecb7b5 into kubernetes:release-1.5 Dec 2, 2016


		__Stable Network ID__

		The hostname of a Pod in a StatefulSet is derived from the name of the


		__Stable Storage__

		[PersistentVolumes](/docs/user-guide/volumes/), one for each Volume Claim Template,

SS concept #1719

SS concept #1719

Conversation

kow3ns commented Nov 18, 2016 • edited by thockin Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

janetkuo Nov 18, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

foxish Nov 18, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

enisoc commented Nov 18, 2016

kow3ns commented Nov 18, 2016

kow3ns commented Nov 18, 2016

kow3ns commented Nov 18, 2016

kow3ns commented Nov 18, 2016

enisoc commented Nov 18, 2016

kow3ns commented Nov 18, 2016

kow3ns commented Nov 18, 2016

kow3ns commented Nov 21, 2016

kow3ns commented Nov 21, 2016

enisoc commented Nov 21, 2016

kow3ns commented Nov 22, 2016

kow3ns commented Nov 22, 2016

erictune left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

enisoc commented Nov 29, 2016

kow3ns commented Nov 29, 2016

enisoc commented Nov 29, 2016

kow3ns commented Dec 1, 2016

devin-donnelly commented Dec 1, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kow3ns commented Dec 2, 2016

kow3ns commented Dec 2, 2016

devin-donnelly commented Dec 2, 2016

kow3ns commented Nov 18, 2016 •

edited by thockin

Loading

janetkuo Nov 18, 2016 •

edited

Loading

foxish Nov 18, 2016 •

edited

Loading