Kubernetes HPA: Guia do Horizontal Pod Autoscaler

O Horizontal Pod Autoscaler (HPA) do Kubernetes ajusta automaticamente o número de réplicas de pods em um deployment, replica set ou stateful set com base em métricas observadas. Em vez de escalar manualmente as cargas de trabalho quando o tráfego aumenta às 2 da manhã, o HPA cuida disso por você. Neste guia você aprenderá como o HPA funciona internamente, como configurá-lo com métricas de CPU, memória e personalizadas, e como ajustar políticas de escalamento para cargas de trabalho em produção.

Pré-requisitos

Antes de configurar o HPA, certifique-se de ter:

• Um cluster Kubernetes em execução (v1.23+) — minikube, kind, ou um cluster gerenciado (EKS, GKE, AKS)
• kubectl instalado e configurado para se comunicar com seu cluster
• metrics-server implantado (a maioria dos clusters gerenciados o inclui por padrão)
• Familiaridade básica com Deployments e Services
• Um deployment com requests de CPU/memória definidos (o HPA não pode calcular utilização sem eles)

Verifique se o metrics-server está em execução:

kubectl get deployment metrics-server -n kube-system
kubectl top nodes
kubectl top pods

Se kubectl top retornar métricas, você está pronto para continuar.

Como o HPA Funciona

O HPA executa como um loop de controle no controller manager do Kubernetes, verificando métricas em um intervalo configurável (padrão: 15 segundos). Em cada iteração ele:

1. Obtém os valores de métricas atuais da API de métricas para todos os pods na carga de trabalho alvo
2. Calcula a contagem de réplicas desejada usando a fórmula:

$$ \text{réplicasDesejadas} = \lceil \text{réplicasAtuais} \times \frac{\text{valorMétricaAtual}}{\text{valorMétricaDesejado}} \rceil $$

3. Compara as réplicas desejadas com as réplicas atuais
4. Escala a carga de trabalho para cima ou para baixo se a proporção exceder uma tolerância configurável (padrão ±10%)

Por exemplo, se seu deployment tem 3 réplicas executando a 75% de CPU em média e seu alvo é 50%:

$$ \text{desejado} = \lceil 3 \times \frac{75}{50} \rceil = \lceil 4.5 \rceil = 5 $$

O HPA escalaria o deployment para 5 réplicas.

Comportamento de cooldown: O HPA usa janelas de estabilização para prevenir oscilações. Por padrão, eventos de scale-down usam uma janela de estabilização de 5 minutos — o HPA escolhe a contagem de réplicas mais alta recomendada dos últimos 5 minutos. O scale-up não tem janela de estabilização padrão, reagindo imediatamente aos aumentos de carga.

Configurando HPA com Métricas de CPU

Configuração Rápida com kubectl

A forma mais rápida de criar um HPA:

kubectl autoscale deployment my-app \
  --cpu-percent=50 \
  --min=2 \
  --max=10

Isso diz ao Kubernetes: mantenha a utilização média de CPU em 50% em todos os pods, com mínimo de 2 e máximo de 10 réplicas.

Manifesto YAML Completo

Para produção, defina o HPA como um manifesto YAML versionável:

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: my-app-hpa
  namespace: default
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: my-app
  minReplicas: 2
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 50
    - type: Resource
      resource:
        name: memory
        target:
          type: Utilization
          averageUtilization: 70

Aplique e monitore:

kubectl apply -f hpa.yaml
kubectl get hpa my-app-hpa --watch

A saída se parece com:

NAME         REFERENCE           TARGETS           MINPODS   MAXPODS   REPLICAS
my-app-hpa   Deployment/my-app   32%/50%, 45%/70%   2         10        3

Importante: Os containers do seu deployment devem ter solicitações de recursos definidas, ou o HPA não pode calcular percentuais de utilização:

resources:
  requests:
    cpu: "250m"
    memory: "256Mi"
  limits:
    cpu: "500m"
    memory: "512Mi"

Métricas Personalizadas e Métricas Externas

CPU e memória frequentemente são insuficientes para decisões de escalamento. Um serviço web pode ter CPU baixo mas uma grande fila de solicitações. O HPA v2 suporta três tipos de métricas:

