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:--- 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 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. 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 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 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 Em ambientes reais você lida com múltiplos clusters e namespaces. Estes comandos evitam confusão e erros graves. # 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 # 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. # 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)' # 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}}' # 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 .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. 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 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