Metrics API do Kubernetes vira GA na 1.37: como migrar do beta sem quebrar HPA e VPA

A partir do Kubernetes↳Kubernetes18 conteúdosGerenciamento de infraestrutura multicloud com Kubernetes proporciona otimização e economiaDevSecOps · set 2021Azure Kubernetes Services – AKS: referências gratuitas e dicas para solução de problemas comunsDevSecOps · abr 2019Kubernetes em produção: o que ninguém te conta e você aprende tarde demaisDev (Back & Front) · abr 2026Ver tudo em DevSecOps → 1.37, a Metrics API (metrics.k8s.io) graduou para GA, servida na versão estável v1. É a API que alimenta o kubectl top, o HorizontalPodAutoscaler (HPA) e o VerticalPodAutoscaler (VPA) com uso de CPU e memória de nós e pods. A mudança foi registrada nos docs oficiais em 01/07/2026 ("Add docs for metrics.k8s.io graduation to stable").

O ponto que importa para quem opera cluster: v1beta1 não some da noite para o dia, mas passa a conviver com v1, e o caminho seguro é validar tudo que consome a API antes de rodar o upgrade do control plane para 1.37. Autoscaler que não encontra métrica não escala, e num pico de tráfego isso não é um alerta amarelo, é indisponibilidade.

O que exatamente mudou

A arquitetura do pipeline continua idêntica: cAdvisor → kubelet (endpoint /metrics/resource) → metrics-server → API server → consumidores (HPA, VPA, kubectl top). O que graduou foi o contrato da API. Antes, uma consulta retornava "apiVersion": "metrics.k8s.io/v1beta1". Agora a versão estável responde em v1:

{
  "kind": "NodeMetrics",
  "apiVersion": "metrics.k8s.io/v1",
  "metadata": { "name": "minikube" },
  "timestamp": "2022-01-27T18:48:33Z",
  "window": "30s",
  "usage": { "cpu": "487558164n", "memory": "732212Ki" }
}

O schema dos objetos NodeMetrics e PodMetrics (campos usage, window, timestamp) não mudou. Isso é o que torna a migração de baixo risco: quem consome via kubectl top ou via HPA/VPA nativos não precisa reescrever nada. O risco mora em quem consulta a API de forma hardcoded, fixando /apis/metrics.k8s.io/v1beta1/... em scripts, dashboards ou operators caseiros.

Lembrando o que a própria doc reforça: a Metrics API entrega só o mínimo de CPU e memória para autoscaling. Se você precisa de métrica de negócio ou latência para escalar, isso continua no Custom Metrics API, que é outro pipeline (e não é afetado por esta graduação).

Pré-requisitos antes de encostar no cluster

• metrics-server compatível: a implementação de referência da Metrics API é o metrics-server. Garanta uma versão que sirva v1. Consulte as releases no repositório oficial (kubernetes-sigs/metrics-server) e a matriz de compatibilidade com sua versão de Kubernetes antes de decidir a tag.
• API aggregation layer habilitada: a Metrics API é servida via aggregation layer, com um APIService registrado para metrics.k8s.io. Em cluster kubeadm isso já vem ligado; em managed (EKS, GKE, AKS) é o provedor quem cuida.
• kubelet no endpoint certo: metrics-server v0.6.0+ lê de /metrics/resource. Versões antigas usam /stats/summary. Se você está num metrics-server muito velho, atualizar já resolve dois problemas de uma vez.

Minha recomendação de ordem: primeiro o metrics-server, valida, depois o control plane para 1.37. Nunca os dois no mesmo passo, porque se algo quebrar você não sabe qual mudança foi a culpada.

Passo 1: descobrir quem ainda fala v1beta1

Antes de qualquer coisa, mapeie o que o cluster expõe hoje:

kubectl api-versions | grep metrics.k8s.io

Se aparecer só metrics.k8s.io/v1beta1, seu metrics-server ainda não serve v1. Depois, cace consumidores hardcoded no seu próprio código e nos manifestos:

grep -rn "metrics.k8s.io/v1beta1" ./infra ./charts ./scripts

Dashboards que fazem kubectl get --raw "/apis/metrics.k8s.io/v1beta1/..." são os primeiros candidatos a quebrar. HPAs e VPAs criados via YAML não referenciam a versão da Metrics API diretamente, então normalmente estão seguros; ainda assim, liste-os para revalidar depois:

kubectl get hpa -A
kubectl get vpa -A 2>/dev/null

