From 086bc829ad77d00e364c4f7b39d6d69313f958aa Mon Sep 17 00:00:00 2001
From: Jun Xiang Tee <juntee@google.com>
Date: Mon, 11 Sep 2017 18:48:47 -0700
Subject: [PATCH] Update statefulset concepts doc to use apps/v1beta2 APIs

---
 .../workloads/controllers/statefulset.md      | 24 +++++++++++--------
 1 file changed, 14 insertions(+), 10 deletions(-)

diff --git a/docs/concepts/workloads/controllers/statefulset.md b/docs/concepts/workloads/controllers/statefulset.md
index 52168247c7292..c43f3d415d890 100644
--- a/docs/concepts/workloads/controllers/statefulset.md
+++ b/docs/concepts/workloads/controllers/statefulset.md
@@ -10,10 +10,6 @@ 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.**
 
 {% include templates/glossary/snippet.md term="statefulset" length="long" %}
 {% endcapture %}
@@ -40,7 +36,7 @@ provides a set of stateless replicas. Controllers such as
 
 ## Limitations
 
-* StatefulSet is a beta resource, not available in any Kubernetes release prior to 1.5.
+* StatefulSet (previously known as PetSet) 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](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.
@@ -51,8 +47,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 +64,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 +220,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 %}