kubectl, o controle remoto do cluster

Público: iniciante, Kubernetes do Docker Desktop ativado (lição 02)
Duração: 35 a 45 min
Módulo: 1/8
Competência alvo: saber qual binário kubectl responde e para qual cluster ele fala, corrigir um aviso de versão, ler um comando kubectl como uma frase (verbo, recurso, nome, opções) e criar seu primeiro namespace

Em uma imagem

kubectl é um controle remoto universal. Ele não faz nada por si mesmo: envia ordens para um dispositivo, o API server da lição 01, em HTTPS na porta 6443. Ele tem um seletor de fonte, o contexto, que diz qual cluster visar (docker-desktop, um velho minikube, a produção da sua empresa): aperte "Play" mirando no dispositivo errado e nada se move, você acha o controle quebrado. Ele tem baterias de uma certa tensão: um kubectl 1.30 na frente de um cluster 1.34 funciona mais ou menos, mas o avisa que não garante mais nada. E fala uma gramática fixa: um verbo (get), um recurso (pods), às vezes um nome, depois opções (-n primeiros-passos -o wide). Em quarenta minutos você lerá essa frase de primeira, terá corrigido um verdadeiro pêgo de versão, e terá aberto sua própria gaveta no cluster: o namespace primeiros-passos, onde todo o módulo vai acontecer.

Como funciona

kubectl lê um único arquivo na inicialização: ~/.kube/config (C:\Users\<você>\.kube\config no Windows), o kubeconfig. Ele contém três listas: clusters (um endereço de API e o certificado que permite reconhecê-lo), users (os identificadores: aqui um certificado de cliente gerado pelo Docker Desktop) e contexts, que associam um cluster a um usuário, com opcionalmente um namespace padrão. A linha current-context designa aquele que cada comando usa. Docker Desktop escreve docker-desktop na ativação; minikube, kind ou um provedor de nuvem adicionam os seus, e é assim que um mesmo kubectl pilota múltiplos clusters.

Cada comando se lê como uma frase: kubectl <verbo> <recurso> [nome] [opções]. O verbo diz o que fazer; o recurso, em qual tipo de objeto; o nome visa um objeto específico (sem nome, o verbo se aplica a todos no namespace); as opções especificam a gaveta (-n), o formato (-o), o escopo (-A) ou o acompanhamento ao vivo (-w). Os recursos aceitam atalhos que kubectl api-resources lista em sua coluna SHORTNAMES.

Pedaço	Exemplos	Papel
verbo	`get`, `describe`, `create`, `apply`, `delete`, `logs`, `exec`, `scale`, `explain`	a ação pedida à API
recurso	`pods` (`po`), `deployments` (`deploy`), `services` (`svc`), `namespaces` (`ns`), `nodes` (`no`)	o tipo de objeto; `pod/api` equivale a `pod api`
nome	`api`, `api-9bfb55fc6-988xh`, `docker-desktop`	um objeto específico; ausente = todos os objetos do namespace
`-n <ns>`	`-n primeiros-passos`	o namespace visado; sem ele, `default` (o curso nunca o usa)
`-A`	`kubectl get pods -A`	todos os namespaces (adiciona uma coluna `NAMESPACE`)
`-o wide` / `-o yaml` / `-o json` / `-o name`	`kubectl get pods -o wide`	mais colunas / o objeto completo como a API o armazena / o mesmo em JSON / apenas `tipo/nome`
`-w`	`kubectl get pods -n primeiros-passos -w`	fica conectado e exibe cada mudança (Ctrl+C para sair)
`--help`	`kubectl get --help`	a ajuda de qualquer verbo, com exemplos

Os namespaces são as gavetas do cluster: um mesmo nome de Pod ou Service pode existir em dois namespaces sem conflito, as quotas e os direitos se prendem ao namespace, e kubectl delete namespace esvazia tudo de uma vez. O cluster nasce com default, kube-system (o plano de controle), kube-public e kube-node-lease. Este curso nunca escreve em default: cada módulo tem seu namespace, e cada comando carrega -n. Esquecer -n significa procurar seu Pod na gaveta errada: ele "não existe", enquanto roda muito bem ao lado. Você provocará esse erro na prática guiada para nunca mais cair nela.