Tipo de Métrica	Fonte	Exemplo
Resource	metrics-server	Utilização de CPU, memória
Pods	API de métricas personalizadas	Solicitações por segundo por pod
External	API de métricas externas	Profundidade de fila SQS, backlog do Pub/Sub

Configurando Métricas Personalizadas com Prometheus Adapter

Instale o prometheus-adapter para expor métricas do Prometheus através da API de métricas personalizadas do Kubernetes:

helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm install prometheus-adapter prometheus-community/prometheus-adapter \
  --namespace monitoring \
  --set prometheus.url=http://prometheus-server.monitoring.svc

Depois configure um HPA usando uma métrica personalizada:

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: my-app-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: my-app
  minReplicas: 2
  maxReplicas: 20
  metrics:
    - type: Pods
      pods:
        metric:
          name: http_requests_per_second
        target:
          type: AverageValue
          averageValue: "100"

Escalamento por Profundidade de Fila Externa

Para arquiteturas orientadas a eventos, escale com base em uma métrica externa como uma fila SQS:

metrics:
  - type: External
    external:
      metric:
        name: sqs_queue_length
        selector:
          matchLabels:
            queue: "order-processing"
      target:
        type: Value
        value: "30"

Isso escala seus pods consumidores para manter o comprimento da fila em torno de 30 mensagens.

HPA vs VPA vs Cluster Autoscaler

Característica	HPA	VPA	Cluster Autoscaler
O que escala	Número de réplicas de pods	Solicitações de CPU/memória por pod	Número de nós do cluster
Direção	Horizontal (mais pods)	Vertical (pods maiores)	Horizontal (mais nós)
Métricas usadas	CPU, memória, personalizadas, externas	Uso histórico de recursos	Pods pendentes de agendamento
Requer reinício	Não	Sim (recria pods)	Não (adiciona nós)
Melhor para	Apps sem estado, escaláveis horizontalmente	Apps de instância única com recursos variáveis	Acomodar o scale-up do HPA
Pode combinar	Sim, com Cluster Autoscaler	Não com HPA na mesma métrica	Sim, com HPA
Velocidade de reação	Segundos a minutos	Minutos (reinício de pod)	Minutos (provisionamento de nó)

Combinação recomendada: Use HPA para escalamento de cargas de trabalho + Cluster Autoscaler para escalamento de infraestrutura. Evite usar HPA e VPA na mesma métrica para o mesmo deployment — eles entrarão em conflito.

Cenário do Mundo Real

Considere uma plataforma de e-commerce que vê 10x mais tráfego durante vendas relâmpago. Seu deployment checkout-service normalmente lida com 50 solicitações/segundo com 3 réplicas.

Sem HPA: Seu engenheiro de plantão recebe um alerta à meia-noite, escala manualmente para 20 réplicas, e depois esquece de reduzir. Você paga por recursos ociosos por 3 dias.

Com HPA configurado:

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: checkout-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: checkout-service
  minReplicas: 3
  maxReplicas: 30
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 60
    - type: Pods
      pods:
        metric:
          name: http_requests_per_second
        target:
          type: AverageValue
          averageValue: "50"
  behavior:
    scaleUp:
      stabilizationWindowSeconds: 0
      policies:
        - type: Percent
          value: 100
          periodSeconds: 60
    scaleDown:
      stabilizationWindowSeconds: 300
      policies:
        - type: Percent
          value: 10
          periodSeconds: 60

Esta configuração:

• Escala para cima agressivamente — dobrando réplicas a cada 60 segundos quando CPU supera 60% ou taxa de solicitações supera 50 req/s por pod
• Escala para baixo conservadoramente — removendo apenas 10% das réplicas por minuto com janela de estabilização de 5 minutos
• Previne redução prematura após picos curtos de tráfego

Durante a venda relâmpago, o HPA escala de 3 para 25 réplicas em menos de 5 minutos. Após o tráfego diminuir, reduz gradualmente para 3 em aproximadamente 30 minutos.

Políticas de Escalamento e Comportamento

O campo behavior (autoscaling/v2) oferece controle preciso sobre a velocidade de escalamento:

