Técnicas Avançadas de kubectl get: Filtrando Saída com Labels e JSONPath

kubectl get torna-se muito mais útil quando você pode restringir a saída aos recursos e campos exatos de que precisa. Em um namespace movimentado, a diferença entre uma parede de pods e uma lista focada de nomes, nós e imagens pode economizar minutos durante um incidente.

Este guia mostra como combinar seletores de label com saída JSONPath. Você também verá quando custom-columns ou jq é uma escolha melhor do que forçar tudo em uma única expressão JSONPath.

Entendendo Labels do Kubernetes: A Base da Seleção de Recursos

Antes de mergulhar na filtragem avançada, é crucial entender os labels do Kubernetes. Labels são pares chave-valor anexados a objetos do Kubernetes (como Pods, Services, Deployments, etc.) que são usados para identificar e organizar recursos. Eles são metadados que clientes e usuários podem usar para selecionar subconjuntos de objetos.

Labels são distintos de annotations; labels são destinados a identificar características que são significativas e relevantes para os usuários consultarem e selecionarem objetos, enquanto annotations são para metadados não identificadores. Boas práticas de labels são essenciais para um gerenciamento eficaz de recursos e operações avançadas de kubectl get.

Para ver os labels atualmente atribuídos aos seus recursos, você pode usar a flag --show-labels:

kubectl get pods --show-labels

Isso adicionará uma coluna LABELS à sua saída, mostrando todos os labels associados a cada Pod.

Seletores de Label Avançados com `kubectl get -l`

A flag -l ou --selector é sua ferramenta principal para filtrar a saída de kubectl get com base em labels. Ela permite especificar um conjunto de requisitos de label que os recursos devem atender para serem incluídos na saída. Os seletores podem ser pares chave-valor simples ou expressões mais complexas baseadas em conjuntos.

Seleção Básica de Label

Correspondência Exata

Para selecionar recursos que têm um label específico com um valor exato, use a sintaxe chave=valor.

# Obter todos os pods com o label 'app' definido como 'nginx'
kubectl get pods -l app=nginx

# Obter todos os services no namespace 'default' com o label 'tier' definido como 'frontend'
kubectl get services -n default -l tier=frontend

Correspondência de Desigualdade

Para selecionar recursos que têm um label específico não definido para um valor particular, use a sintaxe chave!=valor.

# Obter todos os pods onde o label 'app' não é 'nginx'
kubectl get pods -l app!=nginx

Existência (Apenas Chave)

Para selecionar recursos que simplesmente têm um label particular, independentemente de seu valor, apenas especifique a chave.

# Obter todos os pods que têm o label 'environment', independentemente de seu valor
kubectl get pods -l environment

Não Existência (Apenas Chave)

Para selecionar recursos que não têm um label particular, prefixe a chave com !.

# Obter todos os pods que NÃO têm o label 'component'
kubectl get pods -l !component

Combinando Múltiplos Seletores de Label (Lógica E)

Você pode combinar múltiplos seletores de label separando-os por vírgula. Isso implica uma relação E, significando que um recurso deve satisfazer todas as condições de label especificadas para ser incluído.

# Obter pods com 'app=nginx' E 'env=production'
kubectl get pods -l app=nginx,env=production

# Obter deployments com 'tier=backend' E que NÃO têm o label 'version'
kubectl get deployments -l tier=backend,!version

Seletores de Label Baseados em Conjuntos

O Kubernetes também suporta seletores de label baseados em conjuntos mais poderosos, que são particularmente úteis ao lidar com múltiplos valores possíveis para um único label.

`chave in (valor1, valor2, ...)`

Para selecionar recursos onde o valor de um label é um de uma lista especificada de valores.

# Obter pods onde o label 'app' é 'nginx' OU 'redis'
kubectl get pods -l 'app in (nginx,redis)'

# Obter services no namespace 'kube-system' onde o label 'k8s-app' é 'kube-dns' OU 'kubernetes-dashboard'
kubectl get services -n kube-system -l 'k8s-app in (kube-dns,kubernetes-dashboard)'

`chave notin (valor1, valor2, ...)`

Para selecionar recursos onde o valor de um label não é nenhum de uma lista especificada de valores.

# Obter pods onde o label 'env' NÃO é 'dev' NEM 'test'
kubectl get pods -l 'env notin (dev,test)'

