Skip to content

Commit 870f79e

Browse files
mburke5678mburke5678
authored
Merge pull request #97322 from mburke5678/cqa-nodes-hpa
OSDOCS 15410 CQA: Automatically scaling pods with the horizontal pod autoscaler
2 parents 8fa6914 + edc6762 commit 870f79e

18 files changed

+555
-405
lines changed

‎modules/nodes-pods-autoscaling-about.adoc‎

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
// Module included in the following assemblies:
22
//
3-
// * nodes/nodes-pods-autoscaling-about.adoc
3+
// * nodes/nodes-pods-autoscaling.adoc
44

55
:_mod-docs-content-type: CONCEPT
66
[id="nodes-pods-autoscaling-about_{context}"]
@@ -18,12 +18,9 @@ ifdef::openshift-origin,openshift-enterprise,openshift-webscale[]
1818
To use horizontal pod autoscalers, your cluster administrator must have properly configured cluster metrics.
1919
endif::openshift-origin,openshift-enterprise,openshift-webscale[]
2020

21-
[id="supported-metrics_{context}"]
22-
== Supported metrics
23-
2421
The following metrics are supported by horizontal pod autoscalers:
2522

26-
.Metrics
23+
.Supported metrics
2724
[cols="3a,5a,5a",options="header"]
2825
|===
2926

‎modules/nodes-pods-autoscaling-best-practices-hpa.adoc‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@ For optimal performance, configure resource requests for all pods. To prevent fr
1111
All pods must have resource requests configured::
1212
The HPA makes a scaling decision based on the observed CPU or memory usage values of pods in an {product-title} cluster. Utilization values are calculated as a percentage of the resource requests of each pod. Missing resource request values can affect the optimal performance of the HPA.
1313

14+
For more information, see "Understanding resource requests and limits".
15+
1416
Configure the cool down period::
1517
During horizontal pod autoscaling, there might be a rapid scaling of events without a time gap. Configure the cool down period to prevent frequent replica fluctuations. You can specify a cool down period by configuring the `stabilizationWindowSeconds` field. The stabilization window is used to restrict the fluctuation of replicas count when the metrics used for scaling keep fluctuating. The autoscaling algorithm uses this window to infer a previous required state and avoid unwanted changes to workload scale.
1618

@@ -24,3 +26,5 @@ behavior:
2426
----
2527

2628
In the previous example, all intended states for the past 5 minutes are considered. This approximates a rolling maximum, and avoids having the scaling algorithm often remove pods only to trigger recreating an equal pod just moments later.
29+
30+
For more information, see "Scaling policies".

‎modules/nodes-pods-autoscaling-creating-cpu-percent.adoc‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * nodes/nodes-pods-autoscaling.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="nodes-pods-autoscaling-creating-cpu-percent_{context}"]
7+
= Creating a horizontal pod autoscaler for a percent of CPU use
8+
9+
Using the {product-title} CLI, you can create a horizontal pod autoscaler (HPA) to automatically scale an existing object based on percent of CPU use. The HPA scales the pods associated with that object to maintain the CPU use that you specify.
10+
11+
When autoscaling for a percent of CPU use, you can use the `oc autoscale` command to specify the minimum and maximum number of pods that you want to run at any given time and the average CPU use your pods should target. If you do not specify a minimum, the pods are given default values from the {product-title} server.
12+
13+
[NOTE]
14+
====
15+
Use a `Deployment` object or `ReplicaSet` object unless you need a specific feature or behavior provided by other objects.
16+
====
17+
18+
.Prerequisites
19+
20+
include::snippets/nodes-pods-autoscaling-creating-cpu-prereqs.adoc[]
21+
22+
.Procedure
23+
24+
. Create a `HorizontalPodAutoscaler` object for an existing object:
25+
+
26+
[source,terminal]
27+
----
28+
$ oc autoscale <object_type>/<name> \// <1>
29+
--min <number> \// <2>
30+
--max <number> \// <3>
31+
--cpu-percent=<percent> <4>
32+
----
33+
+
34+
<1> Specify the type and name of the object to autoscale. The object must exist and be a `Deployment`, `DeploymentConfig`/`dc`, `ReplicaSet`/`rs`, `ReplicationController`/`rc`, or `StatefulSet`.
35+
<2> Optional: Specify the minimum number of replicas when scaling down.
36+
<3> Specify the maximum number of replicas when scaling up.
37+
<4> Specify the target average CPU use over all the pods, represented as a percent of requested CPU. If not specified or negative, a default autoscaling policy is used.
38+
+
39+
For example, the following command shows autoscaling for the `hello-node` deployment object. The initial deployment requires 3 pods. The HPA object increases the minimum to 5. If CPU usage on the pods reaches 75%, the pods will increase to 7:
40+
+
41+
[source,terminal]
42+
----
43+
$ oc autoscale deployment/hello-node --min=5 --max=7 --cpu-percent=75
44+
----
45+
46+
. Create the horizontal pod autoscaler:
47+
+
48+
[source,terminal]
49+
----
50+
$ oc create -f <file-name>.yaml
51+
----
52+
53+
.Verification
54+
55+
* Ensure that the horizontal pod autoscaler was created:
56+
+
57+
[source,terminal]
58+
----
59+
$ oc get hpa cpu-autoscale
60+
----
61+
+
62+
.Example output
63+
[source,terminal]
64+
----
65+
NAME REFERENCE TARGETS MINPODS MAXPODS REPLICAS AGE
66+
cpu-autoscale Deployment/example 173m/500m 1 10 1 20m
67+
----

