diff --git a/_data/tasks.yml b/_data/tasks.yml index 9898fae32f..1dc775ef73 100644 --- a/_data/tasks.yml +++ b/_data/tasks.yml @@ -31,4 +31,7 @@ toc: section: - 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/ diff --git a/docs/tasks/index.md b/docs/tasks/index.md index b71057e640..486d8f4af2 100644 --- a/docs/tasks/index.md +++ b/docs/tasks/index.md @@ -27,6 +27,10 @@ single thing, typically by giving a short sequence of steps. * [Assigning Pods to Nodes](/docs/tasks/administer-cluster/assign-pods-nodes/) +#### 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 diff --git a/docs/tasks/manage-stateful-set/upgrade-pet-set-to-stateful-set.md b/docs/tasks/manage-stateful-set/upgrade-pet-set-to-stateful-set.md new file mode 100644 index 0000000000..7dd8c84ff2 --- /dev/null +++ b/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 should only contain PetSets that you want to delete, but not any other resources +kubectl delete -f --cascade=false +``` + +Alternatively, delete them by specifying resource names: + +```shell +# Alternatively, delete them by name and namespace without cascading +kubectl delete petsets -n= --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 +``` + +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 %}