Reduce heading levels by 1.

2017-01-18 10:18:37 -08:00
parent 0f6b992771
commit 02d17ade5f
40 changed files with 178 additions and 187 deletions
@@ -26,7 +26,7 @@ This task shows you how to debug a StatefulSet.

 {% capture steps %}

-### Debugging a StatefulSet
+## Debugging a StatefulSet

 In order to list all the pods which belong to a StatefulSet, which have a label `app=myapp` set on them, you can use the following: 

@@ -44,7 +44,7 @@ kubectl annotate pods <pod-name> pod.alpha.kubernetes.io/initialized="false" --o

 When the annotation is set to `"false"`, the StatefulSet will not respond to its Pods becoming unhealthy or unavailable. It will not create replacement Pods till the annotation is removed or set to `"true"` on each StatefulSet Pod. 

-#### Step-wise Initialization
+### Step-wise Initialization

 You can also use the same annotation to debug race conditions during bootstrapping of the StatefulSet by setting the `pod.alpha.kubernetes.io/initialized` annotation to `"false"` in the `.spec.template.metadata.annotations` field of the StatefulSet prior to creating it. 

@@ -21,13 +21,13 @@ This page shows how to delete Pods which are part of a stateful set, and explain
 {% capture steps %}


-### StatefulSet considerations
+## StatefulSet considerations

 In normal operation of a StatefulSet, there is **never** a need to force delete a StatefulSet Pod. The StatefulSet controller is responsible for creating, scaling and deleting members of the StatefulSet. It tries to ensure that the specified number of Pods from ordinal 0 through N-1 are alive and ready. StatefulSet ensures that, at any time, there is at most one Pod with a given identity running in a cluster. This is referred to as *at most one* semantics provided by a StatefulSet.

 Manual force deletion should be undertaken with caution, as it has the potential to violate the at most one semantics inherent to StatefulSet. StatefulSets may be used to run distributed and clustered applications which have a need for a stable network identity and stable storage. These applications often have configuration which relies on an ensemble of a fixed number of members with fixed identities. Having multiple members with the same identity can be disastrous and may lead to data loss (e.g. split brain scenario in quorum-based systems). 

-### Deleting Pods
+## Deleting Pods

 You can perform a graceful pod deletion with the following command:

@@ -46,7 +46,7 @@ The recommended best practice is to use the first or second approach. If a Node

 Normally, the system completes the deletion once the Pod is no longer running on a Node, or the Node is deleted by an administrator. You may override this by force deleting the Pod.

-#### Force Deletion
+### Force Deletion

 Force deletions **do not** wait for confirmation from the kubelet that the Pod has been terminated. Irrespective of whether a force deletion is successful in killing a Pod, it will immediately free up the name from the apiserver. This would let the StatefulSet controller create a replacement Pod with that same identity; this can lead to the duplication of a still-running Pod, and if said Pod can still communicate with the other members of the StatefulSet, will violate the at most one semantics that StatefulSet is designed to guarantee.

@@ -22,7 +22,7 @@ This task shows you how to delete a StatefulSet.

 {% capture steps %}

-### Deleting a StatefulSet
+## Deleting a StatefulSet

 You can delete a StatefulSet in the same way you delete other resources in Kubernetes: use the `kubectl delete` command, and specify the StatefulSet either by file or by name.