O que você quer saber	Comando	Fala com o cluster?
qual binário responde	`where.exe kubectl` (Windows) / `which -a kubectl` (bash)	não
versão do cliente e do servidor	`kubectl version`	sim
para qual cluster eu aponto	`kubectl config current-context`	não
todos os clusters conhecidos	`kubectl config get-contexts`	não
o que contém um campo YAML	`kubectl explain deployment.spec.replicas`	sim
todos os tipos de objetos e seus atalhos	`kubectl api-resources`	sim

Passo a passo

Na máquina do curso, PowerShell guarda propositalmente um pêgo: três kubectl no PATH, incluindo um velho 1.30 instalado manualmente antes do Docker Desktop. Na sua máquina provavelmente há apenas um; mesmo assim faça as etapas 1 a 3, elas o evitarão de uma hora de confusão no dia em que instalar uma segunda ferramenta.

Encontre qual kubectl responde. O shell pega o primeiro binário encontrado na ordem do PATH.
powershell
```
where.exe kubectl
```
bash
```
which -a kubectl
```
Saída real (Windows):
text
```
C:\Program Files\Docker\Docker\resources\bin\kubectl.exe
C:\Users\<você>\Documents\kubectl\kubectl.exe
C:\kubectl\kubectl.exe
```
O que observar: a primeira linha é aquela que se executa quando você digita kubectl. Aqui é a do Docker Desktop, porque o PATH foi reordenado; a etapa 2 mostra o que acontece quando não é. No macOS, espere /usr/local/bin/kubectl (Docker Desktop) e talvez /opt/homebrew/bin/kubectl (Homebrew).
Observe bem o que vai acontecer: lance o velho kubectl propositalmente. Na máquina do curso, o segundo binário é um 1.30. Chamado pelo caminho completo na frente do cluster 1.34:
powershell
```
& "C:\Users\<você>\Documents\kubectl\kubectl.exe" version
```
Saída real:
text
```
Client Version: v1.30.0
Kustomize Version: v5.0.4-0.20230601165947-6ce0bf390ce3
Server Version: v1.34.1
WARNING: version difference between client (1.30) and server (1.34) exceeds the supported minor version skew of +/-1
```
O que observar: o comando responde mesmo assim (o cluster é alcançável), mas o aviso é explícito: Kubernetes não garante kubectl com uma versão menor de diferença do servidor (1.33, 1.34 ou 1.35 para um cluster 1.34). Além disso, alguns sub-comandos se comportam estranhamente ou ignoram campos recentes. Se você vê essa linha na sua máquina, é este pêgo: um velho kubectl (Homebrew, Chocolatey, download manual) passa na frente do do Docker Desktop.
Corrija a ordem do PATH. Para a sessão atual do PowerShell, depois verifique:
powershell
```
$env:Path = "C:\Program Files\Docker\Docker\resources\bin;" + $env:Path
kubectl version
```
Saída real:
text
```
Client Version: v1.34.1
Kustomize Version: v5.7.1
Server Version: v1.34.1
```
O que observar: cliente e servidor alinhados em v1.34.1, nenhum aviso. Para tornar a mudança permanente no Windows: Configurações → Sistema → Informações do sistema → Configurações avançadas do sistema → Variáveis de ambiente → Path do seu usuário → mova C:\Program Files\Docker\Docker\resources\bin para o início (ou remova a entrada do velho kubectl), depois reabra o terminal. No macOS/Linux, remova o duplicado (brew uninstall kubectl) ou coloque /usr/local/bin em primeiro em seu ~/.zshrc. O script do kit verifica para você: .\labo.ps1 prerequis exibe ✘ kubectl client v1.30.0 muito antigo (mínimo 1.33) — … enquanto a ordem estiver errada.
Leia o kubeconfig e o contexto atual. Dois comandos que não tocam o cluster.
bash
```
kubectl config get-contexts
kubectl config current-context
```
Saída real:
text
```
CURRENT   NAME             CLUSTER          AUTHINFO         NAMESPACE
*         docker-desktop   docker-desktop   docker-desktop
          minikube         minikube         minikube         default
docker-desktop
```
O que observar: o asterisco em docker-desktop. A máquina do curso mantém um contexto minikube de um antigo cluster parado: é o tipo de resto que faz você dizer "kubectl não funciona mais" quando vira o contexto atual por acidente. Se na sua máquina o asterisco está em outro lugar, kubectl config use-context docker-desktop o move (não digite se já estiver no lugar certo: o comando reescreve ~/.kube/config). A coluna NAMESPACE vazia significa "default a menos que eu passe -n"; você não a preencherá, o curso quer que -n seja um reflexo.

