From 48ac1e67043320a84b29a37e772e27147075b702 Mon Sep 17 00:00:00 2001 From: Qiming Teng Date: Mon, 15 Jan 2018 13:59:16 +0800 Subject: [PATCH] Drop contents related to PetSet PetSet is a *very* old term that dates back to v1.4. We should not continue evangelize such a concept where there is no trace in code base today. Closes: #6484 --- _data/glossary/statefulset.yml | 2 - _redirects | 6 - docs/concepts/workloads/pods/pod.md | 10 +- .../upgrade-pet-set-to-stateful-set.md | 178 ------------------ 4 files changed, 7 insertions(+), 189 deletions(-) delete mode 100644 docs/tasks/run-application/upgrade-pet-set-to-stateful-set.md diff --git a/_data/glossary/statefulset.yml b/_data/glossary/statefulset.yml index 9b2d6c44fb..4fdbd5ce12 100644 --- a/_data/glossary/statefulset.yml +++ b/_data/glossary/statefulset.yml @@ -1,8 +1,6 @@ id: statefulset name: StatefulSet full-link: /docs/concepts/workloads/controllers/statefulset/ -aka: -- PetSet related: - deployment - pod diff --git a/_redirects b/_redirects index a3fc1cd2f4..dd7cf95317 100644 --- a/_redirects +++ b/_redirects @@ -7,7 +7,6 @@ /api-ref/ https://github.com/kubernetes/kubernetes/milestones/ 301 /concepts/containers/container-lifecycle-hooks/ /docs/concepts/containers/container-lifecycle-hooks/ 301 /docs/ /docs/home/ 301 -/docs/abstractions/controllers/petset/ /docs/concepts/workloads/controllers/statefulset/ 301 /docs/admin/ /docs/concepts/cluster-administration/cluster-administration-overview/ 301 /docs/admin/add-ons/ /docs/concepts/cluster-administration/addons/ 301 @@ -81,7 +80,6 @@ /docs/api-reference/v1/operations/ /docs/api-reference/v1.9/ 301 /docs/concepts/abstractions/controllers/garbage-collection/ /docs/concepts/workloads/controllers/garbage-collection/ 301 -/docs/concepts/abstractions/controllers/petsets/ /docs/concepts/workloads/controllers/statefulset/ 301 /docs/concepts/abstractions/controllers/statefulsets/ /docs/concepts/workloads/controllers/statefulset/ 301 /docs/concepts/abstractions/init-containers/ /docs/concepts/workloads/pods/init-containers/ 301 /docs/concepts/abstractions/overview/ /docs/concepts/overview/working-with-objects/kubernetes-objects/ 301 @@ -124,8 +122,6 @@ /docs/concepts/workloads/controllers/deployment/docs/concepts/workloads/pods/pod/ /docs/concepts/workloads/pods/pod/ 301 /docs/concepts/workloads/controllers/deployment.md /docs/concepts/workloads/controllers/deployment/ 301 /docs/concepts/workloads/controllers/job/ /docs/concepts/workloads/controllers/jobs-run-to-completion/ 301 -/docs/concepts/workloads/controllers/petset/ /docs/concepts/workloads/controllers/statefulset/ 301 -/docs/concepts/workloads/controllers/petsets/ /docs/concepts/workloads/controllers/statefulset/ 301 /docs/concepts/workloads/controllers/statefulsets/ /docs/concepts/workloads/controllers/statefulset/ 301 /docs/concepts/workloads/controllers/statefulset.md /docs/concepts/workloads/controllers/statefulset/ 301 /docs/concepts/workloads/pods/init-containers/Kubernetes/ /docs/concepts/workloads/pods/init-containers/ 301 @@ -368,8 +364,6 @@ /docs/user-guide/persistent-volumes/index /docs/concepts/storage/persistent-volumes/ 301 /docs/user-guide/persistent-volumes/index.md /docs/concepts/storage/persistent-volumes/ 301 /docs/user-guide/persistent-volumes/walkthrough/ /docs/tasks/configure-pod-container/configure-persistent-volume-storage/ 301 -/docs/user-guide/petset/ /docs/concepts/workloads/controllers/statefulset/ 301 -/docs/user-guide/petset/bootstrapping/ /docs/concepts/workloads/controllers/statefulset/ 301 /docs/user-guide/pod-preset/ /docs/tasks/inject-data-application/podpreset/ 301 /docs/user-guide/pod-security-policy/ /docs/concepts/policy/pod-security-policy/ 301 /docs/user-guide/pod-states/ /docs/concepts/workloads/pods/pod-lifecycle/ 301 diff --git a/docs/concepts/workloads/pods/pod.md b/docs/concepts/workloads/pods/pod.md index c07608e601..f7d94ab780 100644 --- a/docs/concepts/workloads/pods/pod.md +++ b/docs/concepts/workloads/pods/pod.md @@ -139,7 +139,13 @@ simplified management. Pods aren't intended to be treated as durable entities. They won't survive scheduling failures, node failures, or other evictions, such as due to lack of resources, or in the case of node maintenance. -In general, users shouldn't need to create pods directly. They should almost always use controllers (e.g., [Deployments](/docs/concepts/workloads/controllers/deployment/)), even for singletons. Controllers provide self-healing with a cluster scope, as well as replication and rollout management. +In general, users shouldn't need to create pods directly. They should almost +always use controllers even for singletons, for example, +[Deployments](/docs/concepts/workloads/controllers/deployment/)). +Controllers provide self-healing with a cluster scope, as well as replication +and rollout management. +Controllers like [StatefulSet](/docs/concepts/workloads/controllers/statefulset.md) +can also provide support to stateful pods. The use of collective APIs as the primary user-facing primitive is relatively common among cluster scheduling systems, including [Borg](https://research.google.com/pubs/pub43438.html), [Marathon](https://mesosphere.github.io/marathon/docs/rest-api.html), [Aurora](http://aurora.apache.org/documentation/latest/reference/configuration/#job-schema), and [Tupperware](http://www.slideshare.net/Docker/aravindnarayanan-facebook140613153626phpapp02-37588997). @@ -152,8 +158,6 @@ Pod is exposed as a primitive in order to facilitate: * clean composition of Kubelet-level functionality with cluster-level functionality — Kubelet is effectively the "pod controller" * high-availability applications, which will expect pods to be replaced in advance of their termination and certainly in advance of deletion, such as in the case of planned evictions, image prefetching, or live pod migration [#3949](http://issue.k8s.io/3949) -There is new first-class support for stateful pods with the [StatefulSet](/docs/concepts/workloads/controllers/statefulset.md) controller (currently in beta). The feature was alpha in 1.4 and was called PetSet. For prior versions of Kubernetes, best practice for having stateful pods is to create a replication controller with `replicas` equal to `1` and a corresponding service, see [this MySQL deployment example](/docs/tutorials/stateful-application/run-stateful-application/). - ## Termination of Pods Because pods represent running processes on nodes in the cluster, it is important to allow those processes to gracefully terminate when they are no longer needed (vs being violently killed with a KILL signal and having no chance to clean up). Users should be able to request deletion and know when processes terminate, but also be able to ensure that deletes eventually complete. When a user requests deletion of a pod the system records the intended grace period before the pod is allowed to be forcefully killed, and a TERM signal is sent to the main process in each container. Once the grace period has expired the KILL signal is sent to those processes and the pod is then deleted from the API server. If the Kubelet or the container manager is restarted while waiting for processes to terminate, the termination will be retried with the full grace period. diff --git a/docs/tasks/run-application/upgrade-pet-set-to-stateful-set.md b/docs/tasks/run-application/upgrade-pet-set-to-stateful-set.md deleted file mode 100644 index 4b442ad750..0000000000 --- a/docs/tasks/run-application/upgrade-pet-set-to-stateful-set.md +++ /dev/null @@ -1,178 +0,0 @@ ---- -approvers: -- bprashanth -- enisoc -- erictune -- foxish -- janetkuo -- kow3ns -- smarterclayton -title: Upgrade from PetSets to StatefulSets ---- - -{% 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 `true` in 1.5 through 1.7. - The annotation is completely ignored in 1.8 and above, which always behave as if it were `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 or have it set to `false`, - be aware that StatefulSet operations might resume after the upgrade. - - If you are upgrading to 1.6 or 1.7, you can set the annotation explicitly to `false` to maintain - the paused behavior. - If you are upgrading to 1.8 or above, there's no longer any debug annotation to pause StatefulSets. - -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/tasks/kubectl/install/). - -### 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. - -You should be running Node version >= 1.1.0 to run StatefulSets safely. Older versions do not support features which allow the StatefulSet to guarantee that at any time, there is **at most** one Pod with a given identity running in a cluster. - -{% endcapture %} - -{% capture whatsnext %} - -Learn more about [scaling a StatefulSet](/docs/tasks/manage-stateful-set/scale-stateful-set/). - -{% endcapture %} - -{% include templates/task.md %}