Update hpa.md

docs/tasks/administer-federation/hpa.md

@@ -1,17 +1,20 @@
 ---
-title: Federated horizontal pod autoscalers (HPA)
+title: Federated Horizontal Pod Autoscalers (HPA)
 ---
 
 {% capture overview %}
+
+{% include feature-state-alpha.md %}
+
 This guide explains how to use federated horizontal pod autoscalers (HPAs) in the federation control plane.
 
 HPAs in the federation control plane are similar to the traditional [Kubernetes
 HPAs](/docs/tasks/run-application/horizontal-pod-autoscale/), and provide the same functionality.
-Creating a HPA targeting a federated object in the federation control plane ensures that the
+Creating an HPA targeting a federated object in the federation control plane ensures that the
 desired number of replicas of the target object are scaled across the registered clusters,
 instead of a single cluster. Also, the control plane keeps monitoring the status of each
 individual HPA in the federated clusters and ensures the workload replicas move where they are
-needed most by manipulating the min and max limits of the HPA objects into the federated clusters.
+needed most by manipulating the min and max limits of the HPA objects in the federated clusters.
 {% endcapture %}
 
 {% capture prerequisites %}
@@ -22,19 +25,19 @@ needed most by manipulating the min and max limits of the HPA objects into the f
 general and [HPAs](/docs/tasks/run-application/horizontal-pod-autoscale/) in particular.
 
 The federated HPA is an alpha feature. The API is not enabled by default on the
-federated apiserver. To use this feature, the user or the admin deploying the federation control
-plane needs to run the federated apiserver with option `--runtime-config=api/all=true` to
+federated API server. To use this feature, the user or the admin deploying the federation control
+plane needs to run the federated API server with option `--runtime-config=api/all=true` to
 enable all APIs, including alpha APIs. Additionally, the federated HPA only works
 when used with CPU utilization metrics.
 {% endcapture %}
 
 {% capture steps %}
 
-## Creating a Federated HPA
+## Creating a federated HPA
 
 The API for federated HPAs is 100% compatible with the
 API for traditional Kubernetes HPA. You can create an HPA by sending
-a request to the federation apiserver.
+a request to the federation API server.
 
 You can do that with [kubectl](/docs/user-guide/kubectl/) by running:
 
@@ -56,17 +59,17 @@ spec:
 EOF
 ```
 
-The '--context=federation-cluster' flag tells kubectl to submit the
+The `--context=federation-cluster` flag tells `kubectl` to submit the
 request to the federation API server instead of sending it to a Kubernetes
 cluster.
 
 Once a federated HPA is created, the federation control plane partitions and
-creates the HPA in all underlying Kubernetes clusters. As of `kubernetes V1.7`
+creates the HPA in all underlying Kubernetes clusters. As of Kubernetes V1.7,
 [cluster selectors](docs/tasks/administer-federation/cluster/#clusterselector-annotation)
-can also be used to restrict any federated object, including the HPAs into a subset
+can also be used to restrict any federated object, including the HPAs in a subset
 of clusters.
 
-You can verify the creation by checking each of the underlying clusters. For example, with a context named 'gce-asia-east1a'
+You can verify the creation by checking each of the underlying clusters. For example, with a context named `gce-asia-east1a`
 configured in your client for your cluster in that zone:
 
 ```shell
@@ -86,85 +89,85 @@ than or equal to the minimum specified on the federated HPA object.
 By default, first max replicas are spread equally in all the underlying clusters, then min replicas are distributed to those clusters that received their maximum value. This means
 that each cluster will get an HPA if the specified max replicas are greater than
 the total clusters participating in this federation, and some clusters will be
-skipped if specified max replicas are lesser than the total clusters participating
-in this federation.
+skipped if specified max replicas are less than the total clusters participating
+in the federation.
 
 For example: if you have 3 registered clusters and you create a federated HPA with
 `spec.maxReplicas = 9`, and `spec.minReplicas = 2`, then each HPA in the 3 clusters
 will get `spec.maxReplicas=3` and `spec.minReplicas = 1`.
 
-Currently the default distribution is only available on the federated HPA, but in
-future users preferences could also be specified to control and/or restrict this
+Currently the default distribution is only available on the federated HPA, but in the
+future, users preferences could also be specified to control and/or restrict this
 distribution.
 
 ## Updating a federated ReplicaSet
 
 You can update a federated HPA as you would update a Kubernetes
 HPA; however, for a federated HPA, you must send the request to
-the federation apiserver instead of sending it to a specific Kubernetes cluster.
+the federation API server instead of sending it to a specific Kubernetes cluster.
 The Federation control plane ensures that whenever the federated HPA is
 updated, it updates the corresponding HPA in all underlying clusters to
 match it.
 
