Guia 02 / 3
Comandos Kubernetes · kubectl
Utilizar o kubectl para observar, implementar, resolver problemas e administrar um cluster de formação.
Escolher um comando, verificar o seu alcance e diagnosticar uma implementação sem intervenção destrutiva inútil.
01 · Contexto e ligação
Antes de cada manipulação, verificar em que cluster e em que namespace os comandos serão executados.
kubectl version --client
Apresenta a versão do cliente instalado, sem necessitar de um acesso funcional ao cluster.
Exemplo
kubectl version --client
kubectl cluster-info
Apresenta os endereços dos principais serviços do cluster acessível.
Exemplo
kubectl cluster-info
kubectl config get-contexts
Lista os contextos do kubeconfig: um contexto combina um cluster, uma identidade e um namespace por omissão.
Exemplo
kubectl config get-contexts
kubectl config current-context
Apresenta o contexto ativo para evitar agir no ambiente errado.
Exemplo
kubectl config current-context
kubectl config use-context
Altera o contexto utilizado por omissão na configuração local do kubectl.
Exemplo
kubectl config use-context lab
Cuidado para não mudar acidentalmente para produção.
kubectl get namespaces
Lista os namespaces acessíveis do cluster.
Exemplo
kubectl get ns
kubectl config set-context --current --namespace
Define o namespace por omissão do contexto atual, sem mudar de cluster.
Exemplo
kubectl config set-context --current --namespace=dev
02 · Observar os recursos
O método de diagnóstico começa por uma visão de conjunto e prossegue com o estado e os eventos de um recurso preciso.
kubectl get
Lista os recursos de um dado tipo no namespace atual.
Exemplo
kubectl get pods
kubectl get -A / -n
-A visa todos os namespaces; -n escolhe um preciso para os recursos de namespace.
Exemplo
kubectl get pods -A
kubectl get pods -n dev
kubectl get -o wide
Acrescenta colunas como o IP do Pod e o nó de colocação, consoante o tipo de recurso.
Exemplo
kubectl get pods -o wide
kubectl get -o yaml
Apresenta a representação YAML completa devolvida pela API, incluindo campos geridos pelo cluster.
Exemplo
kubectl get deployment web -o yaml
Não reutilizar tal e qual uid e resourceVersion num manifesto.
kubectl describe
Produz uma descrição legível com estado, configuração, erros e eventos.
Exemplo
kubectl describe pod web-abc123
kubectl get events
Mostra os eventos do cluster ou do namespace: falhas de colocação, de arranque ou de montagem.
Exemplo
kubectl get events -n dev --sort-by=.metadata.creationTimestamp
kubectl api-resources
Lista os tipos de recursos reconhecidos pela API e os seus eventuais nomes curtos.
Exemplo
kubectl api-resources
kubectl explain
Explica os campos esperados por um objeto da API com base no esquema conhecido do cluster.
Exemplo
kubectl explain deployment.spec.template.spec.containers
03 · Declarar, criar e modificar
Para as aplicações duradouras, conservar os manifestos YAML no Git e aplicar as suas alterações de forma controlada.
kubectl apply -f
Cria ou atualiza os recursos declarados num ficheiro ou diretório.
Exemplo
kubectl apply -f deployment.yaml
kubectl apply -f ./manifests/
kubectl diff -f
Apresenta as diferenças previstas entre o cluster e os manifestos antes da sua aplicação.
Exemplo
kubectl diff -f ./manifests/
Consoante o contexto, pode necessitar de direitos suplementares do lado do servidor.
kubectl apply --dry-run=server
Pede uma validação no lado do servidor sem persistir o objeto; útil antes da aplicação.
Exemplo
kubectl apply --dry-run=server -f deployment.yaml
A validação não garante a disponibilidade das imagens nem do armazenamento.
kubectl create namespace
Cria rapidamente um namespace; útil em TP ou para inicializar um ambiente.
Exemplo
kubectl create namespace dev
kubectl create deployment
Cria um Deployment a partir da linha de comandos, útil para uma demonstração rápida.
Exemplo
kubectl create deployment web --image=nginx:stable
kubectl edit
Abre o editor local para modificar um objeto existente e submeter depois as alterações à API.
Exemplo
kubectl edit deployment web
Para uma configuração reproduzível, transpor depois a alteração para o Git.
kubectl delete
Elimina recursos visados, no namespace ou contexto selecionado.
Exemplo
kubectl delete -f deployment.yaml
Verificar os volumes e os objetos dependentes antes de eliminar.
04 · Diagnóstico de um Pod
Para uma aplicação que não arranca: estado → describe → eventos → registos → verificação da rede e da configuração.
kubectl logs
Apresenta os registos de um Pod, indicando eventualmente o contentor em causa.
Exemplo
kubectl logs pod/web-abc -c nginx
kubectl logs -f / --previous
-f segue os registos; --previous consulta a instância anterior de um contentor reiniciado.
Exemplo
kubectl logs -f deployment/web
kubectl logs pod/web-abc --previous
kubectl exec
Executa um comando num contentor em execução, se a imagem contiver esse comando.
Exemplo
kubectl exec -it pod/web-abc -- sh
kubectl port-forward
Redireciona uma porta local para um Pod ou Service através da ligação kubectl, sem publicar um Service externo.
Exemplo
kubectl port-forward svc/web 8080:80
Acesso temporário de diagnóstico, e não uma publicação de produção.
kubectl cp
Copia ficheiros entre o posto local e um contentor; depende nomeadamente do tar no contentor.
Exemplo
kubectl cp dev/web-abc:/tmp/test.log ./test.log
kubectl top
Apresenta a utilização de CPU/memória quando a API de métricas, por exemplo o metrics-server, está disponível.
Exemplo
kubectl top pods
kubectl top nodes
kubectl debug
Permite uma depuração mais avançada, por exemplo com um contentor efémero ou uma cópia do Pod.
Exemplo
kubectl debug -it pod/web-abc --image=busybox:1.36 --target=nginx
Exige os direitos e o suporte adequados do cluster.
05 · Implementar, dimensionar e voltar atrás
A atualização de um Deployment gere a transição para a nova versão dos seus Pods.
kubectl scale
Modifica o número de réplicas de um recurso que suporte esta operação.
Exemplo
kubectl scale deployment/web --replicas=3
kubectl set image
Atualiza a referência de imagem de um contentor num Deployment ou objeto compatível.
Exemplo
kubectl set image deployment/web nginx=nginx:stable
Privilegiar uma referência de imagem imutável ou uma tag versionada.
kubectl rollout status
Aguarda ou verifica a progressão da implementação, com um timeout possível.
Exemplo
kubectl rollout status deployment/web --timeout=120s
kubectl rollout history
Apresenta as revisões registadas de um Deployment, se o histórico estiver disponível.
Exemplo
kubectl rollout history deployment/web
kubectl rollout undo
Pede o regresso a uma revisão anterior de um Deployment.
Exemplo
kubectl rollout undo deployment/web
O rollback não restaura os dados de negócio.
kubectl rollout restart
Desencadeia um novo ciclo de implementação atualizando o modelo de Pod.
Exemplo
kubectl rollout restart deployment/web
06 · Administração corrente e permissões
As operações sobre os nós e as autorizações devem ser reservadas a pessoas habilitadas.
kubectl get nodes
Apresenta os nós do cluster e a sua disponibilidade.
Exemplo
kubectl get nodes -o wide
kubectl cordon
Impede o planeamento de novos Pods comuns num nó, sem deslocar os Pods existentes.
Exemplo
kubectl cordon worker-1
kubectl drain
Evacua os Pods em causa de um nó para manutenção, respeitando certas proteções.
Exemplo
kubectl drain worker-1 --ignore-daemonsets
Executar apenas num ambiente autorizado; possíveis impactos aplicacionais.
kubectl uncordon
Volta a autorizar o planeamento de Pods num nó anteriormente bloqueado.
Exemplo
kubectl uncordon worker-1
kubectl auth can-i
Verifica se a identidade ativa está autorizada a efetuar uma ação precisa num perímetro.
Exemplo
kubectl auth can-i get secrets -n dev
kubectl get pvc,pv,storageclass
Inspeciona os pedidos, os volumes disponíveis e as classes de armazenamento.
Exemplo
kubectl get pvc -n dev
kubectl get pv,storageclass
kubectl get svc,ingress
Inspeciona os Services e as regras de entrada HTTP do namespace.
Exemplo
kubectl get svc,ingress -n dev
kubectl get configmap,secret
Lista os objetos de configuração do namespace; os valores secretos não são apresentados por omissão.
Exemplo
kubectl get configmaps,secrets -n dev
Nunca registar nem publicar o conteúdo real dos Secrets.
07 · Opções úteis e boas práticas
As opções do kubectl evitam erros de alcance e facilitam a automatização.
--context / --namespace
Visam explicitamente o cluster e o namespace sem modificar a configuração local persistente.
Exemplo
kubectl --context lab -n dev get pods
-l / --selector
Filtra os objetos segundo os seus labels; permite visar um subconjunto funcional.
Exemplo
kubectl get pods -l app=web
-o jsonpath
Extrai campos precisos da resposta da API, útil para scripts e automatização.
Exemplo
kubectl get pod web-abc -o jsonpath="{.status.phase}"
--watch / -w
Observa continuamente as modificações de uma lista de recursos.
Exemplo
kubectl get pods -w
kubectl config view --minify
Apresenta as informações relativas ao contexto ativo, para verificar a configuração utilizada.
Exemplo
kubectl config view --minify
Atenção: certas saídas de configuração podem conter informações sensíveis.