Update statefulset concepts doc to use apps/v1beta2 APIs

kubernetes · Sep 13, 2017 · b4d3b49 · b4d3b49
1 parent 9a472c4
commit b4d3b49
Show file tree

Hide file tree

Showing 2 changed files with 31 additions and 19 deletions.
diff --git a/cn/docs/concepts/workloads/controllers/statefulset.md b/cn/docs/concepts/workloads/controllers/statefulset.md
@@ -10,10 +10,8 @@ title: StatefulSets
 ---
 
 {% capture overview %}
-**StatefulSets are a beta feature in 1.7. This feature replaces the
-PetSets feature from 1.4. Users of PetSets are referred to the 1.5
-[Upgrade Guide](/docs/tasks/manage-stateful-set/upgrade-pet-set-to-stateful-set/)
-for further information on how to upgrade existing PetSets to StatefulSets.**
+**StatefulSet is the workload API object used to manage stateful applications. 
+StatefulSets are beta in 1.8.**
 
 {% include templates/glossary/snippet.md term="statefulset" length="long" %}
 {% endcapture %}
@@ -42,7 +40,7 @@ provides a set of stateless replicas. Controllers such as
 
 * StatefulSet is a beta resource, not available in any Kubernetes release prior to 1.5.
 * As with all alpha/beta resources, you can disable StatefulSet 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/persistent-volume-provisioning/README.md) based on the requested `storage class`, or pre-provisioned by an admin.
+* The storage for a given Pod must either be provisioned by a [PersistentVolume Provisioner](https://github.com/kubernetes/examples/tree/{{page.githubbranch}}/staging/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 data safety, which is generally more valuable than an automatic purge of all related StatefulSet resources.
 * StatefulSets currently require a [Headless Service](/docs/concepts/services-networking/service/#headless-services) to be responsible for the network identity of the Pods. You are responsible for creating this Service.
 
@@ -51,8 +49,7 @@ The example below demonstrates the components of a StatefulSet.
 
 * A Headless Service, named nginx, is used to control the network domain.
 * The StatefulSet, 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 [PersistentVolumes](/docs/concepts/storage/volumes/) provisioned by a
- PersistentVolume Provisioner.
+* The volumeClaimTemplates will provide stable storage using [PersistentVolumes](/docs/concepts/storage/volumes/) provisioned by a PersistentVolume Provisioner.
 
 ```yaml
 apiVersion: v1
@@ -69,17 +66,20 @@ spec:
   selector:
     app: nginx
 ---
-apiVersion: apps/v1beta1
+apiVersion: apps/v1beta2
 kind: StatefulSet
 metadata:
   name: web
 spec:
+  selector:
+    matchLabels:
+      app: nginx # has to match .spec.template.metadata.labels
   serviceName: "nginx"
-  replicas: 3
+  replicas: 3 # by default is 1
   template:
     metadata:
       labels:
-        app: nginx
+        app: nginx # has to match .spec.selector.matchLabels
     spec:
       terminationGracePeriodSeconds: 10
       containers:
@@ -222,6 +222,12 @@ updates to its `.spec.template` will not be propagated to its Pods.
 In most cases you will not need to use a partition, but they are useful if you want to stage an
 update, roll out a canary, or perform a phased roll out.
 
+## Selectors
+
+Same as other controllers, the StatefulSet utilizes selectors to identify pods that it should manage. For a pod to be managed by a StatefulSet, the pod needs to have labels matching the StatefulSet's selectors. However, the StatefulSet does not keep track whether a pod is created by it or another controller. The pods will persist when the StatefulSet is deleted (except when the user performs a [cascading deletion](https://kubernetes.io/docs/concepts/workloads/controllers/garbage-collection/)).
+
+In Kubernetes 1.8 and later, there will be no selector defaulting. `.spec.selector` field will not be defaulted to match `.spec.template.metadata.labels` field during StatefulSet creation. The user has to explicitly set the selectors to match the template labels.
+
 {% endcapture %}
 {% capture whatsnext %}
 

diff --git a/docs/concepts/workloads/controllers/statefulset.md b/docs/concepts/workloads/controllers/statefulset.md
@@ -10,10 +10,8 @@ title: StatefulSets
 ---
 
 {% capture overview %}
-**StatefulSets are a beta feature in 1.7. This feature replaces the
-PetSets feature from 1.4. Users of PetSets are referred to the 1.5
-[Upgrade Guide](/docs/tasks/manage-stateful-set/upgrade-pet-set-to-stateful-set/)
-for further information on how to upgrade existing PetSets to StatefulSets.**
+**StatefulSet is the workload API object used to manage stateful applications. 
+StatefulSets are beta in 1.8.**
 
 {% include templates/glossary/snippet.md term="statefulset" length="long" %}
 {% endcapture %}
@@ -51,8 +49,7 @@ The example below demonstrates the components of a StatefulSet.
 
 * A Headless Service, named nginx, is used to control the network domain.
 * The StatefulSet, 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 [PersistentVolumes](/docs/concepts/storage/volumes/) provisioned by a
- PersistentVolume Provisioner.
+* The volumeClaimTemplates will provide stable storage using [PersistentVolumes](/docs/concepts/storage/volumes/) provisioned by a PersistentVolume Provisioner.
 
 ```yaml
 apiVersion: v1
@@ -69,17 +66,20 @@ spec:
   selector:
     app: nginx
 ---
-apiVersion: apps/v1beta1
+apiVersion: apps/v1beta2
 kind: StatefulSet
 metadata:
   name: web
 spec:
+  selector:
+    matchLabels:
+      app: nginx # has to match .spec.template.metadata.labels
   serviceName: "nginx"
-  replicas: 3
+  replicas: 3 # by default is 1
   template:
     metadata:
       labels:
-        app: nginx
+        app: nginx # has to match .spec.selector.matchLabels
     spec:
       terminationGracePeriodSeconds: 10
       containers:
@@ -222,6 +222,12 @@ updates to its `.spec.template` will not be propagated to its Pods.
 In most cases you will not need to use a partition, but they are useful if you want to stage an
 update, roll out a canary, or perform a phased roll out.
 
+## Selectors
+
+Same as other controllers, the StatefulSet utilizes selectors to identify pods that it should manage. For a pod to be managed by a StatefulSet, the pod needs to have labels matching the StatefulSet's selectors. However, the StatefulSet does not keep track whether a pod is created by it or another controller. The pods will persist when the StatefulSet is deleted (except when the user performs a [cascading deletion](https://kubernetes.io/docs/concepts/workloads/controllers/garbage-collection/)).
+
+In Kubernetes 1.8 and later, there will be no selector defaulting. `.spec.selector` field will not be defaulted to match `.spec.template.metadata.labels` field during StatefulSet creation. The user has to explicitly set the selectors to match the template labels.
+
 {% endcapture %}
 {% capture whatsnext %}