Kubernetes HPA Object Metric Scaling

Kubernetes HPA Object Metric Scaling is the use of the Object metric type within a HorizontalPodAutoscaler, which scales a workload based on a metric describing a single Kubernetes object other than the pods being scaled themselves — most commonly an Ingress's request rate or a queue resource's backlog depth — rather than a value averaged across the target's own pods.

How Object Metrics Differ From Pods Metrics

A Single Value From a Named Object

Where Pods metrics average a per-pod value across every replica of the target, Object metrics retrieve a single metric value associated with one specific, named Kubernetes object, which may have no direct relationship to the target workload's own pods at all — an Ingress resource's total request rate, for example, describes traffic across potentially many backend services, not per-pod behavior.

metrics:
- type: Object
  object:
    metric:
      name: requests-per-second
    describedObject:
      apiVersion: networking.k8s.io/v1
      kind: Ingress
      name: api-gateway
    target:
      type: Value
      value: "2k"

Target Type: Value Versus AverageValue

Object metrics can use either Value (comparing the raw metric value from the described object directly against the target) or AverageValue (dividing the object's metric value by the current number of target pods before comparing), depending on whether the metric represents a total that should be distributed across replicas or an absolute threshold independent of replica count.

metrics:
- type: Object
  object:
    metric:
      name: queue-depth
    describedObject:
      apiVersion: v1
      kind: ConfigMap
      name: queue-status
    target:
      type: AverageValue
      averageValue: "30"

Common Use Cases

Scaling on Ingress or Load Balancer Traffic

A workload sitting behind a shared Ingress or load balancer can scale based on that front-facing object's aggregate request rate, useful when the relevant load signal is naturally associated with the entry point rather than easily attributed to individual backend pods, particularly when multiple services share the same Ingress.

Scaling on External Queue or Broker State

A worker deployment consuming from a message queue can scale based on a metric representing the queue's current backlog, retrieved from whatever object (a ConfigMap populated by an exporter, or a custom resource representing the queue) the metrics adapter is configured to expose that data through.

metrics:
- type: Object
  object:
    metric:
      name: pending-jobs
    describedObject:
      apiVersion: batch.example.com/v1
      kind: JobQueue
      name: order-processing-queue
    target:
      type: Value
      value: "500"

Requirements for Object Metrics

Custom Metrics API Backing

Like Pods metrics, Object metrics depend on a custom metrics API adapter capable of resolving a metric value for the specific object named in describedObject, meaning the adapter's configuration must explicitly support retrieving metrics scoped to that particular resource kind, not just to pods.

Correctly Identifying the Described Object

describedObject must precisely match an existing resource's apiVersion, kind, and name (and implicitly, the HPA's own namespace for namespaced objects); a mismatch — an outdated API version after an upgrade, for instance — causes the metric lookup to fail silently from the HPA's perspective, typically surfacing as a FailedGetObjectMetric condition.

kubectl describe hpa order-worker
# Warning FailedGetObjectMetric ... unable to get metric requests-per-second: no metrics returned from custom metrics API

Practical Considerations

Attribution Ambiguity With Shared Objects

Because an Object metric's source (an Ingress serving multiple backends, for instance) may not correspond one-to-one with the specific workload being scaled, care should be taken that the metric genuinely reflects load attributable to the target workload — scaling one backend service based on an Ingress's total traffic across several unrelated services can produce misleading scaling decisions if traffic to other services dominates the aggregate.

Combining With Other Metric Types

An HPA can combine an Object metric with Resource or Pods metrics simultaneously, in which case the final desired replica count is the maximum across all of them, allowing a workload to scale on whichever signal — CPU utilization or external queue depth — currently indicates the greater need, rather than requiring a single metric type to fully capture the workload's scaling requirements.