kubectl: o guia completo de comandos utilitários do Kubernetes

O kubectl é a CLI oficial do Kubernetes — é através dele que você interage com qualquer cluster, seja local (kind, minikube) ou em produção (EKS, GKE, AKS). Dominar seus comandos é a diferença entre um operador que abre o dashboard e um que resolve problemas em segundos no terminal.

Veja o mapa mental das principais categorias de comandos antes de mergulhar em cada uma:---

1. Inspeção — entendendo o que está rodando

kubectl get

O comando mais usado do dia a dia. Lista recursos do cluster.

# Listar pods no namespace atual
kubectl get pods

# Listar pods de todos os namespaces
kubectl get pods -A

# Listar pods com mais detalhes (IP, nó, tempo)
kubectl get pods -o wide

# Listar em formato YAML (útil para exportar configurações)
kubectl get deployment minha-app -o yaml

# Listar em formato JSON e filtrar com jq
kubectl get pods -o json | jq '.items[].metadata.name'

# Assistir mudanças em tempo real
kubectl get pods -w

# Listar múltiplos recursos de uma vez
kubectl get pods,services,deployments

Recursos comuns que você vai usar com get: pods, services (ou svc), deployments (ou deploy), nodes, namespaces (ou ns), configmaps (ou cm), secrets, ingresses, persistentvolumeclaims (ou pvc).

kubectl describe

Mostra os detalhes completos de um recurso, incluindo eventos — essencial para diagnosticar problemas.

# Descrever um pod específico
kubectl describe pod meu-pod-abc123

# Descrever todos os pods de um deployment
kubectl describe pods -l app=minha-app

# Descrever um nó
kubectl describe node worker-1

# Descrever um service
kubectl describe svc meu-service

A seção Events no final do describe é onde ficam as mensagens de erro mais úteis — sempre role até lá quando um pod não sobe.

kubectl logs

# Ver logs de um pod
kubectl logs meu-pod

# Seguir logs em tempo real (equivalente ao -f do tail)
kubectl logs -f meu-pod

# Ver os últimos 100 logs
kubectl logs --tail=100 meu-pod

# Logs de um container específico (pods multi-container)
kubectl logs meu-pod -c meu-container

# Logs de um pod que já morreu (crashou)
kubectl logs meu-pod --previous

# Logs dos últimos 30 minutos
kubectl logs meu-pod --since=30m

# Logs de todos os pods de um deployment via label
kubectl logs -l app=minha-app --all-containers=true

kubectl top

Mostra consumo de CPU e memória em tempo real. Requer o Metrics Server instalado.

# Consumo dos nós
kubectl top nodes

# Consumo dos pods
kubectl top pods

# Consumo dos pods de um namespace específico
kubectl top pods -n producao

# Ordenar por consumo de CPU
kubectl top pods --sort-by=cpu

2. Criação e gerenciamento de recursos

kubectl apply

A forma declarativa de criar ou atualizar recursos. É o comando que você deve usar em produção.

# Aplicar um arquivo
kubectl apply -f deployment.yaml

# Aplicar todos os YAMLs de um diretório
kubectl apply -f ./k8s/

# Aplicar de uma URL remota
kubectl apply -f https://raw.githubusercontent.com/.../manifest.yaml

# Ver o que seria aplicado sem aplicar (dry-run)
kubectl apply -f deployment.yaml --dry-run=client

# Ver diff entre o que está no cluster e o que será aplicado
kubectl diff -f deployment.yaml

kubectl create

Forma imperativa, útil para criações rápidas e one-shot.

# Criar um namespace
kubectl create namespace staging

# Criar um deployment rapidamente
kubectl create deployment nginx --image=nginx:1.25

# Criar um secret a partir de variáveis literais
kubectl create secret generic db-creds \
  --from-literal=user=admin \
  --from-literal=password=s3cr3t

# Criar secret a partir de arquivo .env
kubectl create secret generic app-env --from-env-file=.env

# Criar configmap a partir de arquivo
kubectl create configmap app-config --from-file=config.yaml

# Expor um deployment como service
kubectl expose deployment minha-app --port=80 --target-port=8080 --type=ClusterIP

kubectl delete

# Deletar por arquivo
kubectl delete -f deployment.yaml

# Deletar por tipo e nome
kubectl delete pod meu-pod

# Deletar todos os pods de um namespace
kubectl delete pods --all -n staging

# Deletar por label
kubectl delete pods -l app=minha-app

# Forçar deleção imediata (cuidado em produção)
kubectl delete pod meu-pod --grace-period=0 --force

