openshift/openshift-docs
1
0
Fork 0
mirror of https://github.com/openshift/openshift-docs.git synced 2026-02-05 21:46:22 +01:00
Code Issues Releases Activity

[RFE] hpa docs

Browse Source
This commit is contained in:
Michael Burke
2019-05-09 10:48:46 -04:00
parent c044c1396a
commit 8b9498694e
8 changed files with 635 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
_topic_map.yml
View File

@@ -459,6 +459,8 @@ Topics:
- Name: Configuring a cluster for Pods
File: nodes-pods-configuring
Distros: openshift-enterprise,openshift-origin
- Name: Automatically scaling pods
File: nodes-pods-autoscaling
- Name: Providing sensitive data to Pods
File: nodes-pods-secrets
- Name: Using Device Manager to make devices available to nodes

73
modules/nodes-pods-autoscaling-about.adoc Normal file
View File

@@ -0,0 +1,73 @@
// Module included in the following assemblies:
//
// * nodes/nodes-pods-autoscaling-about.adoc
[id='nodes-pods-autoscaling-about_{context}']
= Understanding horizontal pod autoscalers
You can create a horizontal pod autoscaler to specify the minimum and maximum number of pods
you want to run, as well as the CPU utilization or memory utilization your pods should target.
[IMPORTANT]
====
Autoscaling for Memory Utilization is a Technology Preview feature only.
====
After you create a horizontal pod autoscaler, {product-title} begins to query the CPU and/or memory resource metrics on the pods.
This query can take one to two minutes before obtaining the initial metrics.
After these metrics are available, the horizontal pod autoscaler computes
the ratio of the current metric utilization with the desired metric utilization,
and scales up or down accordingly. The scaling occurs at a regular interval,
but can take one to two minutes before metrics become available.
For replication controllers, this scaling corresponds directly to the replicas
of the replication controller. For deployment configurations, scaling corresponds
directly to the replica count of the deployment configuration. Note that autoscaling
applies only to the latest deployment in the `Complete` phase.
{product-title} automatically accounts for resources and prevents unnecessary autoscaling
during resource spikes, such as during start up. Pods in the `unready` state
have `0 CPU` usage when scaling up and the autoscaler ignores the pods when scaling down.
Pods without known metrics have `0% CPU` usage when scaling up and `100% CPU` when scaling down.
This allows for more stability during the HPA decision. To use this feature, you must configure
readiness checks to determine if a new pod is ready for use.
ifdef::openshift-origin,openshift-enterprise[]
In order to use horizontal pod autoscalers, your cluster administrator must have
properly configured cluster metrics.
endif::openshift-origin,openshift-enterprise[]
== Supported metrics
The following metrics are supported by horizontal pod autoscalers:
.Metrics
[cols="3a,5a,5a",options="header"]
|===
|Metric |Description |API version
|CPU utilization
|Number of CPU cores used. Can be used to calculate a percentage of the pod's requested CPU.
|`autoscaling/v1`, `autoscaling/v2beta2`
|Memory utilization
|Amount of memory used. Can be used to calculate a percentage of the pod's requested memory.
|`autoscaling/v2beta2`
|===
[IMPORTANT]
====
For memory-based autoscaling, memory usage must increase and decrease
proportionally to the replica count. On average:
* An increase in replica count must lead to an overall decrease in memory
(working set) usage per-pod.
* A decrease in replica count must lead to an overall increase in per-pod memory
usage.
Use the {product-title} web console to check the memory behavior of your application
and ensure that your application meets these requirements before using
memory-based autoscaling.
====

82
modules/nodes-pods-autoscaling-creating-cpu.adoc Normal file
View File