Dica: Ao usar seletores baseados em conjuntos ou seletores com caracteres especiais, sempre coloque toda a expressão do seletor entre aspas simples ('...') para evitar problemas de interpretação pelo shell.

Melhores Práticas para Rotulagem

Consistência: Estabeleça um esquema de rotulagem claro e mantenha-o em todo o cluster. Isso torna a filtragem previsível e confiável.
Nomes Significativos: Use labels que descrevam claramente as características do recurso (ex.: app, tier, environment, version).
Granularidade: Labels devem ser específicos o suficiente para permitir seleção precisa, mas não tão granulares que se tornem ingerenciáveis.
Imutabilidade: Evite usar labels para dados que mudam com frequência. Labels são mais adequados para propriedades de identificação estáticas.
Labels Comuns: Use labels amplamente adotados como app.kubernetes.io/name, app.kubernetes.io/instance, app.kubernetes.io/version, etc., para melhor interoperabilidade com ferramentas.

Extraindo Dados Personalizados com JSONPath

Enquanto os seletores de label ajudam a identificar quais recursos você deseja, o JSONPath ajuda a definir quais informações você deseja extrair desses recursos e como elas devem ser formatadas. kubectl get permite que você exiba detalhes do recurso em vários formatos como yaml, json e wide; -o jsonpath é útil quando você precisa de uma saída personalizada compacta.

kubectl tem sua própria implementação JSONPath para navegar pela estrutura JSON dos objetos do Kubernetes. Ela suporta texto de template útil e loops range, mas não é o mesmo que Go templates ou jq.

Para usar JSONPath, você especifica o formato de saída com -o jsonpath='<template>'.

Fundamentos do JSONPath e Casos de Uso Comuns

Primeiro, muitas vezes é útil visualizar a saída JSON completa de um recurso para entender sua estrutura antes de escrever uma expressão JSONPath:

# Obter a estrutura JSON completa de um pod
kubectl get pod <nome-do-pod> -o json

Isso fornecerá um mapa claro para construir suas consultas JSONPath.

Acessando um Único Campo

Use {.campo.subcampo} para acessar valores específicos. Por exemplo, para obter o nome de um Pod:

# Obter o nome de um pod específico
kubectl get pod my-nginx-pod-12345 -o jsonpath='{.metadata.name}'

# Obter o nome do nó onde um pod está em execução
kubectl get pod my-nginx-pod-12345 -o jsonpath='{.spec.nodeName}'

Acessando Elementos de Array

Para acessar elementos dentro de um array, você pode usar [*] para iterar por todos os elementos ou [índice] para um específico.

# Obter os nomes de todos os containers em um pod específico
kubectl get pod my-nginx-pod-12345 -o jsonpath='{.spec.containers[*].name}'

# Obter a imagem do primeiro container em um pod específico
kubectl get pod my-nginx-pod-12345 -o jsonpath='{.spec.containers[0].image}'

Iterando sobre uma Lista de Recursos (usando `range`)

Quando kubectl get retorna múltiplos recursos (ex.: todos os pods), a saída é tipicamente um objeto contendo um array items. Você precisará da função range do Go template para iterar por eles.

# Listar todos os nomes de pods e seus IPs, cada um em uma nova linha
kubectl get pods -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.podIP}{"\n"}{end}'

# Listar todos os nomes de deployments e o número de réplicas prontas
kubectl get deployments -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.readyReplicas}{"\n"}{end}'

{range .items[*]}: Inicia uma iteração sobre cada item no array .items.
{.metadata.name}: Dentro do loop, . refere-se ao item atual (ex.: um objeto Pod único).
{"\t"}: Insere um caractere de tabulação para formatação.
{"\n"}: Insere um caractere de nova linha.
{end}: Fecha o loop range.

Saída Condicional: Use Go Templates em vez disso

kubectl -o jsonpath não suporta blocos if, with ou else do Go template. Se você precisar de renderização condicional, mude para -o go-template:

# Listar nomes de pods e imprimir N/A quando podIP estiver vazio
kubectl get pods -o go-template='{{range .items}}{{.metadata.name}}{{"\t"}}{{if .status.podIP}}{{.status.podIP}}{{else}}N/A{{end}}{{"\n"}}{{end}}'

