HPA integration with Metrics Server — the scaling loop

The HPA integration with the Metrics Server is the scaling loop. The HPA queries the metrics.k8s.io API for resource metrics, computes the desired replicas, and updates the Deployment. This lesson walks the integration, the scaling loop, the configuration, and the verification.

The HPA + Metrics Server

The HPA uses the Metrics Server for resource metrics:

flowchart LR
    A[HPA controller] --> B[metrics.k8s.io API]
    B --> C[Metrics Server]
    C --> D[Kubelet]
    A --> E[Deployment]
    E --> F[Update replicas]

The HPA controller queries the API and scales the Deployment.

The HPA configuration

The HPA configuration for resource metrics:

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: nginx-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: nginx
  minReplicas: 3
  maxReplicas: 30
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70

The HPA targets CPU utilization.

The scaling loop

The scaling loop:

sequenceDiagram
    participant HPA as HPA controller
    participant M as Metrics Server
    participant K as Kubelet
    participant D as Deployment
    loop every 15s
        HPA->>M: get pod metrics
        M->>K: get kubelet metrics
        K-->>M: CPU/memory
        M-->>HPA: aggregated metrics
        HPA->>HPA: compute desired replicas
        HPA->>D: update spec.replicas
        D->>D: scale Deployment
    end

The loop is the HPA’s heartbeat.

The replica computation

The replica computation:

Current replicas: 5
Current CPU utilization: 50% (average across pods)
Target CPU utilization: 70%

Desired replicas: ceil(5 * 50 / 70) = 4

The HPA scales down to 4 replicas.

Current replicas: 5
Current CPU utilization: 90% (average across pods)
Target CPU utilization: 70%

Desired replicas: ceil(5 * 90 / 70) = 7

The HPA scales up to 7 replicas.

The formula is the HPA’s algorithm.

The tolerance

The tolerance prevents oscillations:

Current replicas: 5
Current CPU utilization: 68%
Target CPU utilization: 70%

Desired replicas: ceil(5 * 68 / 70) = 5

The HPA does not scale (within tolerance).

The tolerance is 0.1 (10% of the target value).

The metrics query

The metrics query:

sequenceDiagram
    participant HPA as HPA controller
    participant API as API server
    participant M as Metrics Server
    HPA->>API: GET /apis/metrics.k8s.io/v1beta1/namespaces/default/pods
    API->>M: forward request
    M->>M: collect from kubelets
    M-->>API: metrics
    API-->>HPA: metrics

The query is the metrics path.

The HPA status

The HPA status:

kubectl get hpa nginx-hpa

NAME        REFERENCE          TARGETS   MINPODS   MAXPODS   REPLICAS
nginx-hpa   Deployment/nginx   50%/70%   3         30        5

The output shows the current utilization, the target, the min/max replicas, and the current replicas.

The HPA conditions

The HPA conditions:

kubectl describe hpa nginx-hpa

Status:
  Conditions:
    Type            Status  Reason              Message
    ----            ------  ------              -------
    AbleToScale     True    ReadyForNewScale    recommended size matches current size
    ScalingActive   True    ValidMetricFound    the HPA was able to successfully calculate a replica count from the cpu metric
    ScalingLimited  False   DesiredWithinRange  the desired count is within the acceptable range

The conditions are the HPA’s health.

The CPU vs memory targets

The CPU vs memory targets:

metrics:
- type: Resource
  resource:
    name: cpu
    target:
      type: Utilization
      averageUtilization: 70
- type: Resource
  resource:
    name: memory
    target:
      type: Utilization
      averageUtilization: 80

The HPA can target multiple metrics. The largest desired replica count is used.

The AverageValue vs Utilization

The AverageValue vs Utilization:

# Utilization (percentage of the request)
target:
  type: Utilization
  averageUtilization: 70

# AverageValue (absolute value)
target:
  type: AverageValue
  averageValue: "100m"

The Utilization requires the request; the AverageValue does not.

Cross-course references

• The HPA course (Part LXXXII) covers the algorithm.
• The Custom Metrics course covers the custom metrics.
• The Capacity Planning course (Part LXXXIV) covers the resource budgeting.

Quiz

Production discipline

• Use the Metrics Server for resource metrics. The canonical source.
• Use CPU for scaling. Memory is volatile.
• Set the requests correctly. The HPA needs the requests for Utilization.
• Test the HPA. Use load generation to verify the scaling.
• Monitor the HPA metrics. Prometheus exposes them.
• Document the HPA configuration. The target, the min/max, the rationale.

The HPA + Metrics Server integration is the canonical scaling loop. Operating it well is using the canonical source, the right metric, and the correct configuration.