@@ -0,0 +1,82 @@
// Module included in the following assemblies:
//
// * nodes/nodes-pods-autoscaling-about.adoc
[id='nodes-pods-autoscaling-creating-cpu_{context}']
= Creating a horizontal pod autoscaler for CPU utilization
You can create a horizontal pod autoscaler (HPA) to automatically scale pods when CPU usage exceeds a specified percentage.
You create the HPA for a replication controller or deployment controller, based on how your pods were created.
.Prerequisites
In order to use horizontal pod autoscalers, your cluster administrator must have properly configured cluster metrics.
You can use the `oc describe PodMetrics <pod-name>` command to determine if metrics are configured. If metrics are
configured, the output appears similar to the following, with `Cpu` and `Memory` displayed under `Usage`.
----
$ oc describe PodMetrics openshift-kube-scheduler-ip-10-0-135-131.ec2.internal
Name: openshift-kube-scheduler-ip-10-0-135-131.ec2.internal
Namespace: openshift-kube-scheduler
Labels: <none>
Annotations: <none>
API Version: metrics.k8s.io/v1beta1
Containers:
Name: wait-for-host-port
Usage:
Memory: 0
Name: scheduler
Usage:
Cpu: 8m
Memory: 45440Ki
Kind: PodMetrics
Metadata:
Creation Timestamp: 2019-05-23T18:47:56Z
Self Link: /apis/metrics.k8s.io/v1beta1/namespaces/openshift-kube-scheduler/pods/openshift-kube-scheduler-ip-10-0-135-131.ec2.internal
Timestamp: 2019-05-23T18:47:56Z
Window: 1m0s
Events: <none>
----
.Procedure
* Use one of the following commands to create a horizontal pod autoscaler for CPU utilization
for a deployment controller or a replication controller:
+
----
oc autoscale dc/<deployment-name> \//<1>
--min <number> \//<2>
--max <number> \//<3>
--cpu-percent=<percent> <4>
oc autoscale rc/<file-name> --min <number> --max <number> --cpu-percent=<percent>
----
+
<1> Specify the deployment object or replica file.
<2> Specify the minimum number of replicas when scaling down.
<3> Specify the maximum number of replicas when scaling up.
<4> Specify the target average CPU utilization, represented as a percent of requested CPU, over all the pods. If not specified or negative, a default autoscaling policy will be used.
+
For example:
+
----
oc autoscale dc/example --min=5 --max=7 --cpu-percent=75
----
+
The following example shows autoscaling for the `example` deployment configuration. The initial deployment requires 3 pods. The HPA object increased that minumum to 5 and will increase the pods up to 7 if CPU usage on the pods reaches 75%:
+
----
$ oc get dc example
NAME REVISION DESIRED CURRENT TRIGGERED BY
example 1 3 3 config
$ oc autoscale dc/example --min=5 --max=7 --cpu-percent=75
horizontalpodautoscaler.autoscaling/example autoscaled
$ oc get dc
NAME REVISION DESIRED CURRENT TRIGGERED BY
example 1 5 5 config
----

166
modules/nodes-pods-autoscaling-creating-memory.adoc Normal file
View File

