Kubernetes HPA Container Metric Scaling

Kubernetes HPA Container Metric Scaling is the use of the ContainerResource metric type within a HorizontalPodAutoscaler, which scales based on CPU or memory utilization of a single named container within a multi-container pod, rather than the aggregate across every container as the standard Resource type computes. It addresses a specific limitation of pod-level resource metrics in workloads where sidecars or auxiliary containers would otherwise distort the scaling signal.

Why Container-Level Scaling Is Needed

The Problem With Aggregate Resource Metrics

The standard Resource metric type sums CPU or memory usage across every container in a pod and compares it against the sum of every container's resource request; when a pod includes a service mesh proxy, a logging agent, or another sidecar with a substantially different resource profile than the main application, this aggregate can obscure the actual application container's true utilization, causing the HPA to react to sidecar behavior rather than genuine application load.

Isolating the Signal to the Relevant Container

ContainerResource metrics target one specific named container, computing utilization or average value using only that container's usage and request, giving a scaling signal that reflects the primary workload's actual behavior independent of any sidecar's resource consumption pattern.

metrics:
- type: ContainerResource
  containerResource:
    name: cpu
    container: app
    target:
      type: Utilization
      averageUtilization: 70

Configuration Structure

Specifying the Target Container

The container field names the specific container within each pod whose metrics should be used; every pod belonging to the target workload must actually contain a container with this exact name, since the metric lookup fails for any pod lacking it.

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: api-service
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: api-service
  minReplicas: 3
  maxReplicas: 20
  metrics:
  - type: ContainerResource
    containerResource:
      name: memory
      container: app
      target:
        type: AverageValue
        averageValue: 512Mi

Combining With Other Metric Types

A single HPA can combine ContainerResource metrics for the primary application container with Resource or custom metrics for other purposes, allowing precise targeting of the specific signal that best represents scaling need without needing to choose exclusively between container-level and pod-level granularity.

Requirements and Limitations

Container Must Exist in Every Target Pod

Because the metric lookup is keyed to a specific container name, any variation in container naming across replicas of the same workload (which should not normally occur in a correctly configured Deployment or StatefulSet, but could arise from manual pod creation or unusual templating) would cause metric retrieval to fail for the mismatched pods.

Same Metrics Server Dependency as Resource Metrics

ContainerResource scaling relies on the same metrics-server infrastructure as standard Resource scaling — no additional custom metrics adapter is required, since container-level resource usage is already collected by the kubelet and exposed through the same summary API, just filtered to a specific container during HPA evaluation.

Practical Use Cases

Service Mesh Sidecar Environments

Workloads running with a service mesh's sidecar proxy injected into every pod are a primary use case for ContainerResource scaling, since the proxy's CPU usage under high connection volume can be substantial and unrelated to the application container's own processing load, making pod-level aggregate CPU a poor scaling signal in that environment.

Logging and Monitoring Sidecars

Similarly, a logging or metrics-collection sidecar with variable resource usage tied to log volume rather than application request volume benefits from being excluded via container-level targeting, keeping the HPA focused on the metric that actually correlates with the need for additional replicas.

Verifying Correct Behavior

Confirming the Right Container Is Measured

Comparing the HPA's reported current metric value against kubectl top pod --containers, which breaks down resource usage per container within a pod, confirms the ContainerResource metric is reading from the intended container and not inadvertently misconfigured to reference the wrong one.

kubectl top pod api-service-7d4f9-x2k1p --containers