Merge pull request #44473 from sftim/20231222_revise_statefulset_tutorial

Revise StatefulSet tutorial updates advice

Author: k8s-ci-robot

content/en/docs/tutorials/stateful-application/basic-stateful-set.md

@@ -545,28 +545,25 @@ When exploring a Pod's [stable storage](#writing-to-stable-storage), we saw that
 
 ## Updating StatefulSets
 
-In Kubernetes 1.7 and later, the StatefulSet controller supports automated updates.  The
+The StatefulSet controller supports automated updates.  The
 strategy used is determined by the `spec.updateStrategy` field of the
-StatefulSet API Object. This feature can be used to upgrade the container
+StatefulSet API object. This feature can be used to upgrade the container
 images, resource requests and/or limits, labels, and annotations of the Pods in a
-StatefulSet. There are two valid update strategies, `RollingUpdate` and
-`OnDelete`.
+StatefulSet.
 
-`RollingUpdate` update strategy is the default for StatefulSets.
+There are two valid update strategies, `RollingUpdate` (the default) and
+`OnDelete`.
 
 ### RollingUpdate {#rolling-update}
 
 The `RollingUpdate` update strategy will update all Pods in a StatefulSet, in
 reverse ordinal order, while respecting the StatefulSet guarantees.
 
-Patch the `web` StatefulSet to apply the `RollingUpdate` update strategy:
+You can split updates to a StatefulSet that uses the `RollingUpdate` strategy
+into _partitions_, by specifying `.spec.updateStrategy.rollingUpdate.partition`.
+You'll practice that later in this tutorial.
 
-```shell
-kubectl patch statefulset web -p '{"spec":{"updateStrategy":{"type":"RollingUpdate"}}}'
-```
-```
-statefulset.apps/web patched
-```
+First, try a simple rolling update.
 
 In one terminal window, patch the `web` StatefulSet to change the container
 image again:
@@ -627,7 +624,7 @@ StatefulSet controller terminates each Pod, and waits for it to transition to Ru
 Ready prior to updating the next Pod. Note that, even though the StatefulSet
 controller will not proceed to update the next Pod until its ordinal successor
 is Running and Ready, it will restore any Pod that fails during the update to
-its current version.
+that Pod's existing version.
 
 Pods that have already received the update will be restored to the updated version,
 and Pods that have not yet received the update will be restored to the previous
@@ -655,21 +652,33 @@ the status of a rolling update to a StatefulSet
 
 #### Staging an update
 
