Como implementar Horizontal Pod Autoscaler em APIs com tráfego variável: guia prático para produção

APIs com tráfego variável precisam equilibrar duas necessidades que parecem opostas: responder bem aos picos de demanda e evitar manter infraestrutura ociosa. O Horizontal Pod Autoscaler (HPA) é um recurso do Kubernetes que ajuda a resolver esse problema ao ajustar automaticamente a quantidade de réplicas de um workload conforme métricas observadas.

Neste guia, você verá como preparar uma API, configurar um HPA com a API autoscaling/v2, selecionar métricas úteis, evitar oscilações e validar a estratégia antes da produção.

Entenda quando o Horizontal Pod Autoscaler é a solução certa

O HPA aumenta ou reduz horizontalmente o número de pods de workloads compatíveis, como Deployments. Ele observa métricas e altera a quantidade de réplicas para aproximar a utilização da meta definida.

Em uma API de e-commerce, por exemplo, duas réplicas podem atender bem o tráfego normal. Durante uma campanha, o HPA pode elevar gradualmente esse número para dez réplicas, desde que existam recursos disponíveis no cluster e que o limite máximo configurado permita essa expansão.

É importante separar as responsabilidades. O HPA decide quantos pods uma aplicação precisa; ele não cria capacidade nos nós. Se os novos pods permanecerem em estado Pending, o problema pode estar na capacidade do cluster, nas regras de agendamento ou no dimensionamento dos recursos solicitados.

Também não confunda HPA com escalonamento vertical. Enquanto o HPA adiciona ou remove réplicas, o ajuste vertical altera recursos destinados a cada pod. Para APIs stateless e distribuídas, a escala horizontal costuma ser uma abordagem mais previsível para absorver picos.

A CPU é um ótimo ponto de partida para serviços com processamento intenso. Porém, ela pode não refletir gargalos em APIs dependentes de banco de dados, cache, serviços externos ou conexões simultâneas. Nesses casos, métricas adicionais são essenciais.

Prepare a API: requests, limits e métricas confiáveis

O HPA baseado em utilização de recursos calcula percentuais em relação aos requests dos containers. Por isso, requests de CPU e memória precisam representar uma referência realista do consumo esperado da API.

Se uma aplicação consome normalmente cerca de 120 millicores de CPU por pod, um request inicial de 200m pode ser uma hipótese razoável para testes. O valor final deve ser confirmado com telemetria e cenários de carga representativos, não apenas com estimativas.

Limits também exigem cuidado. Um limite de CPU muito restritivo pode provocar throttling e aumentar a latência antes de a métrica levar o HPA a reagir. Já um limite de memória incompatível com o perfil da aplicação pode resultar em reinicializações por falta de memória.

Antes de criar o HPA, valide se o Metrics Server está operacional:

kubectl top nodes
kubectl top pods -n producao

Se esses comandos não retornarem métricas, investigue o Metrics Server antes de avançar. Um HPA baseado em recursos depende dessa fonte para tomar decisões.

Um Deployment preparado para autoscaling pode começar assim:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-pedidos
  namespace: producao
spec:
  replicas: 2
  selector:
    matchLabels:
      app: api-pedidos
  template:
    metadata:
      labels:
        app: api-pedidos
    spec:
      containers:
        - name: api
          image: exemplo/api-pedidos:1.0.0
          resources:
            requests:
              cpu: "200m"
              memory: "256Mi"
            limits:
              cpu: "500m"
              memory: "512Mi"

Não trate esses números como valores universais. O perfil de CPU, memória, inicialização e dependências da sua aplicação deve orientar o dimensionamento.

Crie um HPA para uma API usando métricas de CPU e memória

Para ambientes atuais, use autoscaling/v2. Essa versão permite combinar métricas e configurar o comportamento de escala com mais controle.

O exemplo abaixo acompanha CPU e memória para o Deployment api-pedidos, mantém pelo menos duas réplicas e permite chegar a doze:

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: api-pedidos-hpa
  namespace: producao
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: api-pedidos
  minReplicas: 2
  maxReplicas: 12
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 65
    - type: Resource
      resource:
        name: memory
        target:
          type: Utilization
          averageUtilization: 75

O campo scaleTargetRef aponta para o workload que terá as réplicas alteradas. Já minReplicas define a base de disponibilidade e maxReplicas estabelece um limite operacional e financeiro.

Com múltiplas métricas, o HPA calcula uma recomendação para cada uma e adota a maior recomendação. Isso evita que uma API permaneça subdimensionada quando apenas um dos sinais indica pressão.

Aplique e acompanhe o recurso:

kubectl apply -f api-pedidos-hpa.yaml
kubectl get hpa -n producao
kubectl describe hpa api-pedidos-hpa -n producao

Comece com metas conservadoras e ajuste-as com base em medições. Uma meta muito baixa pode gerar réplicas demais; uma meta alta demais pode permitir degradação de desempenho antes da escala.

Escolha métricas que acompanhem a demanda real da API

A melhor métrica de autoscaling é a que sinaliza saturação antes de o usuário perceber degradação. CPU e memória são simples de operar, mas não explicam todas as formas de pressão sobre uma API.

Quando usar CPU e memória

CPU funciona bem para endpoints com serialização pesada, cálculos, compressão, criptografia ou transformação de dados. Memória pode ser relevante quando o aumento de concorrência eleva o consumo de heap, caches locais ou buffers.

