Curso Kubernetes 04 — kubeadm por dentro: certificados, static pods e o join

No capítulo 02 rodamos kubeadm init e vimos o cluster subir. Funcionou — mas o que exatamente aquele comando fez?

Essa é a diferença entre “ter um cluster” e “operar um cluster”. Quando algo quebra às 3 da manhã, você precisa saber onde estão os certificados, quais pods são estáticos, como renovar um token e o que acontece no upgrade.

Selo do curso: testado em Kubernetes 1.35 e Ubuntu 24.04. IPs fictícios (192.168.56.x).

O que o kubeadm cria

Ao rodar kubeadm init, ele gera:

Caminho	Conteúdo
/etc/kubernetes/manifests/	static pods do control plane
/etc/kubernetes/pki/	CA, certificados do apiserver, etcd, service account
/etc/kubernetes/*.conf	kubeconfigs (admin, controller-manager, scheduler)
/var/lib/kubelet/	configuração e dados do kubelet
/etc/cni/net.d/	configuração da CNI (depois)

O control plane não é um “serviço systemd” tradicional. Ele roda como static pods, que o kubelet inicia a partir dos manifestos em /etc/kubernetes/manifests. Se você editar o YAML do apiserver ali, o kubelet recria o pod automaticamente.

ls -l /etc/kubernetes/manifests/
sudo crictl pods | head
kubectl -n kube-system get pods -o wide

Você verá kube-apiserver, kube-controller-manager, kube-scheduler e etcd como pods com nome terminando no hostname do nó.

Certificados: o que expira e quando

O cluster vive de TLS. O kubeadm cria uma PKI local:

sudo ls -l /etc/kubernetes/pki/
sudo kubeadm certs check-expiration

A saída mostra a validade de cada certificado. Por padrão, muitos expiram em 1 ano. Se o apiserver parar de responder com erro de TLS, verifique isso primeiro.

Renovação manual:

sudo kubeadm certs renew all
sudo systemctl restart kubelet

Em clusters de longa duração, automatize a renovação ou faça parte do runbook de manutenção. Certificado vencido não é “bug de Kubernetes”; é operação.

Tokens de join

O kubeadm init imprime um comando de join com token e hash. O token expira (24h por padrão). Para gerar outro:

sudo kubeadm token list
sudo kubeadm token create --print-join-command

O hash é o sha256 da CA pública. Se o token expirou, o comando acima resolve. Se a CA mudou (cluster recriado), o hash antigo não serve.

Para adicionar um control plane (HA), o comando é diferente:

sudo kubeadm join 192.168.56.10:6443 \
  --token <token> \
  --discovery-token-ca-cert-hash sha256:<hash> \
  --control-plane --certificate-key <key>

A --certificate-key é gerada com kubeadm init phase upload-certs --upload-certs. Vamos usar isso no capítulo 05.

O kubeconfig

O arquivo ~/.kube/config aponta para o apiserver e carrega o certificado de cliente. Se você perder acesso:

sudo cp /etc/kubernetes/admin.conf ~/.kube/config
sudo chown $(id -u):$(id -g) ~/.kube/config
kubectl get nodes

Nunca copie esse arquivo para locais inseguros: ele dá acesso administrativo ao cluster.

Upgrade do control plane

O upgrade é uma operação de manutenção, não um apt upgrade qualquer.

sudo kubeadm upgrade plan
sudo apt-mark unhold kubeadm
sudo apt install -y kubeadm=1.35.x-1.1
sudo apt-mark hold kubeadm
sudo kubeadm upgrade apply v1.35.x

Depois, atualize kubelet e kubectl no nó e reinicie o kubelet. Em HA, um master por vez; nunca todos juntos.

Nos workers, o fluxo é:

kubectl drain <worker> --ignore-daemonsets --delete-emptydir-data
sudo apt-mark unhold kubeadm kubelet
sudo apt install -y kubeadm=1.35.x-1.1 kubelet=1.35.x-1.1 kubectl=1.35.x-1.1
sudo kubeadm upgrade node
sudo systemctl restart kubelet
kubectl uncordon <worker>

A regra é: um nó por vez, validando kubectl get nodes e as cargas antes de seguir.

Reset: quando refazer

Se o laboratório quebrar sem volta:

sudo kubeadm reset -f
sudo rm -rf /etc/cni/net.d /var/lib/cni /var/lib/kubelet
sudo systemctl restart containerd kubelet

Em HA, isso é mais delicado: remova o nó do cluster, limpe o etcd e recrie. Faça backup antes.

Laboratório do capítulo

1. Liste os static pods:

kubectl -n kube-system get pods -o wide
sudo crictl pods | grep -E 'kube-apiserver|etcd|scheduler'

2. Verifique a validade dos certificados:

sudo kubeadm certs check-expiration

3. Gere um novo token de join:

sudo kubeadm token create --print-join-command

4. Veja o kubeconfig e o endpoint:

kubectl config view --minify
kubectl cluster-info

5. (Opcional) Em um cluster descartável, teste kubeadm upgrade plan.

Erros comuns

Sintoma	Causa provável
x509: certificate has expired	certificado vencido; kubeadm certs renew
bootstrap token expired	token de join expirou; gere outro
etcdserver: request timed out	disco lento ou quórum perdido
apiserver não sobe após editar manifesto	YAML inválido em /etc/kubernetes/manifests
upgrade falha no meio	versão de kubelet/kubeadm inconsistente
nó não volta após upgrade	kubelet parado ou CNI sem config

Checklist

• [ ] Sei onde ficam os static pods do control plane.
• [ ] Sei verificar a validade dos certificados.
• [ ] Sei gerar um token de join novo.
• [ ] Entendi o papel do kubeconfig.
• [ ] Conheço o fluxo de upgrade de um nó.
• [ ] Sei quando (e como) fazer reset.

Glossário

• PKI: infraestrutura de chaves e certificados.
• static pod: pod gerenciado diretamente pelo kubelet via manifesto.
• bootstrap token: token temporário para o join.
• certificate-key: chave usada para distribuir certificados a novos control planes.
• drain/uncordon: evacuar e liberar um nó para manutenção.

Próximo

Agora que você entende o que o kubeadm criou, vamos colocar o control plane em HA: 3 masters, endpoint estável e etcd com quórum.

Próximo: Curso Kubernetes 05 — HA: 3 masters, VIP e etcd