Improve docs for HorizontalPodAutoscaler #30711

sftim · 2021-12-01T23:59:38Z

(What I hope are) better docs for HPA, following on from PR #30547.

Preview, preview.

netlify · 2021-12-01T23:59:43Z

👷 Deploy Preview for kubernetes-io-vnext-staging processing.

🔨 Explore the source changes: e1bf8f2

🔍 Inspect the deploy log: https://app.netlify.com/sites/kubernetes-io-vnext-staging/deploys/61aa0996b1d31400089d51a1

sftim · 2021-12-01T23:59:45Z

/sig autoscaling

sftim · 2021-12-02T00:00:25Z

Relevant to issue #4493

jlbutler · 2021-12-02T16:55:06Z

/assign @chrisnegus

chrisnegus

Very nice job cleaning up this document. I like the addition of glossary terms and the use of exact object names. Side note: The some of the official autoscaling reviewers are no longer active. I had trouble finding a reviewer from one of the other PRs I was following. We might want to see about getting that list cleaned up.

chrisnegus · 2021-12-02T22:50:53Z

content/en/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough.md

+
+Roughly speaking, the HPA {{<glossary_tooltip text="controller" term_id="controller">}} will increase and decrease
+the number of replicas (by updating the Deployment) to maintain an average CPU utilization across all Pods of 50%.
+The Deployment then updates the ReplicaSet - this is part of how all Deployments work in Kubernetes -


Suggested change

The Deployment then updates the ReplicaSet - this is part of how all Deployments work in Kubernetes -

The Deployment then updates the ReplicaSet---this is part of how all Deployments work in Kubernetes---and

I think you mean an em dash here, which I believe is typically used without spaces before and after it.