@@ -0,0 +1,166 @@
// Module included in the following assemblies:
//
// * nodes/nodes-pods-autoscaling-about.adoc
[id='nodes-pods-autoscaling-creating-memory_{context}']
= Creating a horizontal pod autoscaler object for memory utilization
You can create a horizontal pod autoscaler to automatically scale pods in a Deployment when memory usage exceeds a specified limit.
[IMPORTANT]
====
Autoscaling for memory utilization is a Technology Preview feature only.
ifdef::openshift-enterprise[]
Technology Preview features are not supported with Red Hat production service
level agreements (SLAs), might not be functionally complete, and Red Hat does
not recommend to use them for production. These features provide early access to
upcoming product features, enabling customers to test functionality and provide
feedback during the development process.
For more information on Red Hat Technology Preview features support scope, see
https://access.redhat.com/support/offerings/techpreview/.
endif::[]
====
.Prerequisites
In order to use horizontal pod autoscalers, your cluster administrator must have properly configured cluster metrics.
You can use the `oc describe PodMetrics <pod-name>` command to determine if metrics are configured. If metrics are
configured, the output appears similar to the following, with `Cpu` and `Memory` displayed under `Usage`.
----
$ oc describe PodMetrics openshift-kube-scheduler-ip-10-0-135-131.ec2.internal
Name: openshift-kube-scheduler-ip-10-0-135-131.ec2.internal
Namespace: openshift-kube-scheduler
Labels: <none>
Annotations: <none>
API Version: metrics.k8s.io/v1beta1
Containers:
Name: wait-for-host-port
Usage:
Memory: 0
Name: scheduler
Usage:
Cpu: 8m
Memory: 45440Ki
Kind: PodMetrics
Metadata:
Creation Timestamp: 2019-05-23T18:47:56Z
Self Link: /apis/metrics.k8s.io/v1beta1/namespaces/openshift-kube-scheduler/pods/openshift-kube-scheduler-ip-10-0-135-131.ec2.internal
Timestamp: 2019-05-23T18:47:56Z
Window: 1m0s
Events: <none>
----
.Procedure
To create a horizontal pod autoscaler for memory utilization:
. Create a YAML file that contains one of the following:
+
.Sample HPA object for an absolute value
[source,yaml,options="nowrap"]
----
apiVersion: autoscaling/v2beta2
kind: HorizontalPodAutoscaler
metadata:
name: memory-autoscale <1>
namespace: default
spec:
scaleTargetRef:
apiVersion: apps/v1 <2>
name: example <3>
kind: DeploymentConfig <4>
minReplicas: 1 <5>
maxReplicas: 10 <6>
metrics:
- type: Resource
resource:
name: memory
target:
name: memory-absolute
targetAverageValue: 500Mi <7>
----
<1> Specify the name of this horizontal pod autoscaler object.
<2> Specify `apps/v1` as the API version of the object to scale.
<3> Specify the name of the object to scale.
<4> Specify the kind of object to scale.
<5> Specify the minimum number of replicas when scaling down.
<6> Specify the maximum number of replicas when scaling up.
<7> Specify the average amount of memory used per pod.
.Sample HPA object for a percentage
[source,yaml,options="nowrap"]
----
apiVersion: autoscaling/v2beta2
kind: HorizontalPodAutoscaler
metadata:
name: memory-autoscale <1>
namespace: default
spec:
scaleTargetRef:
apiVersion: apps/v1 <2>
name: example <3>
kind: DeploymentConfig <4>
minReplicas: 1 <5>
maxReplicas: 10 <6>
metrics:
- type: Resource
resource:
name: memory
target:
name: memory-percent
type: Utilization
averageUtilization: 50 <7>
----
<1> Specify the name of this horizontal pod autoscaler object.
<2> Specify `apps/v1` as the API version of the object to scale.
<3> Specify the name of the object to scale.
<4> Specify the kind of object to scale.
<5> Specify the minimum number of replicas when scaling down.
<6> Specify the maximum number of replicas when scaling up.
<7> The average percentage of the requested memory that each pod should be using.
. Create the autoscaler from the above file:
+
[source,bash]
----
$ oc create -f <file-name>.yaml
----
+
For example:
+
----
$ oc create -f hpa.yaml
horizontalpodautoscaler.autoscaling/hpa-resource-metrics-memory created
----
. Verify that the HPA was created:
+
----
$ oc get hpa memory-autoscale
NAME REFERENCE TARGETS MINPODS MAXPODS REPLICAS AGE
memory-autoscale DeploymentConfig/example <unknown>/500Mi 1 10 0 56s
----
+
----
$ oc describe hpa memory-autoscale
Name: memory-autoscale
Namespace: default
Labels: <none>
Annotations: <none>
CreationTimestamp: Wed, 22 May 2019 20:56:35 -0400
Reference: DeploymentConfig/example
Metrics: ( current / target )
resource cpu on pods (as a percentage of request): <unknown>/500Mi
Min replicas: 1
Max replicas: 10
DeploymentConfig pods: 0 current / 0 desired
Events: <none>
----

103
modules/nodes-pods-autoscaling-creating.adoc Normal file
View File