Leia um comando como uma frase, com explain. O manual está no cluster: kubectl explain pede ao API server a documentação de um tipo ou campo, para a versão exata que você usa.

bash

kubectl explain deployment.spec.replicas

Saída real:

text

GROUP:      apps
KIND:       Deployment
VERSION:    v1

FIELD: replicas <integer>

DESCRIPTION:
    Number of desired pods. This is a pointer to distinguish between explicit
    zero and not specified. Defaults to 1.

Depois desça um nível em um Pod:

bash

kubectl explain pod.spec.containers

Saída real:

text

GROUP:      <empty>
KIND:       Pod
VERSION:    v1

FIELD: containers <[]Object>

DESCRIPTION:
    List of containers belonging to the pod. Containers cannot currently be
    added or removed. There must be at least one container in a Pod…

O que observar: grupo <empty> para um Pods (tipo fundamental), apps para um Deployment. A versão sempre coincide com a do servidor (v1 aqui). Use esse comando toda vez que esquecer um nome de campo; é mais rápido que Google.

Crie um namespace para o módulo. Todo o módulo usará -n primeiros-passos, você criará objetos lá, a última etapa o suprimirá de uma vez.
bash
```
kubectl create namespace primeiros-passos
```
Saída real:
text
```
namespace/primeiros-passos created
```
O que observar: created. Se você lê AlreadyExists, você o guardou de um experimento anterior: sem problema, continue.

Verificar que o namespace existe. Duas maneiras equivalentes de vê-lo.

bash

kubectl get ns
kubectl get namespaces

Saída real:

text

NAME               STATUS   AGE
default            Active   18d
kube-node-lease    Active   18d
kube-public        Active   18d
kube-system        Active   18d
primeiros-passos   Active   5s

O que observar: primeiros-passos está lá, Active. Os quatro primeiros vêm com o cluster.

Se der problema

where.exe kubectl retorna nada → kubectl não está instalado, ou não está no PATH. Verifique que Docker Desktop está ativado (Configurações → Kubernetes → Enable Kubernetes), reabra o terminal.
kubectl config get-contexts mostra apenas um contexto, e não é docker-desktop → você está apontando para outro cluster (minikube, kind). Docker Desktop adicionaria seu próprio contexto; talvez ele não tenha sido ativado ou seu ~/.kube/config foi perdido. Lance docker desktop kubernetes enable (ou manualmente em Configurações → Kubernetes → Enable Kubernetes).
Erro current-context is not set → não há contexto ativo em ~/.kube/config. Digite kubectl config use-context docker-desktop para escolher um.

Para reter

kubectl é uma ferramenta universal: começa procurando no ~/.kube/config qual cluster visar, depois envia a solicitação ao API server em HTTPS na porta 6443.
O contexto diz para qual cluster apontar; verifique com kubectl config current-context; troque com kubectl config use-context <contexto>.
A versão do cliente deve estar dentro de uma versão menor do servidor: kubectl version mostra as duas; um aviso significa um velho kubectl fora do PATH.
Cada comando carrega a estrutura kubectl <verbo> <recurso> [nome] [opções]; -n é a opção que escolhe o namespace.
Os namespaces são gavetas do cluster; o curso usa -n sempre, nunca deixa nada no default.
kubectl explain <tipo>.<campo> fornece a documentação de um campo, para a versão exata do seu cluster.
Próxima lição: seu primeiro deploy com um Deployment, três réplicas, e um LoadBalancer em localhost.

Para ir mais longe

A página Kubernetes API Conventions descreve a gramática dos comandos kubectl. A documentação kubectl reference detalha cada subcomando. A página Organizing cluster access using kubeconfig files explica toda a sintaxe do ~/.kube/config.