‎modules/nodes-pods-autoscaling-creating-cpu-specific.adoc‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * nodes/nodes-pods-autoscaling.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="nodes-pods-autoscaling-creating-cpu-specific_{context}"]
7+
= Creating a horizontal pod autoscaler for a specific CPU value
8+
9+
Using the {product-title} CLI, you can create a horizontal pod autoscaler (HPA) to automatically scale an existing object based on a specific CPU value by creating a `HorizontalPodAutoscaler` object with the target CPU and pod limits. The HPA scales the pods associated with that object to maintain the CPU use that you specify.
10+
11+
[NOTE]
12+
====
13+
Use a `Deployment` object or `ReplicaSet` object unless you need a specific feature or behavior provided by other objects.
14+
====
15+
16+
.Prerequisites
17+
18+
include::snippets/nodes-pods-autoscaling-creating-cpu-prereqs.adoc[]
19+
20+
.Procedure
21+
22+
. Create a YAML file similar to the following for an existing object:
23+
+
24+
[source,yaml,options="nowrap"]
25+
----
26+
apiVersion: autoscaling/v2 <1>
27+
kind: HorizontalPodAutoscaler
28+
metadata:
29+
name: cpu-autoscale <2>
30+
namespace: default
31+
spec:
32+
scaleTargetRef:
33+
apiVersion: apps/v1 <3>
34+
kind: Deployment <4>
35+
name: example <5>
36+
minReplicas: 1 <6>
37+
maxReplicas: 10 <7>
38+
metrics: <8>
39+
- type: Resource
40+
resource:
41+
name: cpu <9>
42+
target:
43+
type: AverageValue <10>
44+
averageValue: 500m <11>
45+
----
46+
<1> Use the `autoscaling/v2` API.
47+
<2> Specify a name for this horizontal pod autoscaler object.
48+
<3> Specify the API version of the object to scale:
49+
* For a `Deployment`, `ReplicaSet`, `Statefulset` object, use `apps/v1`.
50+
* For a `ReplicationController`, use `v1`.
51+
* For a `DeploymentConfig`, use `apps.openshift.io/v1`.
52+
<4> Specify the type of object. The object must be a `Deployment`, `DeploymentConfig`/`dc`, `ReplicaSet`/`rs`, `ReplicationController`/`rc`, or `StatefulSet`.
53+
<5> Specify the name of the object to scale. The object must exist.
54+
<6> Specify the minimum number of replicas when scaling down.
55+
<7> Specify the maximum number of replicas when scaling up.
56+
<8> Use the `metrics` parameter for memory use.
57+
<9> Specify `cpu` for CPU usage.
58+
<10> Set to `AverageValue`.
59+
<11> Set to `averageValue` with the targeted CPU value.
60+
61+
. Create the horizontal pod autoscaler:
62+
+
63+
[source,terminal]
64+
----
65+
$ oc create -f <file-name>.yaml
66+
----
67+
68+
.Verification
69+
70+
* Check that the horizontal pod autoscaler was created:
71+
+
72+
[source,terminal]
73+
----
74+
$ oc get hpa cpu-autoscale
75+
----
76+
+
77+
.Example output
78+
[source,terminal]
79+
----
80+
NAME REFERENCE TARGETS MINPODS MAXPODS REPLICAS AGE
81+
cpu-autoscale Deployment/example 173m/500m 1 10 1 20m
82+
----