@@ -0,0 +1,103 @@
// Module included in the following assemblies:
//
// * nodes/nodes-pods-autoscaling-about.adoc
[id='nodes-pods-autoscaling-creating_{context}']
= Understanding how to create a horizontal pod autoscaler
How you create the horizontal pod autoscaler (HPA) depends on whether you want to scale for CPU or memory utilization.
CPU utilization::
For CPU utilization:, you can create a horizontal pod autoscaler using the command line or by
creating a `HorizontalPodAutoscaler` object.
When creating an HPA to control pod scaling based on CPU utilization, you specify the maximum number of pods
you want to run at any given time. You can also specify a minimum number of pods.
The following command creates a Horizontal Pod Autoscaler that maintains between 1 and 10 replicas of the Pods controlled by the `image-registry` DeploymentConfig to maintain an average CPU utilization of 50% across all Pods.
----
$ oc autoscale dc/image-registry --min 1 --max 10 --cpu-percent=50
----
The command creates the following object configuration:
.Horizontal Pod Autoscaler Object Definition for CPU utilization
[source,yaml,options="nowrap"]
----
$ oc edit hpa image-registry
----
----
apiVersion: autoscaling/v1
kind: HorizontalPodAutoscaler
metadata:
annotations:
autoscaling.alpha.kubernetes.io/conditions: '[{"type":"AbleToScale","status":"True","lastTransitionTime":"2019-05-22T20:49:57Z","reason":"SucceededGetScale","message":"the
HPA controller was able to get the target''s current scale"},{"type":"ScalingActive","status":"False","lastTransitionTime":"2019-05-22T20:49:57Z","reason":"FailedGetResourceMetric","message":"the
HPA was unable to compute the replica count: missing request for cpu"}]'
creationTimestamp: 2019-05-22T20:49:42Z
name: image-registry <1>
namespace: default
resourceVersion: "325215"
selfLink: /apis/autoscaling/v1/namespaces/default/horizontalpodautoscalers/image-registry
uid: 1fd7585a-7cd3-11e9-9d00-0e2a93384702
spec:
maxReplicas: 10 <2>
minReplicas: 1 <3>
scaleTargetRef:
apiVersion: apps.openshift.io/v1
kind: DeploymentConfig <4>
name: image-registry <5>
targetCPUUtilizationPercentage: 50 <6>
status:
currentReplicas: 3
desiredReplicas: 0
----
<1> The name of this horizontal pod autoscaler object.
<2> The lower limit for the number of pods that can be set by the autoscaler. If not specified or negative, the server will apply a default value.
<3> The upper limit for the number of pods that can be set by the autoscaler. This value is required.
<4> The kind of object to scale, DeploymentConfig or ReplicationController.
<5> The name of the object to scale.
<6> The percentage of the requested CPU that each pod should ideally be using.
Memory utilization::
For memory utilization, you can specify the minimum number of pods and the average memory utilization
your pods should target as well, otherwise those are given default values from
the {product-title} server.
You can specify resource metrics in terms of direct values, instead of as percentages
of the requested value, by using a target type of `AverageValue` instead of `AverageUtilization`,
and setting the corresponding `target.averageValue` field instead of the `target.averageUtilization`.
.Horizontal Pod Autoscaler Object Definition for memory utilization
[source,yaml,options="nowrap"]
----
apiVersion: autoscaling/v2beta2
kind: HorizontalPodAutoscaler
metadata:
name: memory-autoscale <1>
namespace: default
spec:
scaleTargetRef:
apiVersion: apps/v1
name: example <2>
kind: DeploymentConfig <3>
minReplicas: 1
maxReplicas: 10
metrics:
- type: Resource
resource:
name: cpu
target:
type: Utilization
averageUtilization: 50
----
<1> The name of this horizontal pod autoscaler object.
<2> The API version of the object to scale.
<3> The kind of object to scale.
<4> The name of the object to scale.
<5> The lower limit for the number of pods that can be set by the autoscaler. If not specified or negative, the server will apply a default value.
<6> The upper limit for the number of pods that can be set by the autoscaler. This value is required.
<7> The type of must be either Utilization, Value, or AverageValue.

