Kubectl Top Pod: Monitore o Uso de CPU e Memória no Kubernetes

Resumo: O kubectl top pod oferece um snapshot em tempo real do uso de CPU (millicores) e memória (Mi/Gi) por pod, com dados fornecidos pelo Metrics Server. Use-o para identificar pods que consomem muitos recursos, ordenar com --sort-by=cpu/--sort-by=memory, detalhar o uso por contêiner com --containers e comparar o uso real com os requests/limits configurados, detectando super ou subprovisionamento antes que isso cause throttling ou OOM kills.

Neste artigo:

• Pré-requisitos para usar o kubectl top pod
• Sintaxe básica do kubectl top pod
• Casos de uso do kubectl top pod
• Como interpretar a saída do kubectl top pod
• Boas práticas para usar o kubectl top pod

Como interpretar a saída do kubectl top pod

A saída do kubectl top pod fornece um snapshot do uso atual de CPU e memória dos pods. Entender o significado de cada coluna ajuda a identificar workloads que consomem muitos recursos e a diagnosticar problemas de desempenho.

Exemplo de saída:

NAME                      CPU(cores)   MEMORY(bytes)
nginx-6d4cf56db6-xk8rt    2m           15Mi
api-server-7f89c7d9d      25m          120Mi

As colunas representam:

• NAME — O nome do pod
• CPU (cores) — Uso atual de CPU
• MEMORY (bytes) — Consumo atual de memória

Os valores de CPU normalmente são exibidos em millicores (m):

• 1000m equivale a 1 core de CPU
• 250m equivale a 0,25 core de CPU

Por exemplo:

• 2m significa que o pod está usando uma quantidade mínima de CPU
• 500m significa que o pod está consumindo metade de um core de CPU

Os valores de memória são exibidos em unidades binárias:

• Ki = kibibytes
• Mi = mebibytes
• Gi = gibibytes

Os valores exibidos são métricas de uso atual coletadas pelo Metrics Server. Não são médias históricas e podem mudar entre execuções do comando. Por isso, o kubectl top pod é mais indicado para verificações operacionais rápidas do que para monitoramento de longo prazo.

Saídas por contêiner:

Ao usar a flag --containers, a saída inclui as métricas de cada contêiner dentro do pod:

kubectl top pod nginx-6d4cf56db6-xk8rt --containers

Exemplo de saída:

POD                       NAME    CPU(cores)   MEMORY(bytes)
nginx-6d4cf56db6-xk8rt    nginx   2m           15Mi

Usando a saída do top pod para diagnosticar problemas nos pods:

Depois de identificar um consumo de recursos fora do padrão, compare o uso real com os requests e limits configurados. Isso ajuda a determinar se os pods estão dimensionados corretamente ou se precisam de ajustes para melhorar o desempenho e a eficiência no uso de recursos.

Boas práticas para usar o kubectl top pod

Confira algumas práticas úteis para adotar ao usar esse comando.

1. Confirme que o Metrics Server está instalado e saudável

Antes de confiar no kubectl top pod, verifique se o Metrics Server está instalado e funcionando corretamente no cluster. Você pode conferir o status com kubectl get deployment metrics-server -n kube-system e inspecionar os logs em busca de erros.

Se o Metrics Server estiver mal configurado ou com problemas, o kubectl top pod pode retornar dados incompletos ou falhar completamente. Monitore a saúde do Metrics Server com regularidade para garantir que as métricas de recursos reflitam o estado atual das suas workloads.

Exemplo:

kubectl --namespace=kube-system get deployment metrics-server

Saída:

NAME             READY   UP-TO-DATE   AVAILABLE   AGE
metrics-server   1/1     1            1           45d

Verifique a coleta de métricas:

kubectl top nodes

Saída:

NAME             CPU(cores)   CPU%   MEMORY(bytes)   MEMORY%
worker-node-1    420m         21%    3120Mi           39%
worker-node-2    365m         18%    2875Mi           36%

2. Sempre confira o namespace certo

Clusters Kubernetes costumam hospedar vários namespaces, cada um com workloads ou ambientes diferentes. Ao usar o kubectl top pod, especifique o namespace correto com a flag -n se você não estiver trabalhando no namespace padrão.

Deixar de especificar o namespace pode fazer com que problemas passem despercebidos ou levar a conclusões erradas sobre o uso de recursos. Por exemplo, você pode não perceber um pico de recursos em um ambiente de staging se verificar apenas o namespace padrão.

Exemplo:

kubectl --namespace production top pod

Saída:

NAME                        CPU(cores)   MEMORY(bytes)
frontend-76d9c7f7f5-qn9p8   65m          210Mi
backend-5c8b7d9f67-jh2wt    220m         580Mi
redis-0                     15m          140Mi

3. Ordene por CPU ou memória para encontrar pods problemáticos mais rápido

Ordenar os pods por uso de CPU ou memória destaca aqueles que mais consomem recursos. Use --sort-by=cpu ou --sort-by=memory para trazer os pods mais intensivos em recursos para o topo da saída. Analisar os pods com base no consumo de recursos ajuda a resolver gargalos e apoia o planejamento de capacidade.

Exemplo:

kubectl top pods -n production --sort-by=memory

Saída:

NAME                          CPU(cores)   MEMORY(bytes)
analytics-worker-7f4b7d5c8d   320m         1850Mi
api-server-6b8f4d5f4d         140m         720Mi
frontend-76d9c7f7f5           60m          220Mi

