From df3184bd527afaf2f68a212f287e853ebe654921 Mon Sep 17 00:00:00 2001 From: John T Skarbek Date: Fri, 17 Sep 2021 13:24:00 -0400 Subject: [PATCH] Add recommendation for Deployment when HPA is enabled * Advertise that we need to remove `spec.replicas` when a Horizontal Pod Autoscaler is active to prevent unnecessary changes in Pod counts during Deployment object changes * Make note that a Deployment that has this value set behave awkwardly if a Deployment is scaled manually outside of the Deployment object Signed-off-by: John T Skarbek --- .../workloads/controllers/deployment.md | 12 ++++++ .../workloads/controllers/statefulset.md | 16 ++++++++ .../horizontal-pod-autoscale.md | 40 ++++++++++++++++++- 3 files changed, 67 insertions(+), 1 deletion(-) diff --git a/content/en/docs/concepts/workloads/controllers/deployment.md b/content/en/docs/concepts/workloads/controllers/deployment.md index 22b95255c5..b008ad916b 100644 --- a/content/en/docs/concepts/workloads/controllers/deployment.md +++ b/content/en/docs/concepts/workloads/controllers/deployment.md @@ -1070,6 +1070,18 @@ allowed, which is the default if not specified. `.spec.replicas` is an optional field that specifies the number of desired Pods. It defaults to 1. +Should you manually scale a Deployment, example via `kubectl scale deployment +deployment --replicas=X`, and then you update that Deployment based on a manifest +(for example: by running `kubectl apply -f deployment.yaml`), +then applying that manifest overwrites the manual scaling that you previously did. + +If a [HorizontalPodAutoscaler](/docs/tasks/run-application/horizontal-pod-autoscale/) (or any +similar API for horizontal scaling) is managing scaling for a Deployment, don't set `.spec.replicas`. + +Instead, allow the Kubernetes +{{< glossary_tooltip text="control plane" term_id="control-plane" >}} to manage the +`.spec.replicas` field automatically. + ### Selector `.spec.selector` is a required field that specifies a [label selector](/docs/concepts/overview/working-with-objects/labels/) diff --git a/content/en/docs/concepts/workloads/controllers/statefulset.md b/content/en/docs/concepts/workloads/controllers/statefulset.md index 3f89da5989..018cc018fa 100644 --- a/content/en/docs/concepts/workloads/controllers/statefulset.md +++ b/content/en/docs/concepts/workloads/controllers/statefulset.md @@ -295,6 +295,22 @@ a Pod is considered ready, see [Container Probes](/docs/concepts/workloads/pods/ Please note that this field only works if you enable the `StatefulSetMinReadySeconds` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/). +### Replicas + +`.spec.replicas` is an optional field that specifies the number of desired Pods. It defaults to 1. + +Should you manually scale a deployment, example via `kubectl scale +statefulset statefulset --replicas=X`, and then you update that StatefulSet +based on a manifest (for example: by running `kubectl apply -f +statefulset.yaml`), then applying that manifest overwrites the manual scaling +that you previously did. + +If a [HorizontalPodAutoscaler](/docs/tasks/run-application/horizontal-pod-autoscale/) +(or any similar API for horizontal scaling) is managing scaling for a +Statefulset, don't set `.spec.replicas`. Instead, allow the Kubernetes +{{}} to manage +the `.spec.replicas` field automatically. + ## {{% heading "whatsnext" %}} diff --git a/content/en/docs/tasks/run-application/horizontal-pod-autoscale.md b/content/en/docs/tasks/run-application/horizontal-pod-autoscale.md index 27165d0ca7..ff9c6aa97d 100644 --- a/content/en/docs/tasks/run-application/horizontal-pod-autoscale.md +++ b/content/en/docs/tasks/run-application/horizontal-pod-autoscale.md @@ -504,8 +504,46 @@ stops adjusting the target (and sets the `ScalingActive` Condition on itself to `false`) until you reactivate it by manually adjusting the target's desired replica count or HPA's minimum replica count. -## {{% heading "whatsnext" %}} +### Migrating Deployments and StatefulSets to horizontal autoscaling +When an HPA is enabled, it is recommended that the value of `spec.replicas` of +the Deployment and / or StatefulSet be removed from their +{{< glossary_tooltip text="manifest(s)" term_id="manifest" >}}. If this isn't done, any time +a change to that object is applied, for example via `kubectl apply -f +deployment.yaml`, this will instruct Kubernetes to scale the current number of Pods +to the value of the `spec.replicas` key. This may not be +desired and could be troublesome when an HPA is active. + +Keep in mind that the removal of `spec.replicas` may incur a one-time +degradation of Pod counts as the default value of this key is 1 (reference +[Deployment Replicas](/docs/concepts/workloads/controllers/deployment#replicas). +Upon the update, all Pods except 1 will begin their termination procedures. Any +deployment application afterwards will behave as normal and respect a rolling +update configuration as desired. You can avoid this degradation by choosing one of the following two +methods based on how you are modifying your deployments: + +{{< tabs name="fix_replicas_instructions" >}} +{{% tab name="Client Side Apply (this is the default)" %}} + +1. `kubectl apply edit-last-applied deployment/` +2. In the editor, remove `spec.replicas`. When you save and exit the editor, `kubectl` + applies the update. No changes to Pod counts happen at this step. +3. You can now remove `spec.replicas` from the manifest. If you use source code management, + also commit your changes or take whatever other steps for revising the source code + are appropriate for how you track updates. +4. From here on out you can run `kubectl apply -f deployment.yaml` + +{{% /tab %}} +{{% tab name="Server Side Apply" %}} + +When using the [Server-Side Apply](/docs/reference/using-api/server-side-apply/) +you can follow the [transferring ownership](/docs/reference/using-api/server-side-apply/#transferring-ownership) +guidelines, which cover this exact use case. + +{{% /tab %}} +{{< /tabs >}} + +## {{% heading "whatsnext" %}} * Design documentation: [Horizontal Pod Autoscaling](https://git.k8s.io/community/contributors/design-proposals/autoscaling/horizontal-pod-autoscaler.md). * kubectl autoscale command: [kubectl autoscale](/docs/reference/generated/kubectl/kubectl-commands/#autoscale).