89
modules/nodes-pods-autoscaling-status-about.adoc Normal file
View File

@@ -0,0 +1,89 @@
// Module included in the following assemblies:
//
// * nodes/nodes-pods-autoscaling-about.adoc
[id='nodes-pods-autoscaling-status-about_{context}']
= Understanding horizontal pod autoscaler status conditions
You can use the status conditions set to determine
whether or not the horizontal pod autoscaler (HPA) is able to scale and whether or not it is currently restricted
in any way.
The HPA status conditions are available with the `v2beta1` version of the
autoscaling API.
The HPA responds with the following status conditions:
* The `AbleToScale` condition indicates whether HPA is able to fetch and update metrics, as well as whether any backoff-related conditions could prevent scaling.
** A `True` condition indicates scaling is allowed.
** A `False` condition indicates scaling is not allowed for the reason specified.
* The `ScalingActive` condition indicates whether the HPA is enabled (for example, the replica count of the target is not zero) and is able to calculate desired metrics.
** A `True` condition indicates metrics is working properly.
** A `False` condition generally indicates a problem with fetching metrics.
* The `ScalingLimited` condition indicates that the desired scale was capped by the maximum or minimum of the horizontal pod autoscaler.
** A `True` condition indicates that you need to raise or lower the minimum or maximum replica count in order to scale.
** A `False` condition indicates that the requested scaling is allowed.
+
[source,bash]
----
$ oc describe hpa cm-test
Name: cm-test
Namespace: prom
Labels: <none>
Annotations: <none>
CreationTimestamp: Fri, 16 Jun 2017 18:09:22 +0000
Reference: ReplicationController/cm-test
Metrics: ( current / target )
"http_requests" on pods: 66m / 500m
Min replicas: 1
Max replicas: 4
ReplicationController pods: 1 current / 1 desired
Conditions: <1>
Type Status Reason Message
---- ------ ------ -------
AbleToScale True ReadyForNewScale the last scale time was sufficiently old as to warrant a new scale
ScalingActive True ValidMetricFound the HPA was able to successfully calculate a replica count from pods metric http_request
ScalingLimited False DesiredWithinRange the desired replica count is within the acceptable range
Events:
----
<1> The horizontal pod autoscaler status messages.
// The above output and bullets from https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough/#appendix-horizontal-pod-autoscaler-status-conditions
The following is an example of a pod that is unable to scale:
----
Conditions:
Type Status Reason Message
---- ------ ------ -------
AbleToScale False FailedGetScale the HPA controller was unable to get the target's current scale: no matches for kind "ReplicationController" in group "apps"
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Warning FailedGetScale 6s (x3 over 36s) horizontal-pod-autoscaler no matches for kind "ReplicationController" in group "apps"
----
The following is an example of a pod that could not obtain the needed metrics for scaling:
----
Conditions:
Type Status Reason Message
---- ------ ------ -------
AbleToScale True SucceededGetScale the HPA controller was able to get the target's current scale
ScalingActive False FailedGetResourceMetric the HPA was unable to compute the replica count: unable to get metrics for resource cpu: no metrics returned from heapster
----
The following is an example of a pod where the requested autoscaling was less than the required minimums:
----
Conditions:
Type Status Reason Message
---- ------ ------ -------
AbleToScale True ReadyForNewScale the last scale time was sufficiently old as to warrant a new scale
ScalingActive True ValidMetricFound the HPA was able to successfully calculate a replica count from pods metric http_request
ScalingLimited False DesiredWithinRange the desired replica count is within the acceptable range
----

84
modules/nodes-pods-autoscaling-status-viewing.adoc Normal file
View File