4. Compare o uso com os requests e limits

Para interpretar as métricas de recursos, compare o uso real relatado pelo kubectl top pod com os requests e limits definidos nas especificações dos pods. Se um pod se aproxima com frequência dos seus limits de recursos, ele pode sofrer throttling ou eviction. Um uso consistentemente baixo em relação aos requests indica superprovisionamento. Essa comparação ajuda as equipes a ajustar a alocação de recursos e evitar problemas como OOMKills ou throttling de CPU.

Exemplo:

Veja o uso atual:

kubectl -n production top pod api-server-6b8f4d5f4d

Saída:

NAME                     CPU(cores)   MEMORY(bytes)
api-server-6b8f4d5f4d    850m         920Mi

Confira os recursos configurados:

kubectl -n production describe pod api-server-6b8f4d5f4d

Saída (trecho):

Limits:
  cpu:     1
  memory:  1Gi
Requests:
  cpu:     500m
  memory:  512Mi

Neste exemplo, o pod está se aproximando dos limits tanto de CPU quanto de memória e pode precisar de ajustes.

5. Use labels para verificações no nível de workload

As labels do Kubernetes permitem filtrar e agrupar pods por aplicação, ambiente ou chave personalizada. Combinando o kubectl top pod com a flag -l, você pode monitorar o uso de recursos de uma workload, equipe ou microsserviço específico.

Exemplo:

Liste os pods com uma label específica:

kubectl -n production get pods -l app=web

Saída:

NAME                       READY   STATUS
web-6d7f9d8f8b-7xt2m       1/1     Running
web-6d7f9d8f8b-kq4pn       1/1     Running

Verifique o uso de recursos desses pods:

kubectl top pod -n production | grep web

Saída:

web-6d7f9d8f8b-7xt2m   35m   120Mi
web-6d7f9d8f8b-kq4pn   42m   135Mi

Isso permite que os operadores avaliem rapidamente o consumo de recursos de uma aplicação ou serviço específico sem precisar analisar workloads não relacionadas.

Como fazer right-sizing contínuo dos recursos dos pods com o PerfectScale

Embora o kubectl top pod ofereça um snapshot em tempo real do uso de CPU e memória, transformar essas leituras nos requests e limits certos em centenas de workloads é um esforço manual constante. A solução de otimização de desempenho do PerfectScale aprimora o desempenho do Kubernetes fazendo o right-sizing autônomo das workloads, prevenindo downtime e otimizando o uso de recursos para uma disponibilidade de 99,99%, de modo que os padrões de uso identificados com o kubectl top pod se traduzam diretamente em mudanças de configuração seguras e orientadas por dados.

Principais recursos do PerfectScale:

• Correção automática de problemas: Identifica e corrige instantaneamente riscos de resiliência, incluindo problemas de subprovisionamento de recursos como OOM, throttling de CPU e eviction, para maximizar o uptime e eliminar a latência.
• Right-sizing autônomo de CPU e memória: Analisa continuamente suas workloads e ajusta requests e limits de CPU e memória com base na demanda real, reduzindo o risco de throttling e cortando custos de nuvem — resolvendo o super e o subprovisionamento que o kubectl top pod ajuda você a detectar.
• Fortalecimento da infraestrutura: Oferece visibilidade holística dos seus nós para revelar proativamente configurações incorretas, prevenir o over-commitment dos nós com recomendações precisas de limits de memória, validar node affinities e taints e selecionar os tipos de nó mais adequados para seus pods.
• Priorização orientada por impacto: Resolve problemas críticos em tempo real com priorização automática, alinha os alertas aos seus SLAs/SLOs, envia notificações instantâneas por canais como Slack, MS Teams ou Datadog e transforma problemas em tickets com um clique.

Pronto para deixar os snapshots manuais e partir para a otimização autônoma? Saiba como o PerfectScale aumenta o desempenho do Kubernetes.

FAQ

Por que o kubectl top pod retorna "Metrics API not available"? O Metrics Server não está instalado ou não está saudável no seu cluster. Verifique com kubectl get deployment metrics-server -n kube-system e, se estiver faltando, instale-o a partir do manifesto oficial de componentes.

O que a coluna CPU(cores) realmente significa? Ela é exibida em millicores (m). 1000m equivale a um core completo de CPU, então 250m corresponde a um quarto de core e 2m é uma quantidade insignificante de CPU.

O kubectl top pod serve para monitoramento de longo prazo? Não. É um snapshot em tempo real do Metrics Server, não uma média histórica, então é mais indicado para verificações operacionais rápidas do que para análise de tendências. Use Prometheus/Grafana ou ferramentas semelhantes para monitoramento de longo prazo.

Como vejo as métricas por contêiner em vez de por pod? Adicione a flag --containers: kubectl top pod <pod-name> --containers.

Como encontro os pods que mais consomem recursos em um namespace? Use kubectl top pod -n <namespace> --sort-by=cpu ou --sort-by=memory para ordenar os pods por consumo, do maior para o menor.

Como sei se um pod está sub ou superprovisionado? Compare o uso em tempo real do kubectl top pod com os requests e limits configurados no pod (visíveis via kubectl describe pod). Um uso consistentemente próximo do limit indica risco de subprovisionamento; um uso muito abaixo do request indica superprovisionamento.