From 03c2c0fb356728231c902e764e067b52e714750a Mon Sep 17 00:00:00 2001 From: Tim Bannister Date: Mon, 2 Aug 2021 15:45:03 +0100 Subject: [PATCH] Improve StatefulSet docs around rolling updates As an alpha feature, rolling updates for StatefulSets can now have a .spec.minReadySeconds field. Improve the documentation for StatefulSets to better explain how this is useful. --- .../workloads/controllers/statefulset.md | 52 ++++++++++--------- 1 file changed, 28 insertions(+), 24 deletions(-) diff --git a/content/en/docs/concepts/workloads/controllers/statefulset.md b/content/en/docs/concepts/workloads/controllers/statefulset.md index 5d05dcb8de..faf244b1a5 100644 --- a/content/en/docs/concepts/workloads/controllers/statefulset.md +++ b/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" >}} +## Update strategies -`.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. -## 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. -#### Partitions +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. + +### 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" %}}