# Deletar namespace inteiro (e tudo dentro)
kubectl delete namespace staging

kubectl edit

Abre o recurso no editor padrão ($EDITOR) diretamente para edição ao vivo.

kubectl edit deployment minha-app
kubectl edit configmap app-config

Útil para ajustes rápidos, mas evite em produção — prefira apply com arquivos versionados no Git.

---

3. Execução e acesso a containers

kubectl exec

Executa comandos dentro de um container em execução.

# Abrir shell interativo em um pod
kubectl exec -it meu-pod -- /bin/bash

# Abrir shell em um container específico (pod multi-container)
kubectl exec -it meu-pod -c sidecar -- /bin/sh

# Executar um comando sem shell interativo
kubectl exec meu-pod -- env

# Checar conectividade de dentro do pod
kubectl exec -it meu-pod -- curl http://outro-service:8080/health

kubectl port-forward

Redireciona uma porta local para uma porta dentro do cluster. Indispensável em desenvolvimento.

# Forward da porta local 8080 para a porta 80 do pod
kubectl port-forward pod/meu-pod 8080:80

# Forward para um service
kubectl port-forward svc/meu-service 8080:80

# Forward para um deployment (escolhe um pod automaticamente)
kubectl port-forward deployment/minha-app 8080:8080

# Escutar em todos os endereços (não só localhost)
kubectl port-forward svc/meu-service 8080:80 --address=0.0.0.0

kubectl run

Cria um pod temporário — excelente para testes e diagnósticos.

# Pod temporário interativo com curl disponível
kubectl run debug --image=curlimages/curl -it --rm -- sh

# Pod temporário com busybox para troubleshooting de rede
kubectl run nettest --image=busybox -it --rm -- sh

# Testar DNS de dentro do cluster
kubectl run dns-test --image=busybox --rm -it -- nslookup meu-service

# Pod temporário que morre sozinho após o comando
kubectl run teste --image=alpine --rm --restart=Never -- echo "funciona"

O flag --rm garante que o pod seja deletado automaticamente ao terminar.

kubectl cp

Copia arquivos entre o host e um container.

# Copiar arquivo do pod para o host
kubectl cp meu-pod:/app/logs/app.log ./app.log

# Copiar arquivo do host para o pod
kubectl cp ./config.yaml meu-pod:/app/config.yaml

# Copiar de um container específico
kubectl cp meu-pod:/dados ./dados -c meu-container

4. Escalonamento e rollouts

kubectl scale

# Escalar um deployment para 5 réplicas
kubectl scale deployment minha-app --replicas=5

# Escalar para zero (suspende a aplicação)
kubectl scale deployment minha-app --replicas=0

# Escalar múltiplos deployments de uma vez
kubectl scale deployment app-a app-b --replicas=3

kubectl rollout

Gerencia o ciclo de vida de deployments — um dos comandos mais importantes para operação.

# Ver status de um rollout em andamento
kubectl rollout status deployment/minha-app

# Ver histórico de versões
kubectl rollout history deployment/minha-app

# Ver detalhes de uma revisão específica
kubectl rollout history deployment/minha-app --revision=3

# Fazer rollback para a versão anterior
kubectl rollout undo deployment/minha-app

# Fazer rollback para uma revisão específica
kubectl rollout undo deployment/minha-app --to-revision=2

# Pausar um rollout em andamento
kubectl rollout pause deployment/minha-app

# Retomar um rollout pausado
kubectl rollout resume deployment/minha-app

# Forçar um novo rollout sem mudar nada (útil para reiniciar pods)
kubectl rollout restart deployment/minha-app

O kubectl rollout restart é especialmente útil para forçar os pods a recarregarem ConfigMaps ou Secrets que foram atualizados.

kubectl autoscale

Cria um HorizontalPodAutoscaler (HPA) de forma imperativa.

# Escalar entre 2 e 10 réplicas baseado em CPU
kubectl autoscale deployment minha-app --min=2 --max=10 --cpu-percent=70

5. Debug e diagnóstico avançado

kubectl debug

Introduzido no Kubernetes 1.18, permite criar containers de debug efêmeros.

# Adicionar container de debug a um pod em execução
kubectl debug -it meu-pod --image=busybox --target=meu-container

# Criar cópia do pod com shell para debug
kubectl debug meu-pod -it --copy-to=meu-pod-debug --image=ubuntu

# Debug de um nó diretamente
kubectl debug node/worker-1 -it --image=ubuntu

kubectl events

Lista eventos do cluster — muito mais rápido que describe quando você quer ver tudo de uma vez.