‎modules/nodes-pods-autoscaling-creating-cpu.adoc‎

Lines changed: 5 additions & 139 deletions
Original file line numberDiff line numberDiff line change
@@ -1,147 +1,13 @@
11
// Module included in the following assemblies:
22
//
3-
// * nodes/nodes-pods-autoscaling-about.adoc
3+
// * nodes/nodes-pods-autoscaling.adoc
44

55
:_mod-docs-content-type: PROCEDURE
66
[id="nodes-pods-autoscaling-creating-cpu_{context}"]
7-
= Creating a horizontal pod autoscaler for CPU utilization by using the CLI
7+
= Creating a horizontal pod autoscaler by using the CLI
88

9-
Using the {product-title} CLI, you can create a horizontal pod autoscaler (HPA) to automatically scale an existing `Deployment`, `DeploymentConfig`, `ReplicaSet`, `ReplicationController`, or `StatefulSet` object. The HPA scales the pods associated with that object to maintain the CPU usage you specify.
9+
Using the {product-title} CLI, you can create a horizontal pod autoscaler (HPA) to automatically scale an existing `Deployment`, `DeploymentConfig`, `ReplicaSet`, `ReplicationController`, or `StatefulSet` object. The HPA scales the pods associated with that object to maintain the CPU or memory resources that you specify.
1010

