Add Task: upgrading from PetSet to StatefulSet

_data/tasks.yml

@@ -32,3 +32,6 @@ toc:
   - title: Assigning Pods to Nodes
     path: /docs/tasks/administer-cluster/assign-pods-nodes/
 - title: Managing Stateful Applications
+  section:
+  - title: Upgrading from PetSets to StatefulSets
+    path: /docs/tasks/manage-stateful-set/upgrade-pet-set-to-stateful-set/

docs/tasks/index.md

@@ -29,6 +29,8 @@ single thing, typically by giving a short sequence of steps.
 
 #### Managing Stateful Applications
 
+* [Upgrading from PetSets to StatefulSets](/docs/tasks/manage-stateful-set/upgrade-pet-set-to-stateful-set/)
+
 ### What's next
 
 If you would like to write a task page, see

docs/tasks/manage-stateful-set/upgrade-pet-set-to-stateful-set.md

@@ -0,0 +1,163 @@
+---
+assignees:
+- bprashanth
+- enisoc
+- erictune
+- foxish
+- janetkuo
+- kow3ns
+- smarterclayton
+
+---
+
+{% capture overview %}
+This page shows how to upgrade from PetSets (Kubernetes version 1.3 or 1.4) to *StatefulSets* (Kubernetes version 1.5 or later).
+{% endcapture %}
+
+{% capture prerequisites %}
+
+* If you don't have PetSets in your current cluster, or you don't plan to upgrade
+  your master to Kubernetes 1.5 or later, you can skip this task. 
+
+{% endcapture %}
+
+{% capture steps %}
+
+### Differences between alpha PetSets and beta StatefulSets
+
+PetSet was introduced as an alpha resource in Kubernetes release 1.3, and was renamed to StatefulSet as a beta resource in 1.5. 
+Here are some notable changes:
+
+* **StatefulSet is the new PetSet**: PetSet is no longer available in Kubernetes release 1.5 or later. It becomes beta StatefulSet. To understand why the name was changed, see this [discussion thread](https://github.com/kubernetes/kubernetes/issues/27430).
+* **StatefulSet guards against split brain**: StatefulSets guarantee at most one Pod for a given ordinal index can be running anywhere in a cluster, to guard against split brain scenarios with distributed applications. *TODO: Link to doc about fencing.*
+* **Flipped debug annotation behavior**: The default value of the debug annotation (`pod.alpha.kubernetes.io/initialized`) is now `true`. The absence of this annotation will pause PetSet operations, but will NOT pause StatefulSet operations. In most cases, you no longer need this annotation in your StatefulSet manifests. 
+
+
+### Upgrading from PetSets to StatefulSets
+
+Note that these steps need to be done in the specified order. You **should
+NOT upgrade your Kubernetes master, nodes, or `kubectl` to Kubernetes version
+1.5 or later**, until told to do so.
+
+#### Find all PetSets and their manifests 
+
+First, find all existing PetSets in your cluster:
+
+```shell
+kubectl get petsets --all-namespaces
+```
+
+If you don't find any existing PetSets, you can safely upgrade your cluster to
+Kubernetes version 1.5 or later.
+
+If you find existing PetSets and you have all their manifests at hand, you can continue to the next step to prepare StatefulSet manifests. 
+
+Otherwise, you need to save their manifests so that you can recreate them as StatefulSets later. 
+Here's an example command for you to save all existing PetSets as one file. 
+
+```shell
+# Save all existing PetSets in all namespaces into a single file. Only needed when you don't have their manifests at hand. 
+kubectl get petsets --all-namespaces -o yaml > all-petsets.yaml
+```
+
+#### Prepare StatefulSet manifests 
+
+Now, for every PetSet manifest you have, prepare a corresponding StatefulSet manifest: 
+
+1. Change `apiVersion` from `apps/v1alpha1` to `apps/v1beta1`.
+2. Change `kind` from `PetSet` to `StatefulSet`.
+3. If you have the debug hook annotation `pod.alpha.kubernetes.io/initialized` set to `true`, you can remove it because it's redundant. If you don't have this annotation, you should add one, with the value set to `false`, to pause StatefulSets operations.
+
+It's recommended that you keep both PetSet manifests and StatefulSet manifests, so that you can safely roll back and recreate your PetSets, 
+if you decide not to upgrade your cluster. 
+
+#### Delete all PetSets without cascading
+
+If you find existing PetSets in your cluster in the previous step, you need to delete all PetSets *without cascading*. You can do this from `kubectl` with `--cascade=false`. 
+Note that if the flag isn't set, **cascading deletion will be performed by default**, and all Pods managed by your PetSets will be gone. 
+
+Delete those PetSets by specifying file names. This only works when
+the files contain only PetSets, but not other resources such as Services:
+
+```shell
+# Delete all existing PetSets without cascading 
+# Note that <pet-set-file> should only contain PetSets that you want to delete, but not any other resources
+kubectl delete -f <pet-set-file> --cascade=false
+```
+
+Alternatively, delete them by specifying resource names: 
+
+```shell
+# Alternatively, delete them by name and namespace without cascading
+kubectl delete petsets <pet-set-name> -n=<pet-set-namespace> --cascade=false
+```
+
+Make sure you've deleted all PetSets in the system:
+
+```shell
+# Get all PetSets again to make sure you deleted them all 
+# This should return nothing
+kubectl get petsets --all-namespaces
+```
+
+At this moment, you've deleted all PetSets in your cluster, but not their Pods, Persistent Volumes, or Persistent Volume Claims. 
+However, since the Pods are not managed by PetSets anymore, they will be vulnerable to node failures until you finish the master upgrade and recreate StatefulSets.
+
+#### Upgrade your master to Kubernetes version 1.5 or later
+
+Now, you can [upgrade your Kubernetes master](/docs/admin/cluster-management/#upgrading-a-cluster) to Kubernetes version 1.5 or later.
+Note that **you should NOT upgrade Nodes at this time**, because the Pods
+(that were once managed by PetSets) are now vulnerable to node failures. 
+
+#### Upgrade kubectl to Kubernetes version 1.5 or later
+
+Upgrade `kubectl` to Kubernetes version 1.5 or later, following [the steps for installing and setting up 
+kubectl](/docs/user-guide/prereqs/).
+
+#### Create StatefulSets
+
+Make sure you have both master and `kubectl` upgraded to Kubernetes version 1.5
+or later before continuing:
+
+```shell
+kubectl version
+```
+
+The output is similar to this:
+
+```shell
+Client Version: version.Info{Major:"1", Minor:"5", GitVersion:"v1.5.0", GitCommit:"0776eab45fe28f02bbeac0f05ae1a203051a21eb", GitTreeState:"clean", BuildDate:"2016-11-24T22:35:03Z", GoVersion:"go1.7.3", Compiler:"gc", Platform:"linux/amd64"}
+Server Version: version.Info{Major:"1", Minor:"5", GitVersion:"v1.5.0", GitCommit:"0776eab45fe28f02bbeac0f05ae1a203051a21eb", GitTreeState:"clean", BuildDate:"2016-11-24T22:30:23Z", GoVersion:"go1.7.3", Compiler:"gc", Platform:"linux/amd64"}
+```
+
+If both `Client Version` (`kubectl` version) and `Server Version` (master
+version) are 1.5 or later, you are good to go.
+
+Create StatefulSets to adopt the Pods belonging to the deleted PetSets with the
+StatefulSet manifests generated in the previous step:
+
+```shell
+kubectl create -f <stateful-set-file>
+```
+
+Make sure all StatefulSets are created and running as expected in the
+newly-upgraded cluster:
+
+```shell
+kubectl get statefulsets --all-namespaces
+```
+
+#### Upgrade nodes to Kubernetes version 1.5 or later (optional)
+
+You can now [upgrade Kubernetes nodes](/docs/admin/cluster-management/#upgrading-a-cluster)
+to Kubernetes version 1.5 or later. This step is optional, but needs to be done after all StatefulSets
+are created to adopt PetSets' Pods.
+
+
+{% endcapture %}
+
+{% capture whatsnext %}
+Learn more about debugging a StatefulSet. *TODO: Link to the task for debugging a StatefulSet.*
+{% endcapture %}
+
+{% include templates/task.md %}