behavior:
  scaleUp:
    stabilizationWindowSeconds: 0
    policies:
      - type: Percent
        value: 100
        periodSeconds: 15
      - type: Pods
        value: 4
        periodSeconds: 15
    selectPolicy: Max
  scaleDown:
    stabilizationWindowSeconds: 300
    policies:
      - type: Percent
        value: 10
        periodSeconds: 60
    selectPolicy: Min

Campos chave:

• stabilizationWindowSeconds — quanto tempo o HPA olha para trás para escolher a recomendação mais conservadora. Defina como 0 para scale-up imediato; 300 (5 min) para scale-down cauteloso.
• policies — define a velocidade de escalamento como percentual das réplicas atuais ou número absoluto de pods por período de tempo.
• selectPolicy — Max escolhe a política que permite mais mudança (agressivo), Min escolhe a mais conservadora, Disabled previne o escalamento naquela direção.

Padrões Comuns de Políticas

Scale-up rápido, scale-down lento (recomendado para a maioria das apps web):

scaleUp:
  stabilizationWindowSeconds: 0
  policies:
    - type: Percent
      value: 100
      periodSeconds: 15
scaleDown:
  stabilizationWindowSeconds: 300
  policies:
    - type: Pods
      value: 1
      periodSeconds: 60

Prevenir scale-down completamente (jobs batch):

scaleDown:
  selectPolicy: Disabled

Problemas Comuns e Casos Especiais

Atraso de métricas: O metrics-server coleta dados a cada 15 segundos, e o HPA avalia a cada 15 segundos. Isso significa que há um atraso de 15–30 segundos entre um pico de carga e a primeira decisão de escalamento. Para serviços sensíveis à latência, considere começar com mais minReplicas.

Solicitações de recursos ausentes: Se seus containers não definem requests de CPU ou memória, o HPA reporta <unknown> para utilização e não escalará. Sempre defina requests.

Sondas de prontidão importam: O HPA conta apenas pods Ready ao calcular métricas. Se novos pods levam 60 segundos para ficarem prontos, o HPA pode sobre-provisionar porque os pods existentes permanecem sobrecarregados durante a inicialização. Ajuste sondas de prontidão e considere sondas de inicialização para aplicações de arranque lento.

Conflitos com PodDisruptionBudget: Um PDB que permite zero pods indisponíveis pode bloquear o scale-down se o HPA tentar remover réplicas durante uma interrupção voluntária. Garanta que minAvailable do seu PDB seja menor que minReplicas do seu HPA.

Interação de múltiplas métricas: Quando o HPA avalia múltiplas métricas, calcula a contagem de réplicas desejada para cada métrica independentemente e escolhe o valor mais alto. Isso significa que um pico em uma única métrica pode acionar o escalamento mesmo que outras métricas estejam baixas.

Latência do HPA e Cluster Autoscaler: O HPA cria novos pods imediatamente, mas se nenhum nó tem capacidade, os pods permanecem em Pending até que o Cluster Autoscaler provisione novos nós (tipicamente 2–5 minutos em provedores de nuvem). Considere isso na sua estratégia de escalamento.

Métrica de objeto vs métrica de pods: Use o tipo Pods quando a métrica é por pod (taxa de solicitações). Use o tipo Object quando a métrica vem de um único objeto Kubernetes como um Ingress.

Resumo

• O HPA escala automaticamente réplicas de pods com base em métricas de CPU, memória, personalizadas ou externas
• A fórmula de escalamento é réplicasDesejadas = ceil(réplicasAtuais × métricaAtual / métricaAlvo)
• Sempre defina requests de CPU e memória nos seus containers — o HPA não funciona sem eles
• Use a API autoscaling/v2 para escalamento multi-métrica e políticas de comportamento
• Configure scale-up agressivo e scale-down conservador para cargas de produção
• Combine HPA com Cluster Autoscaler para escalamento elástico completo — evite combinar HPA e VPA na mesma métrica
• Métricas personalizadas via prometheus-adapter desbloqueiam escalamento baseado em métricas de negócio como taxa de solicitações ou profundidade de fila
• Teste sua configuração de HPA sob carga realista antes de depender dela em produção

Artigos Relacionados

• Kubernetes Fundamentals: Deploy Your First Cluster
• K3s Lightweight Kubernetes for Homelab
• Docker Compose Practical Guide for Sysadmins
• Terraform Infrastructure as Code Getting Started Guide