Merge pull request #112863 from mburke5678/cqa-nodes-9-4

OSDOCS CQA NODES-9: Autoscaling and Miscellaneous IV

Author: mburke5678

modules/nodes-pods-vertical-autoscaler-about.adoc

@@ -6,7 +6,10 @@
 [id="nodes-pods-vertical-autoscaler-about_{context}"]
 = About the Vertical Pod Autoscaler Operator
 
-The Vertical Pod Autoscaler Operator (VPA) is implemented as an API resource and a custom resource (CR). The CR determines the actions for the VPA to take with the pods associated with a specific workload object, such as a daemon set, replication controller, and so forth, in a project.
+[role="_abstract"]
+To help you maintain the optimal CPU and memory usage for your pods, you can use the {product-title} Vertical Pod Autoscaler Operator (VPA).
+
+The VPA is implemented as an API resource and a custom resource (CR). The CR determines the actions for the VPA to take with the pods associated with a specific workload object, such as a daemon set, replication controller, and so forth, in a project.
 
 The VPA consists of three components, each of which has its own pod in the VPA namespace:
 

modules/nodes-pods-vertical-autoscaler-configuring.adoc

@@ -6,10 +6,13 @@
 [id="nodes-pods-vertical-autoscaler-configuring_{context}"]
 = Using the Vertical Pod Autoscaler Operator
 
-You can use the Vertical Pod Autoscaler Operator (VPA) by creating a VPA custom resource (CR). The CR indicates the pods to analyze and determines the actions for the VPA to take with those pods.
+[role="_abstract"]
+You can use the Vertical Pod Autoscaler Operator (VPA) to help you maintain the optimal CPU and memory usage for your pods by creating a VPA custom resource (CR). The CR indicates the pods to analyze and determines the actions for the VPA to take with those pods.
 
 You can use the VPA to scale built-in resources such as deployments or stateful sets, and custom resources that manage pods. For more information, see "About using the Vertical Pod Autoscaler Operator".
 
+The following procedure creates a VPA CR for a specific workload object.
+
 .Prerequisites
 
 * Ensure the workload object that you want to autoscale exists.
@@ -18,8 +21,6 @@ You can use the VPA to scale built-in resources such as deployments or stateful
 
 .Procedure
 
-To create a VPA CR for a specific workload object:
-
 . Change to the location of the project for the workload object you want to scale.
 
 .. Create a VPA CR YAML file:
@@ -33,26 +34,28 @@ metadata:
 spec:
   targetRef:
     apiVersion: "apps/v1"
-    kind:       Deployment <1>
-    name:       frontend <2>
+    kind:       Deployment
+    name:       frontend
   updatePolicy:
-    updateMode: "InPlaceOrRecreate" <3>
-  resourcePolicy: <4>
+    updateMode: "InPlaceOrRecreate"
+  resourcePolicy:
     containerPolicies:
     - containerName: my-opt-sidecar
       mode: "Off"
-  recommenders: <5>
+  recommenders:
     - name: my-recommender
 ----
-<1> Specify the type of workload object you want this VPA to manage: `Deployment`, `StatefulSet`, `Job`, `DaemonSet`, `ReplicaSet`, or `ReplicationController`.
-<2> Specify the name of an existing workload object you want this VPA to manage.
-<3> Specify the VPA mode:
+where:
+
+`spec.targetRef.kind`:: Specifies the type of workload object you want this VPA to manage: `Deployment`, `StatefulSet`, `Job`, `DaemonSet`, `ReplicaSet`, or `ReplicationController`.
+`spec.targetRef.name`:: Specifies the name of an existing workload object you want this VPA to manage.
+`spec.updatePolicy.updateMode`:: Specifies the VPA mode:
 * `InPlaceOrRecreate` to automatically apply the recommended resources on pods associated with the workload object. The VPA attempts to update the workload object with the new resources without re-creating the pod. If the VPA is unable to update the object in place, the VPA re-creates it.
 * `Recreate` to automatically apply the recommended resources on pods associated with the workload object. The VPA terminates existing pods and creates new pods with the recommended resource limits and requests. Use the `Recreate` mode only if you need to ensure that the pods restart whenever the resource request changes.
 * `Initial` to automatically apply the recommended resources to newly-created pods associated with the workload object. The VPA does not update the pods as it learns new resource recommendations.
 * `Off` to only generate resource recommendations for the pods associated with the workload object. The VPA does not update the pods as it learns new resource recommendations and does not apply the recommendations to new pods.
-<4> Optional. Specify the containers you want to opt-out and set the mode to `Off`.
-<5> Optional. Specify an alternative recommender.
+`spec.resourcePolicy`:: Specifies the containers you want to opt-out and set the mode to `Off`. This parameter is optional.
+`spec.recommenders`:: Specifies an alternative recommender. This parameter is optional.
 
 .. Create the VPA CR:
 +