11-
[NOTE]
12-
====
13-
It is recommended to use a `Deployment` object or `ReplicaSet` object unless you need a specific feature or behavior provided by other objects.
14-
====
15-
16-
The HPA increases and decreases the number of replicas between the minimum and maximum numbers to maintain the specified CPU utilization across all pods.
17-
18-
When autoscaling for CPU utilization, you can use the `oc autoscale` command and specify the minimum and maximum number of pods you want to run at any given time and the average CPU utilization your pods should target. If you do not specify a minimum, the pods are given default values from the {product-title} server.
19-
20-
To autoscale for a specific CPU value, create a `HorizontalPodAutoscaler` object with the target CPU and pod limits.
21-
22-
.Prerequisites
23-
24-
To use horizontal pod autoscalers, your cluster administrator must have properly configured cluster metrics.
25-
You can use the `oc describe PodMetrics <pod-name>` command to determine if metrics are configured. If metrics are
26-
configured, the output appears similar to the following, with `Cpu` and `Memory` displayed under `Usage`.
27-
28-
[source,terminal]
29-
----
30-
$ oc describe PodMetrics openshift-kube-scheduler-ip-10-0-135-131.ec2.internal
31-
----
32-
33-
.Example output
34-
[source,text,options="nowrap"]
35-
----
36-
Name: openshift-kube-scheduler-ip-10-0-135-131.ec2.internal
37-
Namespace: openshift-kube-scheduler
38-
Labels: <none>
39-
Annotations: <none>
40-
API Version: metrics.k8s.io/v1beta1
41-
Containers:
42-
Name: wait-for-host-port
43-
Usage:
44-
Memory: 0
45-
Name: scheduler
46-
Usage:
47-
Cpu: 8m
48-
Memory: 45440Ki
49-
Kind: PodMetrics
50-
Metadata:
51-
Creation Timestamp: 2019-05-23T18:47:56Z
52-
Self Link: /apis/metrics.k8s.io/v1beta1/namespaces/openshift-kube-scheduler/pods/openshift-kube-scheduler-ip-10-0-135-131.ec2.internal
53-
Timestamp: 2019-05-23T18:47:56Z
54-
Window: 1m0s
55-
Events: <none>
56-
----
57-
58-
.Procedure
59-
60-
To create a horizontal pod autoscaler for CPU utilization:
61-
62-
. Perform one of the following:
63-
64-
** To scale based on the percent of CPU utilization, create a `HorizontalPodAutoscaler` object for an existing object:
65-
+
66-
[source,terminal]
67-
----
68-
$ oc autoscale <object_type>/<name> \// <1>
69-
--min <number> \// <2>
70-
--max <number> \// <3>
71-
--cpu-percent=<percent> <4>
72-
----
73-
+
74-
<1> Specify the type and name of the object to autoscale. The object must exist and be a `Deployment`, `DeploymentConfig`/`dc`, `ReplicaSet`/`rs`, `ReplicationController`/`rc`, or `StatefulSet`.
75-
<2> Optionally, specify the minimum number of replicas when scaling down.
76-
<3> Specify the maximum number of replicas when scaling up.
77-
<4> Specify the target average CPU utilization over all the pods, represented as a percent of requested CPU. If not specified or negative, a default autoscaling policy is used.
78-
+
79-
For example, the following command shows autoscaling for the `hello-node` deployment object. The initial deployment requires 3 pods. The HPA object increases the minimum to 5. If CPU usage on the pods reaches 75%, the pods will increase to 7:
80-
+
81-
[source,terminal]
82-
----
83-
$ oc autoscale deployment/hello-node --min=5 --max=7 --cpu-percent=75
84-
----
85-
86-
** To scale for a specific CPU value, create a YAML file similar to the following for an existing object:
87-
+
88-
.. Create a YAML file similar to the following:
89-
+
90-
[source,yaml,options="nowrap"]
91-
----
92-
apiVersion: autoscaling/v2 <1>
93-
kind: HorizontalPodAutoscaler
94-
metadata:
95-
name: cpu-autoscale <2>
96-
namespace: default
97-
spec:
98-
scaleTargetRef:
99-
apiVersion: apps/v1 <3>
100-
kind: Deployment <4>
101-
name: example <5>
102-
minReplicas: 1 <6>
103-
maxReplicas: 10 <7>
104-
metrics: <8>
105-
- type: Resource
106-
resource:
107-
name: cpu <9>
108-
target:
109-
type: AverageValue <10>
110-
averageValue: 500m <11>
111-
----
112-
<1> Use the `autoscaling/v2` API.
113-
<2> Specify a name for this horizontal pod autoscaler object.
114-
<3> Specify the API version of the object to scale:
115-
* For a `Deployment`, `ReplicaSet`, `Statefulset` object, use `apps/v1`.
116-
* For a `ReplicationController`, use `v1`.
117-
* For a `DeploymentConfig`, use `apps.openshift.io/v1`.
118-
<4> Specify the type of object. The object must be a `Deployment`, `DeploymentConfig`/`dc`, `ReplicaSet`/`rs`, `ReplicationController`/`rc`, or `StatefulSet`.
119-
<5> Specify the name of the object to scale. The object must exist.
120-
<6> Specify the minimum number of replicas when scaling down.
121-
<7> Specify the maximum number of replicas when scaling up.
122-
<8> Use the `metrics` parameter for memory utilization.
123-
<9> Specify `cpu` for CPU utilization.
124-
<10> Set to `AverageValue`.
125-
<11> Set to `averageValue` with the targeted CPU value.
126-
127-
.. Create the horizontal pod autoscaler:
128-
+
129-
[source,terminal]
130-
----
131-
$ oc create -f <file-name>.yaml
132-
----
133-
134-
. Verify that the horizontal pod autoscaler was created:
135-
+
136-
[source,terminal]
137-
----
138-
$ oc get hpa cpu-autoscale
139-
----
140-
+
141-
.Example output
142-
[source,terminal]
143-
----
144-
NAME REFERENCE TARGETS MINPODS MAXPODS REPLICAS AGE
145-
cpu-autoscale Deployment/example 173m/500m 1 10 1 20m
146-
----
11+
You can autoscale based on CPU or memory use by specifying a percentage of resource usage or a specific value, as described in the following sections.
14712

13+
The HPA increases and decreases the number of replicas between the minimum and maximum numbers to maintain the specified resource use across all pods.

0 commit comments

Comments
 (0)