Added docs about container resource metric source for HPA (#23523)

* Added docs about container resource metric source for HPA

Signed-off-by: Arjun Naik <arjun.rn@gmail.com>

* Update content/en/docs/tasks/run-application/horizontal-pod-autoscale.md

Co-authored-by: Tim Bannister <tim@scalefactory.com>

* Update content/en/docs/tasks/run-application/horizontal-pod-autoscale.md

Co-authored-by: Tim Bannister <tim@scalefactory.com>

* Update content/en/docs/tasks/run-application/horizontal-pod-autoscale.md

Co-authored-by: Guy Templeton <guyjtempleton@googlemail.com>

Co-authored-by: Tim Bannister <tim@scalefactory.com>
Co-authored-by: Guy Templeton <guyjtempleton@googlemail.com>

content/en/docs/tasks/run-application/horizontal-pod-autoscale.md

@@ -234,6 +234,75 @@ the delay value is set too short, the scale of the replicas set may keep thrashi
 usual.
 {{< /note >}}
 
+## Support for resource metrics
+
+Any HPA target can be scaled based on the resource usage of the pods in the scaling target.
+When defining the pod specification the resource requests like `cpu` and `memory` should
+be specified. This is used to determine the resource utilization and used by the HPA controller
+to scale the target up or down. To use resource utilization based scaling specify a metric source
+like this:
+
+```yaml
+type: Resource
+resource:
+  name: cpu
+  target:
+    type: Utilization
+    averageUtilization: 60
+```
+With this metric the HPA controller will keep the average utilization of the pods in the scaling
+target at 60%. Utilization is the ratio between the current usage of resource to the requested
+resources of the pod. See [Algorithm](#algorithm-details) for more details about how the utilization
+is calculated and averaged.
+
+{{< note >}}
+Since the resource usages of all the containers are summed up the total pod utilization may not
+accurately represent the individual container resource usage. This could lead to situations where
+a single container might be running with high usage and the HPA will not scale out because the overall
+pod usage is still within acceptable limits.
+{{< /note >}}
+
+### Container Resource Metrics
+
+{{< feature-state for_k8s_version="v1.20" state="alpha" >}}
+
+`HorizontalPodAutoscaler` also supports a container metric source where the HPA can track the
+resource usage of individual containers across a set of Pods, in order to scale the target resource.
+This lets you configure scaling thresholds for the containers that matter most in a particular Pod.
+For example, if you have a web application and a logging sidecar, you can scale based on the resource
+use of the web application, ignoring the sidecar container and its resource use.
+
+If you revise the target resource to have a new Pod specification with a different set of containers,
+you should revise the HPA spec if that newly added container should also be used for
+scaling. If the specified container in the metric source is not present or only present in a subset
+of the pods then those pods are ignored and the recommendation is recalculated. See [Algorithm](#algorithm-details)
+for more details about the calculation. To use container resources for autoscaling define a metric
+source as follows:
+```yaml
+type: ContainerResource
+containerResource:
+  name: cpu
+  container: application
+  target:
+    type: Utilization
+    averageUtilization: 60
+```
+
+In the above example the HPA controller scales the target such that the average utilization of the cpu
+in the `application` container of all the pods is 60%.
+
+{{< note >}}
+If you change the name of a container that a HorizontalPodAutoscaler is tracking, you can
+make that change in a specific order to ensure scaling remains available and effective
+whilst the change is being applied. Before you update the resource that defines the container
+(such as a Deployment), you should update the associated HPA to track both the new and
+old container names. This way, the HPA is able to calculate a scaling recommendation
+throughout the update process.
+
+Once you have rolled out the container name change to the workload resource, tidy up by removing
+the old container name from the HPA specification.
+{{< /note >}}
+
 ## Support for multiple metrics
 
 Kubernetes 1.6 adds support for scaling based on multiple metrics. You can use the `autoscaling/v2beta2` API
@@ -441,4 +510,3 @@ behavior:
 * Design documentation: [Horizontal Pod Autoscaling](https://git.k8s.io/community/contributors/design-proposals/autoscaling/horizontal-pod-autoscaler.md).
 * kubectl autoscale command: [kubectl autoscale](/docs/reference/generated/kubectl/kubectl-commands/#autoscale).
 * Usage example of [Horizontal Pod Autoscaler](/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough/).
-