Skip to content

Latest commit

 

History

History
163 lines (111 loc) · 6.71 KB

upgrade-pet-set-to-stateful-set.md

File metadata and controls

163 lines (111 loc) · 6.71 KB
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 know why the name is changed, see this discussion thread.
  • 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 operated 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:

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.

# 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 with the following steps:

  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:

# 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:

# 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:

# 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 master to Kubernetes version 1.5 or later

Now, you can upgrade your Kubernetes master 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.

Create StatefulSets

Make sure you have both master and kubectl upgraded to Kubernetes version 1.5 or later before continuing:

kubectl version

The output is similar to this:

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:

kubectl create -f <stateful-set-file>

Make sure all StatefulSets are created and running as expected in the newly-upgraded cluster:

kubectl get statefulsets --all-namespaces

Upgrade nodes to Kubernetes version 1.5 or later (optional)

You can now upgrade Kubernetes nodes 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 %}