K3s Kubernetes leve: implantação rápida de cluster para homelab e edge

Se você quer Kubernetes sem o overhead de um control plane pesado, K3s é uma opção extremamente prática. Ele é pequeno, rápido de instalar e compatível com ferramentas padrão do ecossistema Kubernetes.

Este passo a passo oferece uma base sólida com um nó servidor e workers opcionais para laboratório doméstico, filiais ou ambientes de borda.

Pré-requisitos

  • Host Linux (Ubuntu, Debian ou RHEL)
  • Mínimo de 2 vCPU e 2–4 GB RAM por nó
  • Portas de comunicação do cluster liberadas
  • Hostname estável e sincronização de horário

1) Instale o primeiro nó (server)

curl -sfL https://get.k3s.io | sh -

Valide o serviço:

sudo systemctl status k3s
sudo k3s kubectl get nodes -o wide

No K3s, o wrapper k3s já expõe o kubectl para uso imediato.

2) Ajuste o kubeconfig para uso diário

mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown "$(id -u):$(id -g)" ~/.kube/config

Para acesso remoto, substitua 127.0.0.1 no arquivo de configuração pelo IP ou DNS do servidor.

3) Adicione um worker (opcional)

No servidor, obtenha o token:

sudo cat /var/lib/rancher/k3s/server/node-token

No worker:

curl -sfL https://get.k3s.io | \
  K3S_URL=https://<SERVER_IP>:6443 \
  K3S_TOKEN=<NODE_TOKEN> sh -

Confira se o nó entrou:

sudo k3s kubectl get nodes

4) Faça um deploy de teste

sudo k3s kubectl create deployment hello-nginx --image=nginx:stable
sudo k3s kubectl expose deployment hello-nginx --type=ClusterIP --port=80
sudo k3s kubectl get pods,svc -o wide

Para validação externa rápida, use NodePort ou Ingress conforme seu desenho de rede.

5) Base operacional recomendada

Observabilidade inicial

Inclua no mínimo:

  • Coleta de métricas
  • Acesso a logs de containers
  • Alertas de memória e disco

Planejamento de upgrade

Atualizações no K3s são simples, mas devem ser controladas:

  1. Backup/snapshot
  2. Upgrade em nó não crítico
  3. Validação de workloads
  4. Rollout nos demais nós

Estratégia de backup

  • Backups de /etc/rancher/k3s/
  • Snapshots do datastore
  • Testes regulares de restauração

Problemas comuns

Nós não entram no cluster

Cheque:

  • K3S_URL com https://
  • Porta 6443 acessível
  • Token correto
  • Relógio sincronizado em todos os nós

Pods presos em Pending

Geralmente é falta de recursos ou taints:

sudo k3s kubectl describe pod <pod-name>
sudo k3s kubectl describe node <node-name>

DNS interno falhando

Verifique o CoreDNS:

sudo k3s kubectl -n kube-system get pods | grep coredns

Conclusão

K3s é excelente para quem precisa de Kubernetes com menor fricção operacional. Em homelab, edge e ambientes menores, ele entrega velocidade de implantação e boa previsibilidade.

Comece simples, garanta estabilidade e depois evolua para ingress, classes de storage, políticas de segurança e monitoramento completo.