Como Montar um Cluster Kubernetes Leve (K3s) no Ubuntu Server: Passo a Passo [2026]

O Kubernetes (K8s) tornou-se o padrão incontestável para orquestração de contêineres em escala global. No entanto, instalar e operar um cluster tradicional do Kubernetes (com kubeadm ou etcd dedicado) consome muita memória RAM e exige uma infraestrutura pesada. É aqui que entra o K3s: uma distribuição oficial do Kubernetes, 100% certificada pela CNCF (Cloud Native Computing Foundation) e desenvolvida pela Rancher Labs (consulte a Documentação Oficial do K3s e o portal da Kubernetes Foundation), compactada em um único binário de ~50MB que roda com apenas 512MB de RAM!

Neste tutorial passo a passo atualizado para 2026, você aprenderá como configurar um cluster K3s completo no Ubuntu Server (com 1 nó Master Control Plane e nós Workers), fazer o join seguro via token e realizar o deploy da sua primeira aplicação com kubectl.

1. O Que É o K3s e Por Que Ele É a Escolha Ideal?

O K3s removeu drivers legados da nuvem e módulos alfa do código-fonte do Kubernetes padrão, substituindo componentes pesados por alternativas extremamente eficientes:

• Banco de Dados Leve: Usa SQLite por padrão para clusters de nó único ou nós locais (com suporte a etcd distribuído ou MySQL/PostgreSQL para alta disponibilidade).
• Container Runtime Integrado: Já vem com o containerd e o Flannel CNI pré-configurados prontos para uso.
• Ingress Controller Nativo: Já inclui o Traefik Ingress e balanceador de carga de rede (Klipper LoadBalancer) embutidos de fábrica.
• Baixíssimo Consumo: Perfeito para servidores VPS modestos, laboratórios em Proxmox VE, Raspberry Pi e ambientes de Edge Computing.

2. Tabela Comparativa: K3s vs Kubernetes Padrão vs MicroK8s vs Minikube

3. Diagrama da Arquitetura do Cluster K3s

┌─────────────────────────────────────────────────────────────┐
│  NÓ MASTER (Control Plane - IP: 192.168.0.100)               │
│  • K3s Server (API Server, Controller, Scheduler, SQLite)   │
│  • Traefik Ingress Controller + Flannel CNI                 │
│  • Porta 6443 (Comunicação dos Workers)                    │
└──────────────────────────────┬──────────────────────────────┘
                               │  Token Seguro (Porta 6443)
            ┌──────────────────┴──────────────────┐
            ▼                                     ▼
┌─────────────────────────────┐       ┌─────────────────────────────┐
│  NÓ WORKER 1 (k3s-agent)     │       │  NÓ WORKER 2 (k3s-agent)     │
│  • IP: 192.168.0.101        │       │  • IP: 192.168.0.102        │
│  • Kubelet + Containerd     │       │  • Kubelet + Containerd     │
│  • Roda Pods / Containers   │       │  • Roda Pods / Containers   │
└─────────────────────────────┘       └─────────────────────────────┘

4. Pré-requisitos e Preparação do Ubuntu Server

Antes de iniciar a instalação, execute estes passos de preparação em todas as máquinas (Master e Workers):

Passo A: Desativar a Memória Swap

O Kubernetes exige que o swap esteja desativado para garantir a estabilidade dos agendamentos de pods:

# Desativar swap imediatamente
sudo swapoff -a

# Desativar permanentemente no fstab
sudo sed -i '/swap/s/^/#/' /etc/fstab

Passo B: Definir os Nomes de Host (Hostnames)

# No Nó Master:
sudo hostnamectl set-hostname k3s-master

# No Nó Worker 1:
sudo hostnamectl set-hostname k3s-worker01

5. Instalando o Nó Master (Control Plane)

Acesse o servidor Master via SSH Seguro com chaves e execute o instalador oficial do K3s com permissão de leitura no kubeconfig:

# Instalação do K3s Server no Master
curl -sfL https://get.k3s.io | sh -s - --write-kubeconfig-mode 644

# Verificar o status do serviço
sudo systemctl status k3s

# Testar se o nó Master está com status 'Ready'
kubectl get nodes

Obtendo o Token de Segurança do Cluster:

Para conectar os nós Workers ao Master, copie o token gerado automaticamente pelo K3s:

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

Guarde essa string longa (ex: K108abcde...::server:7f89a...), pois ela será usada no comando de join dos workers.

6. Conectando os Nós Workers ao Cluster

Acesse o servidor Worker via terminal e execute o comando abaixo, substituindo o IP pelo IP do seu Master e o Token pelo valor obtido no passo anterior:

