HPAs

Horizontal Pod Autoscalers (HPAs) automatically scale the number of pod replicas in a Deployment, ReplicaSet, or StatefulSet based on observed metrics like CPU utilization, memory usage, or custom metrics.

Key Concepts

HPA

A controller that automatically adjusts the number of pod replicas based on metrics.

Target

The workload resource (Deployment, ReplicaSet, StatefulSet) that the HPA scales.

Metrics

The measurements (CPU, memory, custom) used to determine scaling decisions.

Replicas

The number of pod instances, bounded by minReplicas and maxReplicas.

Required Permissions

Action	Permission
View HPAs	`iam:project:infrastructure:kubernetes:read`
Create HPA	`iam:project:infrastructure:kubernetes:write`
Edit HPA	`iam:project:infrastructure:kubernetes:write`
Delete HPA	`iam:project:infrastructure:kubernetes:delete`

HPA Status Values

Status	Description
Active	HPA is active and current replicas match desired replicas
ScalingUp	HPA is scaling up (current < desired replicas)
ScalingDown	HPA is scaling down (current > desired replicas)
Inactive	HPA is inactive (desired replicas is 0)
ScalingLimited	Scaling is limited by min/max replica bounds
Unknown	Status cannot be determined

How to View HPAs

Select Cluster

Choose a cluster from the cluster dropdown.

Select Namespace

Choose a namespace or select “all” to view HPAs across all namespaces.

Filter and Search

Use the search box to find HPAs by name, namespace, or target. Filter by status (Active, Scaling, Inactive).

How to View HPA Details

Find the HPA

Locate the HPA in the list.

Click HPA Name

Click on the HPA name to open the detail drawer.

Review Details

View HPA information including:

Overview: Name, namespace, target, status, age
Replicas: Current, desired, min, and max replica counts
Metrics: Configured metrics and current values
Conditions: HPA controller conditions
Events: Recent scaling events

How to Create an HPA

Click Create HPA

Click the Create HPA button in the page header.

Write YAML

Enter the HPA manifest in YAML format. Key fields:

spec.scaleTargetRef - Target workload to scale
spec.minReplicas - Minimum replica count
spec.maxReplicas - Maximum replica count
spec.metrics - Metrics to trigger scaling

Select Namespace

Choose the target namespace for the HPA.

Create

Click Create to apply the manifest.

Ensure the target workload exists and has resource requests defined. HPAs need resource requests to calculate utilization percentages.

How to Edit an HPA

Open Actions Menu

Click the actions menu (three dots) on the HPA row.

Click Edit YAML

Select Edit YAML to open the YAML editor.

Modify Spec

Edit the HPA specification. Common changes:

Adjust min/max replicas
Change metric thresholds
Add or remove metrics

Save

Click Update to apply changes.

How to Delete an HPA

Open Actions Menu

Click the actions menu on the HPA row.

Click Delete

Select Delete from the menu.

Confirm

Confirm the deletion. The target workload will stop auto-scaling.

Deleting an HPA stops automatic scaling. The target workload will remain at its current replica count until manually scaled or a new HPA is created.

Metric Types

HPAs support several metric types:

Type	Description	Example
Resource	CPU or memory utilization	CPU at 80%
Pods	Custom metrics from pods	Requests per second
Object	Metrics from other Kubernetes objects	Queue length
External	Metrics from external systems	Cloud queue depth

Resource Metrics

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

Custom Metrics

metrics:
  - type: Pods
    pods:
      metric:
        name: requests_per_second
      target:
        type: AverageValue
        averageValue: 1000

Scaling Behavior

HPA v2 supports configuring scaling behavior:

spec:
  behavior:
    scaleDown:
      stabilizationWindowSeconds: 300
      policies:
        - type: Percent
          value: 10
          periodSeconds: 60
    scaleUp:
      stabilizationWindowSeconds: 0
      policies:
        - type: Percent
          value: 100
          periodSeconds: 15