@@ -52,13 +52,13 @@ By passing `--cascade=false` to `kubectl delete`, the Pods managed by the Statef
 kubectl delete pods -l app=myapp
 ```

-#### Persistent Volumes
+### Persistent Volumes

 Deleting the Pods in a StatefulSet will not delete the associated volumes. This is to ensure that you have the chance to copy data off the volume before deleting it. Deleting the PVC after the pods have left the [terminating state](/docs/user-guide/pods/index#termination-of-pods) might trigger deletion of the backing Persistent Volumes depending on the storage class and reclaim policy. You should never assume ability to access a volume after claim deletion.

 **Note: Use caution when deleting a PVC, as it may lead to data loss.**

-#### Complete deletion of a StatefulSet
+### Complete deletion of a StatefulSet

 To simply delete everything in a StatefulSet, including the associated pods, you can run a series of commands similar to the following:

@@ -72,7 +72,7 @@ kubectl delete pvc -l app=myapp

 In the example above, the Pods have the label `app=myapp`; substitute your own label as appropriate.

-#### Force deletion of StatefulSet pods
+### Force deletion of StatefulSet pods

 If you find that some pods in your StatefulSet are stuck in the 'Terminating' or 'Unknown' states for an extended period of time, you may need to manually intervene to forcefully delete the pods from the apiserver. This is a potentially dangerous task. Refer to [Deleting StatefulSet Pods](/docs/tasks/manage-stateful-set/delete-pods/) for details.

@@ -25,13 +25,13 @@ This page shows how to scale a StatefulSet.

 {% capture steps %}

-### Use `kubectl` to scale StatefulSets
+## Use `kubectl` to scale StatefulSets

 Make sure you have `kubectl` upgraded to Kubernetes version 1.5 or later before
 continuing. If you're unsure, run `kubectl version` and check `Client Version`
 for which kubectl you're using.

-#### `kubectl scale`
+### `kubectl scale`

 First, find the StatefulSet you want to scale. Remember, you need to first understand if you can scale it or not. 

@@ -45,7 +45,7 @@ Change the number of replicas of your StatefulSet:
 kubectl scale statefulsets <stateful-set-name> --replicas=<new-replicas>
 ```

-#### Alternative: `kubectl apply` / `kubectl edit` / `kubectl patch`
+### Alternative: `kubectl apply` / `kubectl edit` / `kubectl patch`

 Alternatively, you can do [in-place updates](/docs/user-guide/managing-deployments/#in-place-updates-of-resources) on your StatefulSets. 

@@ -68,9 +68,9 @@ Or use `kubectl patch`:
 kubectl patch statefulsets <stateful-set-name> -p '{"spec":{"replicas":<new-replicas>}}'
 ```

-### Troubleshooting
+## Troubleshooting

-#### Scaling down doesn't not work right
+### Scaling down doesn't not work right

 You cannot scale down a StatefulSet when any of the stateful Pods it manages is unhealthy. Scaling down only takes place
 after those stateful Pods become running and ready. 
@@ -23,7 +23,7 @@ This page shows how to upgrade from PetSets (Kubernetes version 1.3 or 1.4) to *

 {% capture steps %}

-### Differences between alpha PetSets and beta StatefulSets
+## 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:
@@ -33,13 +33,13 @@ Here are some notable changes:
 * **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
+## 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 
+### Find all PetSets and their manifests 

 First, find all existing PetSets in your cluster:

@@ -60,7 +60,7 @@ Here's an example command for you to save all existing PetSets as one file.
 kubectl get petsets --all-namespaces -o yaml > all-petsets.yaml
 ```

-#### Prepare StatefulSet manifests 
+### Prepare StatefulSet manifests 

 Now, for every PetSet manifest you have, prepare a corresponding StatefulSet manifest: 

@@ -71,7 +71,7 @@ Now, for every PetSet manifest you have, prepare a corresponding StatefulSet man
 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
+### 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. 
@@ -103,18 +103,18 @@ 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
+### 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

 Upgrade `kubectl` to Kubernetes version 1.5 or later, following [the steps for installing and setting up 
 kubectl](/docs/user-guide/prereqs/).

-#### Create StatefulSets
+### Create StatefulSets

 Make sure you have both master and `kubectl` upgraded to Kubernetes version 1.5
 or later before continuing:
@@ -147,7 +147,7 @@ newly-upgraded cluster:
 kubectl get statefulsets --all-namespaces
 ```

-#### Upgrade nodes to Kubernetes version 1.5 or later (optional)
+### 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