-You can stage an update to a StatefulSet by using the `partition` parameter of
-the `RollingUpdate` update strategy. A staged update will keep all of the Pods
-in the StatefulSet at the current version while allowing mutations to the
-StatefulSet's `.spec.template`.
+You can split updates to a StatefulSet that uses the `RollingUpdate` strategy
+into _partitions_, by specifying `.spec.updateStrategy.rollingUpdate.partition`.
+
+For more context, you can read [Partitioned rolling updates](/docs/concepts/workloads/controllers/statefulset/#partitions)
+in the StatefulSet concept page.
+
+You can stage an update to a StatefulSet by using the `partition` field within
+`.spec.updateStrategy.rollingUpdate`.
+For this update, you will keep the existing Pods in the StatefulSet
+unchanged whilst you change the pod template for the StatefulSet.
+Then you - or, outside of a tutorial, some external automation - can
+trigger that prepared update.
 
-Patch the `web` StatefulSet to add a partition to the `updateStrategy` field:
+First, patch the `web` StatefulSet to add a partition to the `updateStrategy` field:
 
 ```shell
+# The value of "partition" determines which ordinals a change applies to
+# Make sure to use a number bigger than the last ordinal for the
+# StatefulSet
 kubectl patch statefulset web -p '{"spec":{"updateStrategy":{"type":"RollingUpdate","rollingUpdate":{"partition":3}}}}'
 ```
 ```
 statefulset.apps/web patched
 ```
 
-Patch the StatefulSet again to change the container's image:
+Patch the StatefulSet again to change the container image that this
+StatefulSet uses:
 
 ```shell
 kubectl patch statefulset web --type='json' -p='[{"op": "replace", "path": "/spec/template/spec/containers/0/image", "value":"registry.k8s.io/nginx-slim:0.7"}]'
@@ -687,7 +696,7 @@ kubectl delete pod web-2
 pod "web-2" deleted
 ```
 
-Wait for the Pod to be Running and Ready.
+Wait for the replacement `web-2` Pod to be Running and Ready:
 
 ```shell
 # End the watch when you see that web-2 is healthy
@@ -711,13 +720,16 @@ registry.k8s.io/nginx-slim:0.8
 ```
 
 Notice that, even though the update strategy is `RollingUpdate` the StatefulSet
-restored the Pod with its original container. This is because the
+restored the Pod with the original container image. This is because the
 ordinal of the Pod is less than the `partition` specified by the
 `updateStrategy`.
 
 #### Rolling out a canary
 
-You can roll out a canary to test a modification by decrementing the `partition`
+You're now going to try a [canary rollout](https://glossary.cncf.io/canary-deployment/)
+of that staged change.
+
+You can roll out a canary (to test the modified template) by decrementing the `partition`
 you specified [above](#staging-an-update).
 
 Patch the StatefulSet to decrement the partition:
@@ -731,7 +743,10 @@ kubectl patch statefulset web -p '{"spec":{"updateStrategy":{"type":"RollingUpda
 statefulset.apps/web patched
 ```
 
-Wait for `web-2` to be Running and Ready.
+The control plane triggers replacement for `web-2` (implemented by
+a graceful **delete** followed by creating a new Pod once the deletion
+is complete).
+Wait for the new `web-2` Pod to be Running and Ready.
 
 ```shell
 # This should already be running
@@ -863,18 +878,32 @@ continue the update process.
 
 ### OnDelete {#on-delete}
 
-The `OnDelete` update strategy implements the legacy (1.6 and prior) behavior,
-When you select this update strategy, the StatefulSet controller will not
-automatically update Pods when a modification is made to the StatefulSet's
-`.spec.template` field. This strategy can be selected by setting the
+You select this update strategy for a StatefulSet by setting the
 `.spec.template.updateStrategy.type` to `OnDelete`.
 
+Patch the `web` StatefulSet to use the `OnDelete` update strategy:
+
+```shell
+kubectl patch statefulset web -p '{"spec":{"updateStrategy":{"type":"OnDelete"}}}'
+```
+```
+statefulset.apps/web patched
+```
+
+When you select this update strategy, the StatefulSet controller does not
+automatically update Pods when a modification is made to the StatefulSet's
+`.spec.template` field. You need to manage the rollout yourself - either
+manually, or using separate automation.
 
 ## Deleting StatefulSets
 
-StatefulSet supports both Non-Cascading and Cascading deletion. In a
-Non-Cascading Delete, the StatefulSet's Pods are not deleted when the StatefulSet is deleted. In a Cascading Delete, both the StatefulSet and its Pods are
-deleted.
+StatefulSet supports both _non-cascading_ and _cascading_ deletion. In a
+non-cascading **delete**, the StatefulSet's Pods are not deleted when the
+StatefulSet is deleted. In a cascading **delete**, both the StatefulSet and
+its Pods are deleted.
+
+Read [Use Cascading Deletion in a Cluster](/docs/tasks/administer-cluster/use-cascading-deletion/)
+to learn about cascading deletion generally.
 
 ### Non-cascading delete
 
@@ -888,7 +917,7 @@ kubectl get pods --watch -l app=nginx
 Use [`kubectl delete`](/docs/reference/generated/kubectl/kubectl-commands/#delete) to delete the
 StatefulSet. Make sure to supply the `--cascade=orphan` parameter to the
 command. This parameter tells Kubernetes to only delete the StatefulSet, and to
-not delete any of its Pods.
+**not** delete any of its Pods.
 
 ```shell
 kubectl delete statefulset web --cascade=orphan
@@ -982,7 +1011,7 @@ with `replicas` equal to 2, once `web-0` had been recreated, and once
 `web-1` had been determined to already be Running and Ready, `web-2` was
 terminated.
 
-Let's take another look at the contents of the `index.html` file served by the
+Now take another look at the contents of the `index.html` file served by the
 Pods' webservers:
 
 ```shell
@@ -1051,7 +1080,7 @@ the Pod's successor to be completely terminated.
 
 {{< note >}}
 Although a cascading delete removes a StatefulSet together with its Pods,
-the cascade does not delete the headless Service associated with the StatefulSet.
+the cascade does **not** delete the headless Service associated with the StatefulSet.
 You must delete the `nginx` Service manually.
 {{< /note >}}
 
@@ -1114,14 +1143,11 @@ statefulset "web" deleted
 
 For some distributed systems, the StatefulSet ordering guarantees are
 unnecessary and/or undesirable. These systems require only uniqueness and
-identity. To address this, in Kubernetes 1.7, we introduced
-`.spec.podManagementPolicy` to the StatefulSet API Object.
-
-### OrderedReady Pod management
+identity.
 
-`OrderedReady` pod management is the default for StatefulSets. It tells the
-StatefulSet controller to respect the ordering guarantees demonstrated
-above.
+You can specify a Pod management policy to avoid this strict ordering;
+either [`OrderedReady`](/docs/concepts/workloads/controllers/statefulset/#orderedready-pod-management) (the default)
+or [`Parallel`](/docs/concepts/workloads/controllers/statefulset/#parallel-pod-management).
 
 ### Parallel Pod management
 
@@ -1170,7 +1196,8 @@ web-0     1/1       Running   0         10s
 web-1     1/1       Running   0         10s
 ```
 
-The StatefulSet controller launched both `web-0` and `web-1` at the same time.
+The StatefulSet controller launched both `web-0` and `web-1` at almost the
+same time.
 
 Keep the second terminal open, and, in another terminal window scale the
 StatefulSet: