Gerador de comando kubectl

kubectl a fundo: verbos, recursos, formatos de saída e gestão de context

O kubectl (pronuncia-se "kube-control" ou "kube-cuddle") é o CLI primário do Kubernetes. É um cliente fino que conversa com o API server do cluster via HTTPS — todo comando vira uma chamada REST contra /api ou /apis, autenticada pelo kubeconfig em ~/.kube/config. Entender kubectl é, no fundo, entender a API: uma vez que você sabe como um Pod, um Deployment e um Service são modelados, o CLI vira só uma forma de listar, buscar, criar e atualizar esses objetos.

A sintaxe geral é kubectl <verbo> <TIPO>[/NOME] [flags], onde o verbo descreve a ação e o tipo identifica o recurso.

Verbos principais

• get — listar recursos (o comando mais usado).
• describe — detalhamento verboso e legível, com eventos.
• create — criação imperativa por argumentos; falha se o objeto já existe.
• apply -f file.yaml — declarativo create-or-update; fluxo preferido para GitOps.
• delete — remover recurso (por nome, label ou -f file.yaml).
• logs — pegar stdout/stderr do container; -f para acompanhar, --previous para o último crash.
• exec -it pod -- /bin/sh — abrir shell dentro do container.
• port-forward — tunelar porta local até pod/service para debug.
• cp — copiar arquivos entre local e container.
• top pods / top nodes — CPU/memória em tempo real (requer metrics-server).
• rollout status / rollout undo — acompanhar e reverter Deployments.
• scale deployment api --replicas=5 — mudar contagem de réplicas sem editar YAML.

Tipos de recursos comuns

Cada tipo tem um apelido curto utilizável em qualquer comando:

po       pods
deploy   deployments
svc      services
ing      ingresses
cm       configmaps
sec      secrets
ns       namespaces
no       nodes
pv       persistentvolumes
pvc      persistentvolumeclaims
sts      statefulsets
ds       daemonsets
job/cj   jobs / cronjobs
sa       serviceaccounts
ep       endpoints
hpa      horizontalpodautoscalers

Rode kubectl api-resources para ver todo tipo suportado pelo cluster, incluindo CRDs.

Exemplos práticos

# Pods num namespace
kubectl get pods -n meu-ns

# Pods em todos os namespaces
kubectl get pods -A

# Detalhes + eventos recentes
kubectl describe pod nginx-abc123

# Tail de logs de um deployment (escolhe um pod)
kubectl logs -f deploy/api --tail=200

# Abrir shell no primeiro container
kubectl exec -it api-7d4f -- /bin/sh

# Aplicar manifests de uma árvore de diretórios
kubectl apply -f k8s/

# Acompanhar rolling update
kubectl rollout status deployment/api -w

# Reverter o último deploy
kubectl rollout undo deployment/api

# Escalar para 5 réplicas
kubectl scale deployment api --replicas=5

# Port-forward de um service
kubectl port-forward svc/api 8080:80

# Pod descartável para debug
kubectl run debug --image=alpine -it --rm -- sh

Formatos de saída

• -o wide — colunas extras (node, IP).
• -o yaml / -o json — objeto completo como você escreveria.
• -o name — só tipo/nome, útil para pipes shell.
• -o jsonpath='{.items[*].metadata.name}' — extrair um campo específico.
• -o custom-columns=NAME:.metadata.name,IMAGE:.spec.containers[0].image — view tabular customizada.
• --watch / -w — fluxo de atualizações em vez de um snapshot.

Contexts e kubeconfig

Um context agrupa cluster, usuário e namespace padrão. Para alternar:

kubectl config get-contexts          # listar
kubectl config current-context       # qual está ativo
kubectl config use-context prod      # trocar
kubectl config set-context --current --namespace=staging

Ferramentas como kubectx e kubens são wrappers com seletor por setas; a maioria dos times configura alias k=kubectl com completion: source <(kubectl completion bash).

FAQ

Como debuggar um pod em CrashLoopBackOff? Combine kubectl describe pod <nome> (olhe a seção Events no final), kubectl logs <pod> --previous (logs do container que crashou) e kubectl get events --sort-by=.lastTimestamp no namespace.

Por que kubectl delete pod faz o pod reaparecer? Porque um Deployment, ReplicaSet ou StatefulSet é dono dele, e o controller imediatamente gera um substituto. Apague o dono (kubectl delete deploy api) ou faça scale para 0.

create ou apply — qual usar? Em scripts, prefira sempre apply -f: é idempotente e guarda a intenção numa anotação last-applied-configuration. O create é bom para coisas pontuais via flags (kubectl create secret generic ...).

Como copiar um arquivo de dentro de um pod? kubectl cp meu-ns/pod-nome:/caminho/no/container ./arquivo-local. O container precisa ter tar instalado (vem em distroless e nas imagens padrão).

Como explorar o schema de um recurso? kubectl explain pod.spec.containers.resources — funciona recursivamente, com --recursive para tudo. Puxa o OpenAPI do cluster ao vivo, então sempre bate com sua versão.

Quanto tempo demora um rolling update? Depende de maxSurge, maxUnavailable, readiness probe e tempo de startup do pod. Acompanhe com kubectl rollout status deploy/api; se travar, kubectl describe no novo ReplicaSet mostra o motivo.