> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shiftlabs.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# HPAs

> Manage Kubernetes HPAs to automatically scale workloads based on metrics

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

<CardGroup cols={2}>
  <Card title="HPA" icon="scale">
    A controller that automatically adjusts the number of pod replicas based on metrics.
  </Card>

  <Card title="Target" icon="target">
    The workload resource (Deployment, ReplicaSet, StatefulSet) that the HPA scales.
  </Card>

  <Card title="Metrics" icon="chart-line">
    The measurements (CPU, memory, custom) used to determine scaling decisions.
  </Card>

  <Card title="Replicas" icon="copy">
    The number of pod instances, bounded by minReplicas and maxReplicas.
  </Card>
</CardGroup>

## 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

<Steps>
  <Step title="Select Cluster">
    Choose a cluster from the cluster dropdown.
  </Step>

  <Step title="Select Namespace">
    Choose a namespace or select "all" to view HPAs across all namespaces.
  </Step>

  <Step title="Filter and Search">
    Use the search box to find HPAs by name, namespace, or target. Filter by status (Active, Scaling, Inactive).
  </Step>
</Steps>

## How to View HPA Details

<Steps>
  <Step title="Find the HPA">
    Locate the HPA in the list.
  </Step>

  <Step title="Click HPA Name">
    Click on the HPA name to open the detail drawer.
  </Step>

  <Step title="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
  </Step>
</Steps>

## How to Create an HPA

<Steps>
  <Step title="Click Create HPA">
    Click the **Create HPA** button in the page header.
  </Step>

  <Step title="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
  </Step>

  <Step title="Select Namespace">
    Choose the target namespace for the HPA.
  </Step>

  <Step title="Create">
    Click **Create** to apply the manifest.
  </Step>
</Steps>

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

## How to Edit an HPA

<Steps>
  <Step title="Open Actions Menu">
    Click the actions menu (three dots) on the HPA row.
  </Step>

  <Step title="Click Edit YAML">
    Select **Edit YAML** to open the YAML editor.
  </Step>

  <Step title="Modify Spec">
    Edit the HPA specification. Common changes:

    * Adjust min/max replicas
    * Change metric thresholds
    * Add or remove metrics
  </Step>

  <Step title="Save">
    Click **Update** to apply changes.
  </Step>
</Steps>

## How to Delete an HPA

<Steps>
  <Step title="Open Actions Menu">
    Click the actions menu on the HPA row.
  </Step>

  <Step title="Click Delete">
    Select **Delete** from the menu.
  </Step>

  <Step title="Confirm">
    Confirm the deletion. The target workload will stop auto-scaling.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

## 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

```yaml theme={null}
metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 80
  - type: Resource
    resource:
      name: memory
      target:
        type: Utilization
        averageUtilization: 80
```

### Custom Metrics

```yaml theme={null}
metrics:
  - type: Pods
    pods:
      metric:
        name: requests_per_second
      target:
        type: AverageValue
        averageValue: 1000
```

## Scaling Behavior

HPA v2 supports configuring scaling behavior:

```yaml theme={null}
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

<AccordionGroup>
  <Accordion title="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`
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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`
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>