@@ -85,16 +88,16 @@ status:
   recommendation:
     containerRecommendations:
     - containerName: frontend
-      lowerBound: <1>
+      lowerBound:
         cpu: 25m
         memory: 262144k
-      target: <2>
+      target:
         cpu: 25m
         memory: 262144k
-      uncappedTarget: <3>
+      uncappedTarget:
         cpu: 25m
         memory: 262144k
-      upperBound: <4>
+      upperBound:
         cpu: 262m
         memory: "274357142"
     - containerName: backend
@@ -113,7 +116,11 @@ status:
 
 ...
 ----
-<1> `lowerBound` is the minimum recommended resource levels.
-<2> `target` is the recommended resource levels.
-<3> `upperBound` is the highest recommended resource levels.
-<4> `uncappedTarget` is the most recent resource recommendations.
+where:
+
+`status.recommendation.containerRecommendations`:: Specifies the minimum and maximum recommended resource levels for the container:
+* `containerName` is the container for the recommended resource levels.
+* `lowerBound` is the minimum recommended resource levels.
+* `target` is the recommended resource levels.
+* `upperBound` is the highest recommended resource levels.
+* `uncappedTarget` is the most recent resource recommendations.

modules/nodes-pods-vertical-autoscaler-custom-resource.adoc

@@ -6,7 +6,8 @@
 [id="nodes-pods-vertical-autoscaler-custom-resource_{context}"]
 = Example custom resources for the Vertical Pod Autoscaler
 
-The Vertical Pod Autoscaler Operator (VPA) can update not only built-in resources such as deployments or stateful sets, but also custom resources that manage pods.
+[role="_abstract"]
+You can use the Vertical Pod Autoscaler Operator (VPA) to update custom resources that manage pods, not just built-in resources such as deployments or stateful sets.
 
 To use the VPA with a custom resource when you create the `CustomResourceDefinition` (CRD) object, you must configure the `labelSelectorPath` field in the `/scale` subresource. The `/scale` subresource creates a `Scale` object. The `labelSelectorPath` field defines the JSON path inside the custom resource that corresponds to `status.selector` in the `Scale` object and in the custom resource. The following is an example of a `CustomResourceDefinition` and a `CustomResource` that fulfills these requirements, along with a `VerticalPodAutoscaler` definition that targets the custom resource. The following example shows the `/scale` subresource contract.
 
@@ -50,7 +51,7 @@ spec:
       scale:
         specReplicasPath: .spec.replicas
         statusReplicasPath: .status.replicas
-        labelSelectorPath: .spec.selector <1>
+        labelSelectorPath: .spec.selector
   scope: Namespaced
   names:
     plural: scalablepods
@@ -59,7 +60,9 @@ spec:
     shortNames:
     - spod
 ----
-<1> Specifies the JSON path that corresponds to `status.selector` field of the custom resource object.
+where:
+
+`spec.subresources.scale.labelSelectorPath`:: Specifies the JSON path that corresponds to `status.selector` field of the custom resource object.
 
 .Example custom CR
 [source,yaml]
@@ -70,10 +73,12 @@ metadata:
   name: scalable-cr
   namespace: default
 spec:
-  selector: "app=scalable-cr" <1>
+  selector: "app=scalable-cr"
   replicas: 1
 ----
-<1> Specify the label type to apply to managed pods. This is the field that the `labelSelectorPath` references in the custom resource definition object.
+where:
+
+`spec.selector`:: Specifies the label type to apply to managed pods. This is the field that the `labelSelectorPath` references in the custom resource definition object.
 
 .Example VPA object
 [source,yaml]

modules/nodes-pods-vertical-autoscaler-custom.adoc

@@ -6,7 +6,10 @@
 [id="nodes-pods-vertical-autoscaler-custom_{context}"]
 = Using an alternative recommender
 
-You can use your own recommender to autoscale based on your own algorithms. If you do not specify an alternative recommender, {product-title} uses the default recommender, which suggests CPU and memory requests based on historical usage. Because there is no universal recommendation policy that applies to all types of workloads, you might want to create and deploy different recommenders for specific workloads.
+[role="_abstract"]
+You can use your own recommender to autoscale based on your own algorithms. If you do not specify an alternative recommender, {product-title} uses the default recommender, which suggests CPU and memory requests based on historical usage. 
+
+Because there is no universal recommendation policy that applies to all types of workloads, you might want to create and deploy different recommenders for specific workloads.
 
 For example, the default recommender might not accurately predict future resource usage when containers exhibit certain resource behaviors. Examples are cyclical patterns that alternate between usage spikes and idling as used by monitoring applications, or recurring and repeating patterns used with deep learning applications. Using the default recommender with these usage behaviors might result in significant over-provisioning and Out of Memory (OOM) kills for your applications.
 
@@ -17,21 +20,21 @@ For example, the default recommender might not accurately predict future resourc
 Instructions for how to create a recommender are beyond the scope of this documentation.
 ====
 