Passo 2: atualizar o metrics-server

Nota da redação: o código desta seção não foi executado em ambiente real. Valide antes de usar em produção.

Em cluster kubeadm ou bare-metal, aplique o manifesto da versão escolhida:

kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/download/<VERSAO>/components.yaml

O tropeço clássico aqui, principalmente em kubeadm e clusters com certificado de kubelet self-signed: o metrics-server não consegue validar o TLS do kubelet e o pod fica em CrashLoopBackOff ou o APIService reporta False. O sintoma no log é algo como unable to fully scrape metrics: x509: certificate signed by unknown authority. A solução conhecida é adicionar a flag ao container:

args:
  - --kubelet-insecure-tls
  - --kubelet-preferred-address-types=InternalIP,Hostname,ExternalIP

--kubelet-insecure-tls só em ambiente controlado; o certo em produção é configurar o kubelet com certificado assinado por uma CA que o metrics-server confie. É o trade-off explícito: pular a verificação de TLS resolve rápido, mas abre uma superfície que você vai querer fechar depois.

Em managed, você geralmente não gerencia o metrics-server na mão; o upgrade da versão do cluster já traz a versão compatível. Vale confirmar com o provedor se o add-on que você usa (ou o instalado por Helm) serve v1.

Passo 3: validar que a v1 responde

Depois do rollout, confirme que a API estável está de pé:

kubectl api-versions | grep metrics.k8s.io
# esperado: metrics.k8s.io/v1

kubectl get apiservice v1.metrics.k8s.io -o jsonpath='{.status.conditions[?(@.type=="Available")].status}{"\n"}'
# esperado: True

Consulte um nó direto pela versão nova:

kubectl get --raw "/apis/metrics.k8s.io/v1/nodes/$(kubectl get nodes -o jsonpath='{.items[0].metadata.name}')" | jq '.apiVersion'
# "metrics.k8s.io/v1"

E o teste que mais importa na prática, o kubectl top:

kubectl top nodes
kubectl top pods -A

Se kubectl top retorna números, o pipeline inteiro está funcional: kubelet coletando, metrics-server agregando, API server servindo. Se retorna error: Metrics API not available, algo entre o metrics-server e o aggregation layer está quebrado, volte ao Passo 2.

Passo 4: confirmar HPA e VPA de verdade

API respondendo não é a mesma coisa que autoscaler funcionando. Cheque se o HPA está lendo métrica:

kubectl describe hpa <nome> -n <namespace>

O que você quer ver em Conditions é AbleToScale: True e ScalingActive: True. Se aparecer ScalingActive: False com motivo FailedGetResourceMetric, o HPA não está conseguindo a métrica, mesmo que kubectl top funcione. Em geral é permissão ou o metrics-server ainda não populou o cache (dê alguns minutos após o rollout).

Para o VPA, além dos pods do próprio VPA (recommender, updater, admission-controller) estarem Running, confira se as recomendações continuam sendo geradas:

kubectl describe vpa <nome> -n <namespace> | grep -A6 "Recommendation"

VPA parado de recomendar depois do upgrade é sinal de que o recommender perdeu o pipeline de métricas.

Passo 5: subir para 1.37

Com metrics-server servindo v1, kubectl top respondendo e HPAs com ScalingActive: True, aí sim o upgrade do control plane para 1.37 é seguro. Em kubeadm, o fluxo padrão (kubeadm upgrade plan → kubeadm upgrade apply → drenar e atualizar nós). Depois do upgrade, repita o Passo 3 e o Passo 4: é rápido e é a diferença entre descobrir um autoscaler morto agora, na janela de manutenção, ou às 3h da manhã num pico.

O que fica em aberto

A doc marca a graduação, mas não crava um cronograma de remoção do v1beta1. Historicamente o Kubernetes mantém a versão beta por alguns releases após o GA, então há folga para migrar scripts sem pressa. Ainda assim, tratar v1beta1 hardcoded como dívida técnica a pagar já vale: troque para v1 nos seus dashboards e operators enquanto o beta ainda existe, para não ser pego quando ele finalmente sair. Referência oficial completa em kubernetes.io/docs/tasks/debug/debug-cluster/resource-metrics-pipeline.

Fonte 1: Kubernetes Docs — Resource Metrics Pipeline (Metrics API) (https://kubernetes.io/docs/tasks/debug/debug-cluster/resource-metrics-pipeline/)

Fonte: Kubernetes Docs — Resource Metrics Pipeline (Metrics API)