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

No capítulo 02 subimos um cluster com um master. Funciona para aprender, mas é um ponto único de falha: se aquele nó cair, o kubectl para, o scheduler para e novos pods não são criados.

Alta disponibilidade de control plane não é “ter três máquinas”. É ter três etcds com quórum, um endpoint estável e um processo de join que aguente a queda de um membro.

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

Topologia

Nome	IP	Papel
k8s-master-01	192.168.56.10	control plane + etcd
k8s-master-02	192.168.56.11	control plane + etcd
k8s-master-03	192.168.56.12	control plane + etcd
VIP	192.168.56.100	endpoint do API server
workers	192.168.56.21–23	cargas

O endpoint 192.168.56.100:6443 precisa apontar para os três masters. Quem faz isso pode ser:

• kube-vip (VIP com ARP/BGP, roda como static pod).
• HAProxy/nginx stream + keepalived (VIP na camada 4).
• Um load balancer de cloud.

Neste curso usamos a ideia do kube-vip/HAProxy: um IP virtual que sobrevive à queda de um master.

Por que o número de masters precisa ser ímpar

O etcd usa consenso Raft. A maioria precisa estar disponível:

Masters	Quórum	Tolera falhas
1	1	0
2	2	0 (pior que 1)
3	2	1
5	3	2

Com 2 masters, você não tolera nenhuma falha. Por isso o mínimo sério é 3. Nunca suba HA com 2.

1. Preparar o endpoint estável

Você tem duas opções práticas.

Opção A — kube-vip

O kube-vip roda como static pod e anuncia o VIP na rede. O manifesto fica em /etc/kubernetes/manifests/kube-vip.yaml, com vip, interface e a imagem do kube-vip. Ele é criado antes do kubeadm init e sobrevive ao control plane.

Opção B — HAProxy + keepalived

Exemplo de frontend TCP:

frontend k8s-api
    bind *:6443
    mode tcp
    default_backend k8s-api

backend k8s-api
    mode tcp
    balance roundrobin
    option tcp-check
    server master1 192.168.56.10:6443 check
    server master2 192.168.56.11:6443 check
    server master3 192.168.56.12:6443 check

O keepalived mantém o VIP 192.168.56.100 em um dos proxies. Se o proxy ativo cair, o VIP migra.

Atenção: o endpoint precisa existir antes do kubeadm init. Trocar o endpoint depois é uma cirurgia. Planeje desde o começo.

2. Inicializar o primeiro master

No master-01:

sudo kubeadm init \
  --control-plane-endpoint=192.168.56.100:6443 \
  --pod-network-cidr=10.244.0.0/16 \
  --upload-certs

--upload-certs publica os certificados necessários para os outros masters no cluster (criptografados com uma certificate-key temporária).

Guarde a saída: ela traz o comando de join de workers e de control planes.

3. Join dos outros masters

No master-02 e master-03:

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

Se a certificate-key expirar, gere outra no master-01:

sudo kubeadm init phase upload-certs --upload-certs

Depois do join, valide:

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

Você deve ver três apiservers, três etcds, três schedulers e três controllers.

4. Join dos workers

sudo kubeadm join 192.168.56.100:6443 \
  --token <token> \
  --discovery-token-ca-cert-hash sha256:<hash>

5. Verificar o etcd

O etcd é o coração do HA. Liste os membros:

kubectl -n kube-system exec etcd-k8s-master-01 -- \
  etcdctl --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/server.crt \
  --key=/etc/kubernetes/pki/etcd/server.key \
  member list

Confira:

• 3 membros, todos started.
• Um líder eleito.
• etcdctl endpoint health saudável nos três.

Se o etcd perder quórum (2 de 3), o control plane para de aceitar escritas. Recuperar quórum é um procedimento de emergência: restaure snapshot ou remova o membro morto com member remove.

6. Teste de falha

Faça o teste antes de precisar dele em produção:

# em um master, pare o kubelet (simula falha do nó)
sudo systemctl stop kubelet

# em outro terminal
kubectl get nodes
kubectl get pods -A | head

O kubectl deve continuar funcionando via VIP, e o etcd deve manter quórum com 2/3. Depois:

sudo systemctl start kubelet

Se você desligar o master inteiro, o comportamento é o mesmo — desde que o VIP migre e o etcd mantenha 2/3.

7. Erros comuns

Sintoma	Causa provável
connection refused no VIP	kube-vip/HAProxy não subiu ou health check falhou
join de master falha	certificate-key expirada
etcdserver: no leader	quórum perdido (2 masters fora)
apiserver reinicia em loop	certificado ou endpoint errado
workers não entram	token expirado ou hash errado
HA “funciona” mas cai com 1 master	você subiu com 2 masters

Checklist

• [ ] VIP/endpoint estável definido antes do init.
• [ ] 3 masters com etcd stacked.
• [ ] --control-plane-endpoint igual em todos.
• [ ] kubectl get nodes mostra 3 control planes.
• [ ] etcdctl member list com 3 membros e líder.
• [ ] Teste de falha de 1 master documentado.
• [ ] Snapshot do etcd configurado.

Glossário

• quórum: maioria necessária para o etcd decidir.
• VIP: IP virtual que migra entre nós.
• stacked etcd: etcd rodando no mesmo nó do control plane.
• certificate-key: chave para distribuir certificados aos masters.
• fencing: garantir que o nó antigo não continue escrevendo.

Próximo

Com o control plane em HA, vamos falar da rede dos pods: flannel, Cilium e por que NetworkPolicy pode ser um no-op se você escolher a CNI errada.

Próximo: Curso Kubernetes 06 — CNI: flannel, Cilium e NetworkPolicy