# Ver todos os eventos do namespace atual
kubectl events

# Ver eventos de um namespace específico
kubectl events -n producao

# Ver eventos em ordem cronológica
kubectl events --sort-by=lastTimestamp

# Ver eventos de um recurso específico
kubectl events --for pod/meu-pod

# Ver apenas eventos de Warning
kubectl events --types=Warning

kubectl diff

Mostra exatamente o que mudaria antes de aplicar um manifest — fundamental em pipelines de CD.

kubectl diff -f deployment.yaml

6. Contextos e namespaces

Em ambientes reais você lida com múltiplos clusters e namespaces. Estes comandos evitam confusão e erros graves.

Gerenciando contextos

# Ver o contexto atual
kubectl config current-context

# Listar todos os contextos disponíveis
kubectl config get-contexts

# Trocar de contexto (mudar de cluster)
kubectl config use-context producao

# Renomear um contexto
kubectl config rename-context velho-nome novo-nome

# Deletar um contexto
kubectl config delete-context contexto-antigo

# Ver o kubeconfig completo
kubectl config view

Trabalhando com namespaces

# Listar todos os namespaces
kubectl get namespaces

# Executar comando em um namespace específico
kubectl get pods -n kube-system

# Mudar o namespace padrão do contexto atual
kubectl config set-context --current --namespace=staging

# Listar recursos em todos os namespaces
kubectl get pods --all-namespaces
# ou o shorthand:
kubectl get pods -A

Uma dica de ouro: use a ferramenta kubens (do pacote kubectx) para trocar de namespace com um simples kubens staging. Da mesma forma, kubectx producao troca de cluster. São as duas ferramentas de produtividade mais recomendadas para quem usa kubectl no dia a dia.

7. Comandos de produtividade

Labels e seletores

# Adicionar label a um pod
kubectl label pod meu-pod ambiente=producao

# Remover label
kubectl label pod meu-pod ambiente-

# Filtrar por label
kubectl get pods -l app=minha-app,ambiente=producao

# Filtrar com operadores de conjunto
kubectl get pods -l 'ambiente in (staging, dev)'

Anotações

# Adicionar anotação
kubectl annotate deployment minha-app \
  kubernetes.io/change-cause="Atualiza para v2.1.0"

# Anotações ficam no histórico do rollout
kubectl rollout history deployment/minha-app

kubectl patch

Atualiza um campo específico sem precisar editar o arquivo inteiro.

# Atualizar a imagem de um container via patch JSON
kubectl patch deployment minha-app \
  -p '{"spec":{"template":{"spec":{"containers":[{"name":"app","image":"minha-app:v2"}]}}}}'

# Patch com merge estratégico
kubectl patch deployment minha-app --type=merge \
  -p '{"spec":{"replicas":3}}'

Output e formatação

# Colunas customizadas com jsonpath
kubectl get pods -o jsonpath='{.items[*].metadata.name}'

# Formato de tabela customizado
kubectl get pods \
  -o custom-columns=NOME:.metadata.name,STATUS:.status.phase,IP:.status.podIP

# Exportar todos os deployments do namespace em YAML
kubectl get deployments -o yaml > backup-deployments.yaml

Aliases úteis para o .bashrc / .zshrc

alias k='kubectl'
alias kg='kubectl get'
alias kd='kubectl describe'
alias kl='kubectl logs'
alias kx='kubectl exec -it'
alias kns='kubectl config set-context --current --namespace'
alias kctx='kubectl config use-context'

Com alias k='kubectl', você pode usar simplesmente k get pods, k apply -f ., k logs -f meu-pod e ganhar muito tempo no dia a dia.

8. Referência rápida dos recursos e seus atalhos

Recurso completo	Abreviação
pods	po
services	svc
deployments	deploy
replicasets	rs
statefulsets	sts
daemonsets	ds
configmaps	cm
namespaces	ns
nodes	no
persistentvolumes	pv
persistentvolumeclaims	pvc
horizontalpodautoscalers	hpa
ingresses	ing
serviceaccounts	sa

Você pode ver todos os recursos disponíveis (incluindo CRDs instalados) com:

kubectl api-resources

9. O comando que todo mundo esquece: kubectl explain

Documentação inline, sem precisar abrir o browser.

# Explicar um recurso
kubectl explain pod

# Explicar um campo específico
kubectl explain pod.spec.containers

# Explicar de forma recursiva (mostra todos os campos)
kubectl explain pod.spec --recursive

# Explicar para uma versão específica da API
kubectl explain deployment.spec.strategy --api-version=apps/v1