How to Scale Based on Custom Metrics in Kubernetes

To scale based on custom metrics in Kubernetes, use the HorizontalPodAutoscaler resource configured with a metrics section specifying your custom metric. You must have a metrics adapter like the Prometheus Adapter installed to expose these metrics to the Kubernetes API for autoscaling.

Syntax

The HorizontalPodAutoscaler (HPA) resource defines how Kubernetes scales pods based on metrics. The key parts are:

• apiVersion: Use autoscaling/v2 or higher for custom metrics support.
• kind: Always HorizontalPodAutoscaler.
• metadata.name: Name of the HPA resource.
• spec.scaleTargetRef: The deployment or resource to scale.
• spec.minReplicas and spec.maxReplicas: Limits for scaling.
• spec.metrics: Defines the custom metric to use for scaling.

yaml

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: example-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: example-deployment
  minReplicas: 1
  maxReplicas: 5
  metrics:
  - type: External
    external:
      metric:
        name: custom_metric_name
      target:
        type: Value
        value: "100"

Example

This example shows an HPA scaling a deployment named web-app based on a custom metric called requests_per_second exposed via Prometheus Adapter.

yaml

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: web-app-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: web-app
  minReplicas: 2
  maxReplicas: 10
  metrics:
  - type: External
    external:
      metric:
        name: requests_per_second
        selector:
          matchLabels:
            service: web-app
      target:
        type: Value
        value: "500"

Output

HorizontalPodAutoscaler "web-app-hpa" created

Common Pitfalls

• Missing metrics adapter: Kubernetes cannot scale on custom metrics without a metrics adapter like Prometheus Adapter installed and configured.
• Incorrect metric name or labels: The metric name and labels must exactly match what the adapter exposes.
• Using older API versions: Custom metrics require autoscaling/v2 or newer API version.
• Not setting target type correctly: Use Value or AverageValue depending on metric type.

yaml

Wrong example (missing metrics adapter):
apiVersion: autoscaling/v1
kind: HorizontalPodAutoscaler
metadata:
  name: wrong-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: web-app
  minReplicas: 1
  maxReplicas: 3
  targetCPUUtilizationPercentage: 50

Right example (with custom metric and adapter):
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: right-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: web-app
  minReplicas: 1
  maxReplicas: 3
  metrics:
  - type: External
    external:
      metric:
        name: custom_metric
      target:
        type: Value
        value: "100"

Quick Reference

Tips for scaling on custom metrics in Kubernetes:

• Install and configure a metrics adapter like Prometheus Adapter.
• Use autoscaling/v2 API version for HPA.
• Define metrics with type: External for custom metrics.
• Match metric names and labels exactly as exposed by the adapter.
• Set appropriate minReplicas and maxReplicas limits.

Key Takeaways

Use HorizontalPodAutoscaler with autoscaling/v2 API to scale on custom metrics.

Install a metrics adapter like Prometheus Adapter to expose custom metrics to Kubernetes.

Define custom metrics under the metrics section with type External in the HPA spec.

Ensure metric names and labels match exactly what the adapter provides.

Set sensible minReplicas and maxReplicas to control scaling limits.