[RFE] hpa docs

_topic_map.yml

@@ -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

modules/nodes-pods-autoscaling-about.adoc

@@ -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.
+====

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

@@ -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
+----
+

modules/nodes-pods-autoscaling-creating-memory.adoc

@@ -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>
+----
+