I meant an en dash with spaces round it (but, I'm not very familiar with American-style punctuation). Could we tweak the punctuation in a follow up PR though?

As you like. We Americans do things a little different sometimes.

chrisnegus · 2021-12-02T22:52:15Z

content/en/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough.md

+Roughly speaking, the HPA {{<glossary_tooltip text="controller" term_id="controller">}} will increase and decrease
+the number of replicas (by updating the Deployment) to maintain an average CPU utilization across all Pods of 50%.
+The Deployment then updates the ReplicaSet - this is part of how all Deployments work in Kubernetes -
+and then the ReplicaSet either adds or removes Pods based on the change to its `.spec`.


Suggested change

and then the ReplicaSet either adds or removes Pods based on the change to its `.spec`.

then the ReplicaSet either adds or removes Pods based on the change to its `.spec`.

I added the "and" to the previous line so the em dash could butt up against it.

content/en/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough.md

chrisnegus · 2021-12-02T22:53:56Z

content/en/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough.md


 ```shell
+# You can use "hpa" or "horizontalpodautoscaler"; either name works OK.


Suggested change

# You can use "hpa" or "horizontalpodautoscaler"; either name works OK.

# You can use "hpa" or "horizontalpodautoscaler"; either name will work.

content/en/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough.md

content/en/docs/tasks/run-application/horizontal-pod-autoscale.md

chrisnegus · 2021-12-03T01:48:57Z

/lgtm
Nice job.

k8s-ci-robot · 2021-12-03T01:49:20Z

LGTM label has been added.

Git tree hash: aab5f2877f79ff9678d852c851253a0e0e4399c7

jlbutler · 2021-12-03T01:52:43Z

@gjtempleton could you give this one a quick tech review? thanks!

Co-authored-by: Chris Negus <[email protected]>

sftim · 2021-12-03T12:21:53Z

I fixed a spelling mistake I'd accidentally missed.

gjtempleton

Mostly nits, but a number of minor suggestions/queries, generally looks like a significant improvement though, thanks!

gjtempleton · 2021-12-03T21:11:59Z

content/en/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough.md

+the HorizontalPodAutoscaler instructs the workload resource (the Deployment, StatefulSet,
+or other similar resource) to scale back down.


This should probably end up referring to any object implementing the scale subresource, but I don't think we currently have any great place to link users to for more information on this, so best to leave it as is, and make improving the docs on the scale subresource a follow-up action.

gjtempleton · 2021-12-03T21:26:08Z

content/en/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough.md

-Finally, to use metrics not related to any Kubernetes object you must have a
-Kubernetes cluster at version 1.10 or later, and you must be able to communicate
-with the API server that provides the external Metrics API.
-See the [Horizontal Pod Autoscaler user guide](/docs/tasks/run-application/horizontal-pod-autoscale/#support-for-custom-metrics) for more details.


Do we move this anywhere else as this still applies given custom and external metrics continue to be entirely optional?

gjtempleton · 2021-12-03T21:28:29Z

content/en/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough.md

+[`kubectl autoscale`](/docs/reference/generated/kubectl/kubectl-commands#autoscale) subcommand,
+part of `kubectl`, that helps you do this.


Suggested change

[`kubectl autoscale`](/docs/reference/generated/kubectl/kubectl-commands#autoscale) subcommand,

part of `kubectl`, that helps you do this.

the [`kubectl autoscale`](/docs/reference/generated/kubectl/kubectl-commands#autoscale) subcommand,

part of `kubectl`, which helps you do this.

gjtempleton · 2021-12-03T21:30:52Z

content/en/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough.md

-The following command will create a Horizontal Pod Autoscaler that maintains between 1 and 10 replicas of the Pods
-controlled by the php-apache deployment we created in the first step of these instructions.
-Roughly speaking, HPA will increase and decrease the number of replicas
-(via the deployment) to maintain an average CPU utilization across all Pods of 50%.
 Since each pod requests 200 milli-cores by `kubectl run`, this means an average CPU usage of 100 milli-cores.


Is this not via kubectl apply rather than kubectl run at this point?

gjtempleton · 2021-12-03T21:35:37Z

content/en/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough.md

+and isn't usually a problem).
+
+Please note that the current CPU consumption is 0% as there are no clients sending requests to the server
+(the ``TARGET`` column shows the average across all the Pods controlled by the corresponding deployment).


This is an area we might need to expand on given the support for container-based scaling, though I don't think it should block this PR, especially given they're still in alpha.

gjtempleton · 2021-12-03T21:46:19Z

content/en/docs/tasks/run-application/horizontal-pod-autoscale.md

+  value as a percentage of the equivalent
+  [resource request](/docs/concepts/configuration/manage-resources-containers/#requests-and-limits)
+  on the containers in each Pod.  If a target raw value is set, the raw metric values are used directly.


Another point where we should likely call out the alpha support for container metrics.

gjtempleton · 2021-12-03T21:47:53Z

content/en/docs/tasks/run-application/horizontal-pod-autoscale.md

+The common use for HorizontalPodAutoscaler is to configure it to fetch metrics from
+{{< glossary_tooltip text="aggregated APIs" term_id="aggregation-layer" >}}
+(`metrics.k8s.io`, `custom.metrics.k8s.io`, or `external.metrics.k8s.io`).  The `metrics.k8s.io` API is
+usually provided by an add on named Metrics Server, which needs to be launched separately.


Suggested change

usually provided by an add on named Metrics Server, which needs to be launched separately.

usually provided by an add-on named Metrics Server, which needs to be launched separately.

Maybe personal preference, I'm not certain.

gjtempleton · 2021-12-03T21:49:25Z

content/en/docs/tasks/run-application/horizontal-pod-autoscale.md

-The autoscaler accesses corresponding scalable controllers (such as replication controllers, deployments, and replica sets)
-by using the scale sub-resource. Scale is an interface that allows you to dynamically set the number of replicas and examine
-each of their current states. More details on scale sub-resource can be found
-[here](https://git.k8s.io/community/contributors/design-proposals/autoscaling/horizontal-pod-autoscaler.md#scale-subresource).


As mentioned above, we need to improve our documentation of the scale subresource in general and link to it in a number of places, not a blocker though.

gjtempleton · 2021-12-03T21:50:40Z

content/en/docs/tasks/run-application/horizontal-pod-autoscale.md

+action if the ratio is sufficiently close to 1.0 (within a globally-configurable
+tolerance, 0.1 by default).



It does feel like we're forcing users to take an extra hop by removing the name of the flag here.

gjtempleton · 2021-12-03T22:03:23Z

content/en/docs/tasks/run-application/horizontal-pod-autoscale.md

+You specify these behaviours by setting `scaleUp` and / or `scaleDown`
+under the `behavior` field.
+
+You can specify a _stabilization window_ that prevents [flapping](#flapping)


Maybe mitigates or lessens is better here, as we can't guarantee preventing any scaling flapping.

Actually, do we need this segment given largely restating it ~40 lines below?

jlbutler · 2021-12-04T15:02:59Z

/lgtm
/approve

k8s-ci-robot · 2021-12-04T15:03:18Z

LGTM label has been added.

Git tree hash: f3d5bbd8dc0384f7fcb01b197856b463e2ea2ee2

k8s-ci-robot · 2021-12-04T15:03:27Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: jlbutler

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

~~content/en/OWNERS~~ [jlbutler]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

sftim · 2021-12-04T15:39:41Z

After the v1.23 release I'll see about nudging folk to improve this further.

k8s-ci-robot added this to the 1.23 milestone Dec 1, 2021

k8s-ci-robot added do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. labels Dec 1, 2021

k8s-ci-robot added sig/autoscaling Categorizes an issue or PR as relevant to SIG Autoscaling. size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels Dec 1, 2021

k8s-ci-robot requested review from DirectXMan12 and justinsb December 2, 2021 00:00

k8s-ci-robot added language/en Issues or PRs related to English language sig/docs Categorizes an issue or PR as relevant to SIG Docs. labels Dec 2, 2021

k8s-ci-robot assigned chrisnegus Dec 2, 2021

sftim marked this pull request as ready for review December 2, 2021 17:17

k8s-ci-robot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Dec 2, 2021

chrisnegus suggested changes Dec 2, 2021

View reviewed changes

sftim commented Dec 2, 2021

View reviewed changes

content/en/docs/tasks/run-application/horizontal-pod-autoscale.md Outdated Show resolved Hide resolved

sftim force-pushed the 20211123_improve_hpa_docs branch 2 times, most recently from 4440c7d to 6c9456c Compare December 3, 2021 00:04

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Dec 3, 2021

Improve docs for HorizontalPodAutoscaler

e1bf8f2

Co-authored-by: Chris Negus <[email protected]>

sftim force-pushed the 20211123_improve_hpa_docs branch from 6c9456c to e1bf8f2 Compare December 3, 2021 12:12

k8s-ci-robot removed the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Dec 3, 2021

gjtempleton reviewed Dec 3, 2021

View reviewed changes

k8s-ci-robot assigned jlbutler Dec 4, 2021

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Dec 4, 2021

k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Dec 4, 2021

k8s-ci-robot merged commit 702ae92 into kubernetes:dev-1.23 Dec 4, 2021

sftim deleted the 20211123_improve_hpa_docs branch December 4, 2021 15:39

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve docs for HorizontalPodAutoscaler #30711

Improve docs for HorizontalPodAutoscaler #30711

sftim commented Dec 1, 2021 •

edited

Loading

netlify bot commented Dec 1, 2021 •

edited

Loading

sftim commented Dec 1, 2021

sftim commented Dec 2, 2021

jlbutler commented Dec 2, 2021

chrisnegus left a comment

chrisnegus Dec 2, 2021

chrisnegus Dec 2, 2021

sftim Dec 2, 2021

chrisnegus Dec 3, 2021

chrisnegus Dec 2, 2021

chrisnegus Dec 2, 2021

chrisnegus commented Dec 3, 2021

k8s-ci-robot commented Dec 3, 2021

jlbutler commented Dec 3, 2021

sftim commented Dec 3, 2021

gjtempleton left a comment •

edited

Loading

gjtempleton Dec 3, 2021

gjtempleton Dec 3, 2021

gjtempleton Dec 3, 2021

gjtempleton Dec 3, 2021

gjtempleton Dec 3, 2021

gjtempleton Dec 3, 2021

gjtempleton Dec 3, 2021

gjtempleton Dec 3, 2021

gjtempleton Dec 3, 2021

gjtempleton Dec 3, 2021

gjtempleton Dec 3, 2021

jlbutler commented Dec 4, 2021

k8s-ci-robot commented Dec 4, 2021

k8s-ci-robot commented Dec 4, 2021

sftim commented Dec 4, 2021

	The Deployment then updates the ReplicaSet - this is part of how all Deployments work in Kubernetes -
	The Deployment then updates the ReplicaSet---this is part of how all Deployments work in Kubernetes---and

	and then the ReplicaSet either adds or removes Pods based on the change to its `.spec`.
	then the ReplicaSet either adds or removes Pods based on the change to its `.spec`.


		```shell
		# You can use "hpa" or "horizontalpodautoscaler"; either name works OK.

		the HorizontalPodAutoscaler instructs the workload resource (the Deployment, StatefulSet,
		or other similar resource) to scale back down.

		[`kubectl autoscale`](/docs/reference/generated/kubectl/kubectl-commands#autoscale) subcommand,
		part of `kubectl`, that helps you do this.

	usually provided by an add on named Metrics Server, which needs to be launched separately.
	usually provided by an add-on named Metrics Server, which needs to be launched separately.

		action if the ratio is sufficiently close to 1.0 (within a globally-configurable
		tolerance, 0.1 by default).

Improve docs for HorizontalPodAutoscaler #30711

Improve docs for HorizontalPodAutoscaler #30711

Conversation

sftim commented Dec 1, 2021 • edited Loading

netlify bot commented Dec 1, 2021 • edited Loading

sftim commented Dec 1, 2021

sftim commented Dec 2, 2021

jlbutler commented Dec 2, 2021

chrisnegus left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chrisnegus commented Dec 3, 2021

k8s-ci-robot commented Dec 3, 2021

jlbutler commented Dec 3, 2021

sftim commented Dec 3, 2021

gjtempleton left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jlbutler commented Dec 4, 2021

k8s-ci-robot commented Dec 4, 2021

k8s-ci-robot commented Dec 4, 2021

sftim commented Dec 4, 2021

sftim commented Dec 1, 2021 •

edited

Loading

netlify bot commented Dec 1, 2021 •

edited

Loading

gjtempleton left a comment •

edited

Loading