Merge pull request #29193 from sftim/20210802_improve_statefulset_minreadyseconds_docs

Improve StatefulSet .minReadySeconds docs

Author: k8s-ci-robot

content/en/docs/concepts/workloads/controllers/statefulset.md

@@ -228,39 +228,33 @@ and Ready or completely terminated prior to launching or terminating another
 Pod. This option only affects the behavior for scaling operations. Updates are not
 affected.
 
-#### Minimum Ready Seconds
 
-{{< feature-state for_k8s_version="v1.22" state="alpha" >}}
-
-`.spec.minReadySeconds` is an optional field that specifies the minimum number of seconds for which a newly
-created Pod should be ready without any of its containers crashing, for it to be considered available.
-This defaults to 0 (the Pod will be considered available as soon as it is ready). To learn more about when
-a Pod is considered ready, see [Container Probes](/docs/concepts/workloads/pods/pod-lifecycle/#container-probes).
+## Update strategies
 
-Please note that this field only works if you enable the `StatefulSetMinReadySeconds` feature gate.
-## Update Strategies
-
-In Kubernetes 1.7 and later, StatefulSet's `.spec.updateStrategy` field allows you to configure
+A StatefulSet's `.spec.updateStrategy` field allows you to configure
 and disable automated rolling updates for containers, labels, resource request/limits, and
-annotations for the Pods in a StatefulSet.
+annotations for the Pods in a StatefulSet. There are two possible values:
 
-### On Delete
+`OnDelete`
+: When a StatefulSet's `.spec.updateStrategy.type` is set to `OnDelete`,
+  the StatefulSet controller will not automatically update the Pods in a
+  StatefulSet. Users must manually delete Pods to cause the controller to
+  create new Pods that reflect modifications made to a StatefulSet's `.spec.template`.
 
-The `OnDelete` update strategy implements the legacy (1.6 and prior) behavior. When a StatefulSet's
-`.spec.updateStrategy.type` is set to `OnDelete`, the StatefulSet controller will not automatically
-update the Pods in a StatefulSet. Users must manually delete Pods to cause the controller to
-create new Pods that reflect modifications made to a StatefulSet's `.spec.template`.
+`RollingUpdate`
+: The `RollingUpdate` update strategy implements automated, rolling update for the Pods in a StatefulSet. This is the default update strategy.
 
-### Rolling Updates
+## Rolling Updates
 
-The `RollingUpdate` update strategy implements automated, rolling update for the Pods in a
-StatefulSet. It is the default strategy when `.spec.updateStrategy` is left unspecified. When a StatefulSet's `.spec.updateStrategy.type` is set to `RollingUpdate`, the
+When a StatefulSet's `.spec.updateStrategy.type` is set to `RollingUpdate`, the
 StatefulSet controller will delete and recreate each Pod in the StatefulSet. It will proceed
 in the same order as Pod termination (from the largest ordinal to the smallest), updating
-each Pod one at a time. It will wait until an updated Pod is Running and Ready prior to
-updating its predecessor.
+each Pod one at a time.
+
+The Kubernetes control plane waits until an updated Pod is Running and Ready prior
+to updating its predecessor. If you have set `.spec.minReadySeconds` (see [Minimum Ready Seconds](#minimum-ready-seconds)), the control plane additionally waits that amount of time after the Pod turns ready, before moving on.
 
-#### Partitions
+### Partitioned rolling updates {#partitions}
 
 The `RollingUpdate` update strategy can be partitioned, by specifying a
 `.spec.updateStrategy.rollingUpdate.partition`. If a partition is specified, all Pods with an
@@ -272,7 +266,7 @@ updates to its `.spec.template` will not be propagated to its Pods.
 In most cases you will not need to use a partition, but they are useful if you want to stage an
 update, roll out a canary, or perform a phased roll out.
 
-#### Forced Rollback
+### Forced rollback
 
 When using [Rolling Updates](#rolling-updates) with the default
 [Pod Management Policy](#pod-management-policies) (`OrderedReady`),
@@ -292,6 +286,16 @@ After reverting the template, you must also delete any Pods that StatefulSet had
 already attempted to run with the bad configuration.
 StatefulSet will then begin to recreate the Pods using the reverted template.
 
+### Minimum ready seconds
+
+{{< feature-state for_k8s_version="v1.22" state="alpha" >}}
+
+`.spec.minReadySeconds` is an optional field that specifies the minimum number of seconds for which a newly
+created Pod should be ready without any of its containers crashing, for it to be considered available.
+This defaults to 0 (the Pod will be considered available as soon as it is ready). To learn more about when
+a Pod is considered ready, see [Container Probes](/docs/concepts/workloads/pods/pod-lifecycle/#container-probes).
+
+Please note that this field only works if you enable the `StatefulSetMinReadySeconds` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/).
 
 ## {{% heading "whatsnext" %}}