Quando considerar métricas de aplicação

Uma API de checkout pode apresentar CPU baixa enquanto aguarda respostas do banco de dados. Nesse cenário, requisições por segundo por pod, conexões ativas, duração das requisições ou tamanho da fila podem refletir melhor a demanda real.

Para workloads orientados por filas, acompanhe backlog e tempo de processamento. Escalar somente depois de uma fila crescer demais aumenta o tempo de espera e pode tornar a recuperação mais cara.

Métricas customizadas exigem uma cadeia confiável de instrumentação, coleta, agregação e exposição ao Kubernetes. Antes de usar um sinal de negócio para escalar, valide sua atualização, disponibilidade e comportamento durante falhas de observabilidade.

Uma boa prática é cruzar a métrica de escala com indicadores de experiência: latência p95, taxa de erros, saturação de dependências e cumprimento de SLOs. Assim, o HPA deixa de ser apenas uma automação de infraestrutura e passa a apoiar a confiabilidade do serviço.

Evite oscilações com políticas de comportamento e estabilização

Sem controles adequados, pequenas variações de métrica podem fazer o HPA adicionar e remover pods repetidamente. Esse efeito aumenta o custo, pressiona dependências e pode reduzir a estabilidade da API.

Use o bloco behavior para definir a velocidade máxima de crescimento, uma política de redução e uma janela de estabilização para scale down:

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

Nesse exemplo, a API pode crescer com rapidez, mas a redução espera cinco minutos para evitar encerrar pods logo após um pico curto. A política de descida limita a redução a 25% por minuto.

O tempo de inicialização da aplicação também importa. Se um novo pod leva 90 segundos para ficar pronto, uma escala reativa pode chegar tarde demais. Readiness probes bem definidas garantem que o pod só receba tráfego quando realmente puder atendê-lo.

Considere ainda pools de conexão, migrações, aquecimento de cache e chamadas de inicialização. Cada nova réplica deve entrar em operação sem criar uma onda de carga adicional sobre banco de dados ou serviços externos.

Teste o autoscaling antes de levar a configuração para produção

Um manifesto válido não garante uma estratégia eficaz. Teste o autoscaling em ambiente controlado com tráfego semelhante ao comportamento real da API.

Prepare ao menos três cenários: crescimento gradual, pico abrupto e redução de tráfego. Durante cada teste, acompanhe réplicas desejadas e atuais, CPU, memória, latência, erros, saturação de dependências e tempo até os novos pods se tornarem prontos.

Inclua testes de carga em APIs que elevem, por exemplo, a taxa de 20 para 500 requisições por segundo. O objetivo não é apenas verificar se o número de pods aumenta, mas confirmar que a latência p95 permanece dentro do SLO e que a taxa de erros continua aceitável.

Observe o atraso completo da escala: geração da métrica, decisão do HPA, criação do pod, inicialização da aplicação, aprovação da readiness probe e distribuição de tráfego. Esse intervalo define quanto de capacidade mínima você precisa manter para absorver picos iniciais.

Teste também as dependências compartilhadas. Aumentar o número de pods pode multiplicar conexões com banco de dados, chamadas a APIs externas e consumo de cache. Se uma dependência se tornar o gargalo, escalar a API não resolverá a experiência do usuário.

Registre os resultados e transforme-os em critérios de aceite: tempo máximo para escalar, latência p95, erro máximo permitido, consumo de recursos e comportamento após a redução da carga.

Monitore o HPA e ajuste continuamente em produção

O HPA deve ser tratado como uma configuração operacional que evolui com a aplicação. Mudanças de código, tráfego, dependências e perfil de uso podem invalidar parâmetros que funcionavam bem no lançamento.

Monitore a quantidade de réplicas atual e desejada, a frequência de eventos de escala, a utilização das métricas-alvo, latência, erros, reinicializações e sinais de saturação nas dependências.

Um alerta útil é detectar quando a API fica no máximo de doze réplicas por dez minutos. Isso pode indicar que o limite precisa ser revisto, que os nós não têm capacidade suficiente ou que existe um gargalo fora da camada de aplicação.

Também acompanhe situações em que a métrica fica persistentemente acima da meta, mas o número de réplicas não cresce. Eventos do HPA, quotas de namespace, pods pendentes e indisponibilidade de métricas costumam ajudar a explicar esse comportamento.

Revise periodicamente requests, limits, metas, mínimo e máximo de réplicas. A configuração ideal busca preservar o SLO da API com o menor consumo necessário, sem usar o autoscaling como substituto para investigação de gargalos estruturais.

Conclusão

Implementar Horizontal Pod Autoscaler em produção começa pela preparação correta da aplicação: métricas disponíveis, requests realistas, limites coerentes e probes confiáveis. Depois, a configuração deve refletir o comportamento da demanda e ser validada com carga antes de receber tráfego crítico.

Para APIs simples, CPU e memória podem entregar um primeiro resultado sólido. Para serviços I/O-bound, orientados por filas ou dependentes de sistemas externos, complemente a estratégia com métricas que traduzam melhor a pressão real sobre o serviço.

Sua API enfrenta picos de tráfego ou custos imprevisíveis no Kubernetes? Avalie suas métricas, requests e limites de escala para construir uma estratégia de autoscaling adequada ao seu ambiente de produção.