# No servidor Worker:
curl -sfL https://get.k3s.io | K3S_URL=https://192.168.0.100:6443 K3S_TOKEN="SEU_TOKEN_AQUI" sh -

Volte ao terminal do Nó Master e execute kubectl get nodes. Você verá todos os nós listados e operacionais:

kubectl get nodes -o wide

# Saída esperada:
# NAME           STATUS   ROLES                  AGE     VERSION
# k3s-master     Ready    control-plane,master   5m      v1.30.2+k3s1
# k3s-worker01   Ready                     1m      v1.30.2+k3s1

7. Primeiro Deploy Real: Subindo um Servidor NGINX no Cluster

Vamos criar uma aplicação real no cluster para validar o balanceamento de carga entre os nós:

# 1. Criar um Deployment com 3 réplicas do NGINX
kubectl create deployment meu-nginx --image=nginx:alpine --replicas=3

# 2. Expor a aplicação via serviço NodePort
kubectl expose deployment meu-nginx --port=80 --type=NodePort

# 3. Conferir os Pods rodando distribuídos entre o Master e o Worker
kubectl get pods -o wide

# 4. Descobrir a porta de acesso externa
kubectl get svc meu-nginx

Abra o navegador no IP de qualquer nó do cluster na porta gerada (ex: http://192.168.0.100:31254) e você verá a tela de boas-vindas do NGINX rodando diretamente no seu cluster Kubernetes!

8. Cheat Sheet: Comandos Essenciais do kubectl no Dia a Dia

9. Guia de Resolução de Problemas: 5 Erros Comuns no K3s

1. CrashLoopBackOff no Traefik ou CoreDNS: Ocorre se a memória RAM do servidor for inferior a 512MB ou se o Swap estiver ativo. Solução: Execute sudo swapoff -a e aumente a memória disponível.
2. Worker não conecta no Master (Connection Refused): O nó worker não alcança a porta TCP 6443 do Master. Solução: No Master, libere a porta no firewall com sudo ufw allow 6443/tcp.
3. Error: Node Token Mismatch: O token colado no comando de join do worker possui espaços extras ou caracteres faltando. Solução: Recopie o conteúdo limpo de /var/lib/rancher/k3s/server/node-token.
4. Conflito de Porta 80 com Apache/NGINX local: Se o host já tiver outro web server rodando, o Traefik Ingress do K3s falhará ao bindar na porta 80. Solução: Desative o NGINX do host ou configure o K3s com --disable traefik se for usar ingress externo.
5. Permissão Negada ao rodar kubectl: Ocorre se o arquivo /etc/rancher/k3s/k3s.yaml estiver protegido. Solução: Defina a permissão correta com sudo chmod 644 /etc/rancher/k3s/k3s.yaml ou use a flag --write-kubeconfig-mode 644.

Para automatizar o provisionamento dos nós de computação antes de instalar o cluster K3s, você pode utilizar scripts declarativos de Infraestrutura como Código (Terraform).

Perguntas Frequentes (FAQ)

O K3s é seguro para ser usado em ambiente de produção em 2026?

Sim! O K3s é um projeto oficial da CNCF totalmente testado para conformidade com a API do Kubernetes. Ele é amplamente utilizado em produção por empresas de tecnologia, provedores de IoT e datacenters de borda em todo o mundo.

Como posso controlar o cluster K3s a partir do meu computador pessoal?

Basta copiar o arquivo /etc/rancher/k3s/k3s.yaml do nó Master para o diretório ~/.kube/config do seu notebook, substituindo o endereço 127.0.0.1 pelo IP de rede do seu servidor Master.

Como desinstalar o K3s completamente se eu quiser recomeçar?

O K3s cria scripts de limpeza automáticos. No Master, execute /usr/local/bin/k3s-uninstall.sh. Nos nós Workers, execute /usr/local/bin/k3s-agent-uninstall.sh.

Qual a diferença entre K3s e Docker Compose?

O Docker Compose gerencia múltiplos containers em uma única máquina. O K3s gerencia e orquestra containers distribuídos em dezenas de servidores ao mesmo tempo, com auto-recuperação (reinicia containers que caem), escalonamento automático e balanceamento de carga de rede integrado.

📚 Você Também Pode Gostar

Perdi meu Cartão de Crédito: O Que Fazer? (Checklist de Emergência 2026)

Ler mais →

Guia Prático de Shell Script no Linux [Com Exemplos Reais 2026]

Ler mais →

Guia de Estudos Microsoft Azure Fundamentals (AZ-900) em Português [2026]

Ler mais →

Tabela Completa de Permissões no Linux: chmod, chown e Notação Octal Explicada [Guia 2026]

Ler mais →