@@ -0,0 +1,84 @@
// Module included in the following assemblies:
//
// * nodes/nodes-pods-autoscaling-about.adoc
[id='nodes-pods-autoscaling-status-viewing_{context}']
= Viewing horizontal pod autoscaler status conditions
You can view the status conditions set on a pod by the horizontal pod autoscaler (HPA).
[NOTE]
====
The horizontal pod autoscaler status conditions are available with the `v2beta1` version of the
autoscaling API.
====
.Prerequisites
In order to use horizontal pod autoscalers, your cluster administrator must have properly configured cluster metrics.
You can use the `oc describe PodMetrics <pod-name>` command to determine if metrics are configured. If metrics are
configured, the output appears similar to the following, with `Cpu` and `Memory` displayed under `Usage`.
----
$ oc describe PodMetrics openshift-kube-scheduler-ip-10-0-135-131.ec2.internal
Name: openshift-kube-scheduler-ip-10-0-135-131.ec2.internal
Namespace: openshift-kube-scheduler
Labels: <none>
Annotations: <none>
API Version: metrics.k8s.io/v1beta1
Containers:
Name: wait-for-host-port
Usage:
Memory: 0
Name: scheduler
Usage:
Cpu: 8m
Memory: 45440Ki
Kind: PodMetrics
Metadata:
Creation Timestamp: 2019-05-23T18:47:56Z
Self Link: /apis/metrics.k8s.io/v1beta1/namespaces/openshift-kube-scheduler/pods/openshift-kube-scheduler-ip-10-0-135-131.ec2.internal
Timestamp: 2019-05-23T18:47:56Z
Window: 1m0s
Events: <none>
----
.Procedure
To view the status conditions on a pod, use the following command with the name of the pod:
[source,bash]
----
$ oc describe hpa <pod-name>
----
For example:
[source,bash]
----
$ oc describe hpa cm-test
----
The conditions appear in the `Conditions` field in the output.
----
Name: cm-test
Namespace: prom
Labels: <none>
Annotations: <none>
CreationTimestamp: Fri, 16 Jun 2017 18:09:22 +0000
Reference: ReplicationController/cm-test
Metrics: ( current / target )
"http_requests" on pods: 66m / 500m
Min replicas: 1
Max replicas: 4
ReplicationController pods: 1 current / 1 desired
Conditions: <1>
Type Status Reason Message
---- ------ ------ -------
AbleToScale True ReadyForNewScale the last scale time was sufficiently old as to warrant a new scale
ScalingActive True ValidMetricFound the HPA was able to successfully calculate a replica count from pods metric http_request
ScalingLimited False DesiredWithinRange the desired replica count is within the acceptable range
----

36
nodes/pods/nodes-pods-autoscaling.adoc Normal file
View File

@@ -0,0 +1,36 @@
:context: nodes-pods-autoscaling
[id='nodes-pods-autoscaling']
= Automatically scaling pods
include::modules/common-attributes.adoc[]
toc::[]
As a developer, you can use a horizontal pod autoscaler (HPA) to
specify how {product-title} should automatically increase or decrease the scale of
a replication controller or deployment configuration, based on metrics collected
from the pods that belong to that replication controller or deployment
configuration.
// The following include statements pull in the module files that comprise
// the assembly. Include any combination of concept, procedure, or reference
// modules required to cover the user story. You can also include other
// assemblies.
include::modules/nodes-pods-autoscaling-about.adoc[leveloffset=+1]
include::modules/nodes-pods-autoscaling-creating.adoc[leveloffset=+1]
include::modules/nodes-pods-autoscaling-creating-cpu.adoc[leveloffset=+2]
include::modules/nodes-pods-autoscaling-creating-memory.adoc[leveloffset=+2]
include::modules/nodes-pods-autoscaling-status-about.adoc[leveloffset=+1]
include::modules/nodes-pods-autoscaling-status-viewing.adoc[leveloffset=+2]
== Additional resources
For more information on replication controllers and deployment controllers,
see xref:../../applications/deployments/what-deployments-are.adoc#what-deployments-are[Understanding Deployments and DeploymentConfigs].