# Autoscaling Kubernetes: Guia Prático de HPA em 5 Passos

> O HorizontalPodAutoscaler (HPA) do Kubernetes ajusta automaticamente o número de réplicas de um workload com base em métricas como CPU e memória. O guia prático de autoscaling horizontal apresenta cinco passos para configurar o HPA, incluindo pré-requisitos, implementação e erros comuns. A configuração exige o Metrics Server ativo e limites de recursos definidos nos pods. O HPA escala réplicas entre mínimos e máximos conforme a demanda observada.

*Pingobox · Apps e Software · 12 de agosto de 2026 · Gustavo Sequeira*

O autoscaling horizontal no Kubernetes ajusta o número de réplicas de um workload automaticamente, com base em métricas como CPU e memória. Este guia mostra como configurar um HorizontalPodAutoscaler (HPA) de forma prática, cobrindo pré-requisitos, passos de implementação e erros

Autoscaling horizontal no Kubernetes ajusta o número de réplicas de um Deployment ou StatefulSet automaticamente, com base em métricas observadas, como uso de CPU ou memória. A ferramenta nativa para isso é o HorizontalPodAutoscaler (HPA), que consulta o Metrics Server e altera a quantidade de pods para atender à demanda. Este guia cobre o caminho completo, de pré-requisitos a validação, em cinco passos práticos.

## Pré-requisitos

Antes de começar, você precisa de um cluster Kubernetes funcional (versão 1.23 ou superior é recomendada, mas HPA existe desde a 1.1), acesso via kubectl e permissão para criar recursos no namespace desejado. O passo mais crítico é garantir que o Metrics Server esteja instalado, pois sem ele o HPA não tem dados para decidir.

## Passo 1: Instalar o Metrics Server

O Metrics Server coleta métricas de uso de CPU e memória de cada nó e pod. Sem ele, o comando kubectl top nodes retorna erro e o HPA fica sem fonte de dados.

Verifique se está instalado com kubectl get deployment metrics-server -n kube-system. Se não existir, instale a versão mais recente do manifesto oficial do projeto Metrics Server (disponível no repositório kubernetes-sigs/metrics-server no GitHub). Em clusters locais como minikube, basta habilitar o addon: minikube addons enable metrics-server.

Erro comum: esquecer de ajustar a flag --kubelet-insecure-tls em clusters que não usam certificados TLS válidos, o que impede a coleta de métricas.

## Passo 2: Definir recursos nos containers

O HPA só funciona se os pods tiverem limites de recursos definidos. Sem requests e limits de CPU ou memória no spec do container, o autoscaler não tem referência para calcular a utilização.

No seu Deployment, adicione:

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

Dica: use requests realistas, baseados em testes de carga. Se o request for muito baixo, o HPA escala cedo demais; se for alto, pode não escalar quando necessário.

## Passo 3: Criar o HorizontalPodAutoscaler

Com o Metrics Server ativo e recursos definidos, crie o HPA apontando para o workload. A forma mais direta é via kubectl:

kubectl autoscale deployment meu-app --cpu-percent=60 --min=2 --max=10

Isso cria um HPA que mantém a utilização média de CPU em torno de 60%, com mínimo de 2 e máximo de 10 réplicas. Para controle mais fino, use um manifesto YAML:

apiVersion: autoscaling/v2 kind: HorizontalPodAutoscaler metadata: name: meu-app-hpa spec: scaleTargetRef: apiVersion: apps/v1 kind: Deployment name: meu-app minReplicas: 2 maxReplicas: 10 metrics:

- type: Resource

resource: name: cpu target: type: Utilization averageUtilization: 60

A API autoscaling/v2 é a versão estável desde o Kubernetes 1.23. Evite a v1, que só suporta CPU e é limitada.

## Passo 4: Validar o funcionamento

Aplique o manifesto com kubectl apply -f hpa.yaml e verifique o status com kubectl get hpa. A coluna TARGETS mostra a utilização atual versus a desejada. Se aparecer , o Metrics Server não está entregando dados.

Para testar, gere carga com uma ferramenta como kubectl run -i --tty load-generator --image=busybox -- /bin/sh -c "while true; do wget -q -O- http://meu-app-service; done". Observe o número de réplicas aumentar após alguns minutos. O HPA verifica as métricas a cada 15 segundos, mas a decisão de escala pode levar de 1 a 2 minutos para refletir.

## Passo 5: Ajustar parâmetros de comportamento

O HPA tem opções de comportamento (behavior) para controlar a velocidade de escala, evitando flutuações bruscas. Por exemplo, para limitar o scale down a 1 pod por minuto:

behavior: scaleDown: stabilizationWindowSeconds: 300 policies:

- type: Pods

value: 1 periodSeconds: 60

Isso impede que o cluster desligue pods rapidamente quando a carga cai, útil para aplicações com picos intermitentes. O stabilizationWindowSeconds define o tempo de espera antes de reduzir réplicas.

## Checklist rápido

- [ ] Metrics Server instalado e kubectl top nodes funcionando
- [ ] Containers com requests e limits definidos
- [ ] HPA criado com autoscaling/v2
- [ ] HPA exibindo TARGETS com valores numéricos, não 
- [ ] Teste de carga gerou aumento de réplicas
- [ ] Comportamento de scale down ajustado se necessário

## FAQ

### O que é autoscaling horizontal no Kubernetes?

É o mecanismo que ajusta o número de réplicas de um workload com base em métricas observadas. O HorizontalPodAutoscaler (HPA) é o recurso nativo que implementa isso, consultando o Metrics Server para decidir quantos pods são necessários para atender à demanda atual.

### Qual a diferença entre HPA e autoscaling vertical?

O HPA altera a quantidade de pods. O autoscaling vertical (VPA) ajusta os recursos (CPU e memória) dos pods existentes. HPA é mais comum para aplicações stateless, enquanto VPA é usado quando não é possível dividir a carga em múltiplas instâncias.

### Por que meu HPA mostra em TARGETS?

Isso indica que o HPA não está recebendo métricas. As causas mais comuns são: Metrics Server não instalado, pods sem requests de CPU definidos, ou o Metrics Server com problemas de rede (como a flag --kubelet-insecure-tls ausente). Verifique os logs do Metrics Server com kubectl logs -n kube-system deployment/metrics-server.

### Posso usar autoscaling baseado em métricas personalizadas?

Sim, o HPA suporta métricas personalizadas via API, como requisições por segundo ou fila de mensagens. Isso requer um adaptador de métricas externas, como o Prometheus Adapter, e configuração adicional no HPA com type: External ou type: Object.

### O HPA funciona com StatefulSets?

Funciona, desde que o StatefulSet tenha requests de recursos definidos. O HPA escala o número de pods, mas lembre-se de que cada pod de um StatefulSet tem identidade estável, o que pode exigir cuidado com dados persistentes. Para workloads com estado, avalie se o escalonamento horizontal é adequado antes de aplicar.

### Qual a frequência de verificação do HPA?

O HPA consulta o Metrics Server a cada 15 segundos por padrão. No entanto, a decisão de escalar não é imediata: o controlador espera alguns ciclos para evitar reações a picos momentâneos. O tempo total para aumentar réplicas costuma ficar entre 1 e 2 minutos após a carga subir.

---

Fonte (canonical): https://www.pingobox.com.br/apps-e-software/autoscaling-kubernetes-guia-pratico-de-hpa-em-5-passos/