-If your update includes a change in number of replicas, the federation
+If your update includes a change in the number of replicas, the federation
 control plane will change the number of replicas in underlying clusters to
-ensure that the sum of the max and min replica remains matched as specified
-in the previous section above.
+ensure that the sum of the max and min replicas remains matched as specified
+in the previous section.
 
-## Deleting a Federated HPA
+## Deleting a federated HPA
 
 You can delete a federated HPA as you would delete a Kubernetes
 HPA; however, for a federated HPA, you must send the request to
-the federation apiserver instead of sending it to a specific Kubernetes cluster.
+the federation API server instead of sending it to a specific Kubernetes cluster.
 It should also be noted that for the federated resource to be deleted from
 all underlying clusters, [cascading deletion](docs/concepts/cluster-administration/federation/#cascading-deletion)
 should be used.
 
-For example, you can do that using kubectl by running:
+For example, you can do that using `kubectl` by running:
 
 ```shell
 kubectl --context=federation-cluster delete HPA php-apache
 ```
 
 ## Alternative ways to use federated HPA
 
-To a `federation user` interacting with federated control plane (or simply federation),
-the interaction is almost identical as interacting with a normal k8s cluster (but
-with a limited set of APIs that are federated). As both deployments and
-horizontalpodautoscalers are now federated, `kubectl` commands like `kubectl run`
-and `kubectl autoscale` work on federation. Given this fact the mechanism specified in
+To a federation user interacting with federated control plane (or simply federation),
+the interaction is almost identical to interacting with a normal Kubernetes cluster (but
+with a limited set of APIs that are federated). As both Deployments and
+HorizontalPodAutoscalers are now federated, `kubectl` commands like `kubectl run`
+and `kubectl autoscale` work on federation. Given this fact, the mechanism specified in
 [horizontal pod autoscaler walkthrough](/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough)
 will also work when used with federation.
 Care however will need to be taken that when
-[generating load on a target deployment](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough/#step-three-increase-load)
+[generating load on a target deployment](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough/#step-three-increase-load),
 it should be done against a specific federated cluster (or multiple clusters) not the federation.
 
 ## Conclusion
 
 The use of federated HPA is to ensure workload replicas move to the cluster(s) where
 they are needed most, or in other words where the load is beyond expected threshold.
-Federated HPA feature achieves this by manipulating the min and max replicas on the
+The federated HPA feature achieves this by manipulating the min and max replicas on the
 HPAs it creates in the federated clusters. It does not directly monitor the target
-object metrics from the federated clusters. It actually relies on the in cluster HPA
-controllers to monitor the metrics and update relevant fields. The in cluster HPA
+object metrics from the federated clusters. It actually relies on the in-cluster HPA
+controllers to monitor the metrics and update relevant fields. The in-cluster HPA
 controller monitors the target pod metrics and updates the fields like desired
 replicas (after metrics based calculations) and current replicas (observing the
-current status of in cluster pods). The federate HPA controller on the other hand
-monitors only the cluster specific HPA object fields and updates the min replica and
-max replica fields of those in cluster HPA objects which have replicas matching thresholds.
+current status of in cluster pods). The federated HPA controller, on the other hand,
+monitors only the cluster-specific HPA object fields and updates the min replica and
+max replica fields of those in cluster HPA objects, which have replicas matching thresholds.
 
-For example: The cluster which has both desired replicas and current replicas same as the max replicas
+For example, if a cluster has both desired replicas and current replicas the same as the max replicas,
 and averaged current CPU utilization still higher than the target CPU utilization (all of which
-are fields on local HPA object) would mean that the target app in this particular cluster
+are fields on local HPA object), then the target app in this cluster
 needs more replicas, and the scaling is currently restricted by max replicas set on this local
 HPA object. In such a scenario, the federated HPA controller scans all clusters and tries to
-find clusters which do not have such a condition (meaning the the desired replicas are lesser
-than the max and current averaged cpu utilization is lower then the threshold). If it finds such
+find clusters which do not have such a condition (meaning the the desired replicas are less
+than the max, and current averaged cpu utilization is lower then the threshold). If it finds such
 a cluster, it reduces the max replica on the HPA in this cluster and increases the max replicas
 on the HPA in the cluster which needed the replicas.
 
-There are many other similar conditions which federated HPA controller checks and moves the max
-replicas and min replicas around the local HPAs in federated clusters to eventually ensure, that
+There are many other similar conditions which the federated HPA controller checks and moves the max
+replicas and min replicas around the local HPAs in federated clusters to eventually ensure that
 the replicas move (or remain) in the cluster(s) which need them.
 
 For more information, see ["federated HPA design proposal"](https://github.com/kubernetes/community/pull/593).