Para saída não condicional, JSONPath é mais curto:

kubectl get pods -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.podIP}{"\n"}{end}'

Formatação Personalizada e Cabeçalho

Você pode adicionar seu próprio texto estático e criar um cabeçalho para sua saída semelhante a uma tabela.

# Saída personalizada para nomes de pods, imagens e nó, com um cabeçalho
kubectl get pods -o=jsonpath='{"NAME\tIMAGE\tNODE\n"}{range .items[*]}{.metadata.name}{"\t"}{.spec.containers[*].image}{"\t"}{.spec.nodeName}{"\n"}{end}'

Aviso: kubectl tem sua própria implementação JSONPath. Ela é útil para extração de campos e loops range, mas não é o mesmo que jq e não suporta todos os recursos JSONPath que você pode conhecer de outras ferramentas.

Dicas para JSONPath

Comece Simples: Comece com um caminho básico e depois adicione mais complexidade.
Inspecione o JSON: Sempre use kubectl get <recurso> <nome> -o json para entender a estrutura exata que você está consultando.
Escape Caracteres: Lembre-se de escapar caracteres especiais como novas linhas (\n) e tabulações (\t) dentro da string do template JSONPath se você quiser que eles sejam renderizados como literais na saída.
Salve Templates: Para expressões JSONPath complexas ou usadas com frequência, salve-as em um arquivo e use -o jsonpath-file=/caminho/para/template.jsonpath.

Combinando Labels e JSONPath

O verdadeiro poder vem da combinação dessas técnicas. Primeiro, use seletores de label para restringir os recursos e, em seguida, aplique JSONPath para extrair e formatar dados específicos desse conjunto filtrado.

# Obter os nomes e imagens de container de todos os pods com 'app=my-app' e 'env=production'
kubectl get pods -l 'app=my-app,env=production' -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.containers[*].image}{"\n"}{end}'

# Obter os nomes e IPs de cluster de todos os services que têm o label 'tier' definido como 'backend'
kubectl get services -l tier=backend -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.clusterIP}{"\n"}{end}'

# Encontrar todos os pods em execução em um nó específico 'worker-node-1' e listar seus nomes e status
kubectl get pods --field-selector spec.nodeName=worker-node-1 -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.phase}{"\n"}{end}'

Nota: Enquanto os seletores de label (-l) são para pares chave-valor arbitrários, kubectl também oferece --field-selector para filtrar com base em campos do recurso (ex.: status.phase=Running, metadata.namespace=default). Isso fornece outra camada poderosa de filtragem que pode ser combinada com labels e JSONPath.

Solução de Problemas e Armadilhas Comuns

Erros de Sintaxe JSONPath: Mesmo um pequeno erro de digitação pode quebrar o template. Verifique novamente chaves, pontos e acesso a arrays.
Campos Ausentes: Se um campo não existir para um recurso específico, JSONPath pode gerar <no value> ou uma string vazia. Use construções if ou with do Go template para lidar com isso de forma elegante.
Escape do Shell: As aspas simples ao redor da expressão JSONPath são cruciais. Se sua expressão contiver aspas internas ou caracteres especiais, você pode precisar de escape adicional do shell.
Go Template vs. JSONPath Puro: Lembre-se de que kubectl usa Go templates, não um mecanismo JSONPath universal. Recursos como filtragem avançada (?()) são tipicamente parte do jq ou outros processadores JSON dedicados, não suportados diretamente no -o jsonpath do kubectl.
Array items Vazio: Se seu seletor de label não corresponder a nenhum recurso, items estará vazio e seu loop range não produzirá nenhuma saída.

Conclusão

Dominar técnicas avançadas de kubectl get com seletores de label e JSONPath é uma habilidade inestimável para qualquer usuário do Kubernetes. Essas opções poderosas de filtragem e formatação transformam kubectl get de uma simples ferramenta de listagem em um utilitário sofisticado de extração de dados. Você pode identificar rapidamente recursos problemáticos, gerar relatórios personalizados ou alimentar dados precisos em scripts de automação.

Use labels para escolher os recursos e, em seguida, escolha o formato de saída mais simples que forneça os campos de que você precisa. JSONPath é ótimo para extração compacta, custom-columns é mais fácil para tabelas rápidas, e jq ou Go templates são melhores quando a saída precisa de lógica real.