Setting	Description
stabilizationWindowSeconds	Time to wait before scaling (prevents flapping)
policies	Rules for how quickly to scale

Troubleshooting

HPA shows 'unknown' for current metrics

Verify metrics-server is installed and running
Check target pods have resource requests defined
Wait for metrics collection (can take a few minutes)
Verify metrics API is accessible: kubectl top pods

HPA not scaling up

Check current replicas equals maxReplicas (at limit)
Verify metric thresholds are being exceeded
Check HPA conditions for errors
Ensure target workload exists and is not paused

HPA not scaling down

Check current replicas equals minReplicas (at minimum)
Verify stabilization window has passed
Check scale-down policies if configured
Review HPA events for scaling decisions

HPA scaling too aggressively

Increase stabilizationWindowSeconds
Adjust scale-down policies to be more gradual
Consider using multiple metrics for better decision making
Review and tune metric thresholds

Target workload not found

Verify the target exists in the same namespace
Check scaleTargetRef name and kind are correct
Ensure apiVersion matches the target resource

Custom metrics not working

Verify Prometheus Adapter or custom metrics API is configured
Check metric name matches exactly
Ensure metrics are being exported by pods
Test with kubectl get --raw /apis/custom.metrics.k8s.io/v1beta1

FAQ

What resources can HPAs scale?

HPAs can scale Deployments, ReplicaSets, and StatefulSets. The target must support the /scale subresource. DaemonSets cannot be scaled by HPAs.

How quickly does HPA respond to load changes?

HPA checks metrics every 15 seconds by default (configurable via --horizontal-pod-autoscaler-sync-period). Actual scaling depends on stabilization windows and policies.

What happens if I delete an HPA?

The target workload stays at its current replica count. Automatic scaling stops until a new HPA is created or you manually scale the workload.

Can I have multiple HPAs for one Deployment?

No. Only one HPA should target each workload. Multiple HPAs would conflict with each other’s scaling decisions.

What's the difference between HPA v1 and v2?

HPA v2 supports multiple metrics, custom metrics, external metrics, and configurable scaling behavior. v1 only supports CPU and basic scaling. Always use v2 (autoscaling/v2).

Do I need metrics-server for HPA?

Yes, for resource metrics (CPU/memory). Custom metrics require additional components like Prometheus Adapter. External metrics require an external metrics provider.

How do I prevent scaling during deployments?

Use the --horizontal-pod-autoscaler-downscale-stabilization flag or configure behavior.scaleDown.stabilizationWindowSeconds to delay scale-down decisions.

What if my pods don't have resource requests?

HPA cannot calculate utilization percentages without resource requests. Define CPU/memory requests on your containers for HPA to work correctly.

Getting Started

Infrastructure

Platform Services

CI/CD & Deployments

Pipeline & Helm

Performance Testing

Security

Mesh Networking

Access Management

Audit & Compliance

Settings

Key Concepts

HPA

Target

Metrics

Replicas

Required Permissions

HPA Status Values

How to View HPAs

How to View HPA Details

How to Create an HPA

How to Edit an HPA

How to Delete an HPA

Metric Types

Resource Metrics

Custom Metrics

Scaling Behavior

Troubleshooting

FAQ

​Key Concepts

HPA

Target

Metrics

Replicas

​Required Permissions

​HPA Status Values

​How to View HPAs

​How to View HPA Details

​How to Create an HPA

​How to Edit an HPA

​How to Delete an HPA

​Metric Types

​Resource Metrics

​Custom Metrics

​Scaling Behavior

​Troubleshooting

​FAQ

Key Concepts

Required Permissions

HPA Status Values

How to View HPAs

How to View HPA Details

How to Create an HPA

How to Edit an HPA

How to Delete an HPA

Metric Types

Resource Metrics

Custom Metrics

Scaling Behavior

Troubleshooting

FAQ