-.Procedure
+The following procedure shows how to use an alternative recommender for your pods.
 
-To use an alternative recommender for your pods:
+.Procedure
 
 . Create a service account for the alternative recommender and bind that service account to the required cluster role:
 +
 [source,yaml]
 ----
-apiVersion: v1 <1>
+apiVersion: v1
 kind: ServiceAccount
 metadata:
   name: alt-vpa-recommender-sa
   namespace: <namespace_name>
 ---
-apiVersion: rbac.authorization.k8s.io/v1 <2>
+apiVersion: rbac.authorization.k8s.io/v1
 kind: ClusterRoleBinding
 metadata:
   name: system:example-metrics-reader
@@ -44,7 +47,7 @@ subjects:
   name: alt-vpa-recommender-sa
   namespace: <namespace_name>
 ---
-apiVersion: rbac.authorization.k8s.io/v1 <3>
+apiVersion: rbac.authorization.k8s.io/v1
 kind: ClusterRoleBinding
 metadata:
   name: system:example-vpa-actor
@@ -57,7 +60,7 @@ subjects:
   name: alt-vpa-recommender-sa
   namespace: <namespace_name>
 ---
-apiVersion: rbac.authorization.k8s.io/v1 <4>
+apiVersion: rbac.authorization.k8s.io/v1
 kind: ClusterRoleBinding
 metadata:
   name: system:example-vpa-target-reader-binding
@@ -70,10 +73,13 @@ subjects:
   name: alt-vpa-recommender-sa
   namespace: <namespace_name>
 ----
-<1> Creates a service account for the recommender in the namespace that displays the recommender.
-<2> Binds the recommender service account to the `metrics-reader` role. Specify the namespace for where to deploy the recommender.
-<3> Binds the recommender service account to the `vpa-actor` role. Specify the namespace for where to deploy the recommender.
-<4> Binds the recommender service account to the `vpa-target-reader` role. Specify the namespace for where to display the recommender.
++
+--
+* The `alt-vpa-recommender-sa` object creates a service account for the recommender in the namespace that displays the recommender.
+* The `system:metrics-reader` object binds the recommender service account to the `metrics-reader` role. Specify the namespace for where to deploy the recommender.
+* The `system:example-vpa-actor` object binds the recommender service account to the `vpa-actor` role. Specify the namespace for where to deploy the recommender.
+* The `system:example-vpa-target-reader-binding` object binds the recommender service account to the `vpa-target-reader` role. Specify the namespace for where to display the recommender.
+--
 
 . To add the alternative recommender to the cluster, create a `Deployment` object similar to the following:
 +
@@ -94,9 +100,9 @@ spec:
       labels:
         app: alt-vpa-recommender
     spec:
-      containers: <1>
+      containers:
       - name: recommender
-        image: quay.io/example/alt-recommender:latest <2>
+        image: quay.io/example/alt-recommender:latest
         imagePullPolicy: Always
         resources:
           limits:
@@ -115,15 +121,16 @@ spec:
               - ALL
           seccompProfile:
             type: RuntimeDefault
-      serviceAccountName: alt-vpa-recommender-sa <3>
+      serviceAccountName: alt-vpa-recommender-sa
       securityContext:
         runAsNonRoot: true
 ----
+where:
 +
 --
-<1> Creates a container for your alternative recommender.
-<2> Specifies your recommender image.
-<3> Associates the service account that you created for the recommender.
+`spec.template.spec.containers`:: Specifies a container for your alternative recommender.
+`spec.template.spec.containers.image`:: Specifies your recommender image.
+`spec.template.spec.serviceAccountName`:: Specifies the service account that you created for the recommender.
 --
 +
 A new pod is created for the alternative recommender in the same namespace.
@@ -155,11 +162,13 @@ metadata:
   namespace: <namespace_name>
 spec:
   recommenders:
-    - name: alt-vpa-recommender <1>
+    - name: alt-vpa-recommender
   targetRef:
     apiVersion: "apps/v1"
-    kind:       Deployment <2>
+    kind:       Deployment
     name:       frontend
 ----
-<1> Specifies the name of the alternative recommender deployment.
-<2> Specifies the name of an existing workload object you want this VPA to manage.
+where:
+
+`spec.recommenders.name`:: Specifies the name of the alternative recommender deployment.
+`spec.targetRef.kind`:: Specifies the name of an existing workload object you want this VPA to manage.

modules/nodes-pods-vertical-autoscaler-install.adoc

@@ -6,7 +6,8 @@
 [id="nodes-pods-vertical-autoscaler-install_{context}"]
 = Installing the Vertical Pod Autoscaler Operator
 
-You can use the {product-title} web console to install the Vertical Pod Autoscaler Operator (VPA).
+[role="_abstract"]
+You can install the Vertical Pod Autoscaler Operator (VPA) by using the {product-title} web console.
 
 ifdef::openshift-origin[]
 .Prerequisites