Instale o k3s em servidor dedicado: nó único para começar ou cluster com 3 VMs no Proxmox, portas, firewall, kubeconfig e verificação.

Para que serve

Este guia mostra como instalar o k3s, uma distribuição Kubernetes certificada e enxuta (um único binário com containerd, CoreDNS, Traefik, ServiceLB e um provisionador de volumes locais), em um servidor dedicado. São dois cenários: nó único, direto no Debian/Ubuntu ou em uma VM, e cluster com três VMs no Proxmox VE, para aprender alta disponibilidade e fazer manutenção sem parar as aplicações.

Se você ainda está decidindo entre Kubernetes e Docker Compose, leia antes o artigo Kubernetes ou Docker Compose: quando vale a pena migrar nesta mesma categoria.

Pré-requisitos

  • Debian 12/13 ou Ubuntu 24.04 (servidor físico ou VM). Mínimo pelo projeto: 2 vCPU e 2 GB de RAM por nó servidor; para uso real, reserve 4 vCPU e 8 GB ou mais.
  • Hostname único em cada nó (hostnamectl set-hostname k3s-1) e relógio sincronizado (timedatectl).
  • Acesso root ou sudo e o console IPMI/iLO à mão, caso precise mexer em firewall.
  • Para o cenário em cluster: Proxmox VE 8.x/9.x configurado (veja Primeiros passos no Proxmox VE e Configurar a rede do Proxmox para as VMs).

Portas usadas pelo k3s

PortaProtocoloEntreUso
6443TCPnós e administradores → servidoresAPI do Kubernetes
2379-2380TCPservidor ↔ servidoretcd embutido (só em cluster HA)
8472UDPtodos os nósFlannel VXLAN (rede dos pods)
10250TCPtodos os nóskubelet (métricas, logs, exec)
80 / 443TCPinternet → nósTraefik (entrada HTTP/HTTPS)
Atenção: nunca deixe a porta UDP 8472 (VXLAN) nem a 10250 abertas para a internet, e evite expor a 6443 publicamente. O ideal é que o tráfego entre nós passe por uma rede privada e que a API seja acessada pela VPN (veja Como fechar o acesso ao Proxmox, SSH e RDP e liberar só pela VPN). Se uma regra de firewall bloquear seu SSH, entre pelo console IPMI/iLO e desative a regra (ufw disable ou nft flush ruleset).

Cenário 1: instalar o k3s em nó único

  1. Crie o arquivo de configuração antes de instalar. O k3s lê /etc/rancher/k3s/config.yaml, o que deixa a instalação reprodutível: 
    mkdir -p /etc/rancher/k3s
cat > /etc/rancher/k3s/config.yaml <<'EOF'
write-kubeconfig-mode: "0600"
tls-san:
  - k3s.seudominio.com.br
  - 203.0.113.10
node-ip: 203.0.113.10
secrets-encryption: true
EOF
    Troque 203.0.113.10 pelo IP do servidor (ou da VM). O tls-san inclui nomes extras no certificado da API; o secrets-encryption criptografa os Secrets gravados no banco do cluster.
  2. Instale pelo script oficial no canal estável: 
    curl -sfL https://get.k3s.io | INSTALL_K3S_CHANNEL=stable sh -
    Para fixar uma versão exata (recomendado em produção, para todos os nós ficarem iguais), use INSTALL_K3S_VERSION=v1.36.5+k3s1 no lugar do canal. Consulte as versões vigentes em https://update.k3s.io/v1-release/channels.
  3. Confira o serviço: 
    systemctl status k3s --no-pager
k3s kubectl get nodes -o wide
    O nó deve aparecer como Ready em menos de um minuto.
  4. Use o kubectl no seu computador. Copie /etc/rancher/k3s/k3s.yaml para ~/.kube/config na sua máquina e troque server: https://127.0.0.1:6443 pelo IP ou nome do servidor acessível pela VPN. Proteja o arquivo: ele dá acesso de administrador ao cluster.

Cenário 2: cluster k3s com três VMs no Proxmox

Com três nós servidores, o etcd embutido mantém quórum mesmo com uma VM desligada. O número de servidores deve ser ímpar (3 ou 5). Lembre que as três VMs estão no mesmo hardware: isso protege contra falha ou manutenção de uma VM, não contra a queda do servidor físico.

  1. Crie uma rede privada para o cluster. No Proxmox, crie uma bridge sem porta física (ex.: vmbr1, rede 10.10.10.0/24). Cada VM recebe duas placas: vmbr0 com um IP público do bloco /28 (só se precisar receber tráfego de fora) e vmbr1 com o IP privado.
  2. Crie três VMs (ex.: 4 vCPU, 8 GB de RAM, disco VirtIO SCSI de 60 GB, CPU tipo host, QEMU Guest Agent ativo) com Debian 13 ou Ubuntu 24.04. Uma forma rápida é criar uma, transformar em template e clonar, regenerando o machine-id e o hostname de cada clone.
  3. No primeiro servidor, gere um token forte e inicie o cluster: 
    openssl rand -hex 32   # guarde este valor em local seguro
cat > /etc/rancher/k3s/config.yaml <<'EOF'
cluster-init: true
token: COLE_O_TOKEN_AQUI
node-ip: 10.10.10.11
flannel-iface: ens19
tls-san:
  - 10.10.10.11
  - k3s.seudominio.com.br
secrets-encryption: true
EOF
curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=v1.36.5+k3s1 sh -s - server
    O flannel-iface faz a rede dos pods trafegar pela placa privada (confira o nome com ip -br addr).
  4. Nos outros dois servidores, use o mesmo token e aponte para o primeiro: 
    cat > /etc/rancher/k3s/config.yaml <<'EOF'
server: https://10.10.10.11:6443
token: COLE_O_TOKEN_AQUI
node-ip: 10.10.10.12
flannel-iface: ens19
tls-san:
  - k3s.seudominio.com.br
secrets-encryption: true
EOF
curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=v1.36.5+k3s1 sh -s - server
    Todas as opções de rede e de componentes (como disable) precisam ser iguais em todos os servidores.
  5. (Opcional) Adicione nós agentes só para rodar cargas: 
    curl -sfL https://get.k3s.io | K3S_URL=https://10.10.10.11:6443 K3S_TOKEN=COLE_O_TOKEN_AQUI sh -

Como saber se funcionou

kubectl get nodes -o wide
kubectl get pods -A
kubectl create deployment teste --image=nginx:alpine
kubectl expose deployment teste --port=80
kubectl run curl --rm -it --image=curlimages/curl --restart=Never -- curl -s teste

Os nós devem estar Ready, os pods de kube-system em Running ou Completed, e o último comando deve devolver o HTML padrão do nginx. Apague o teste depois: kubectl delete deployment,svc teste.

Problemas comuns

Nó fica NotReady ou pods não se falam entre nós

Quase sempre é firewall bloqueando UDP 8472 ou a placa errada no Flannel. Libere as portas da tabela apenas na rede privada e confira o flannel-iface. Logs: journalctl -u k3s -f (servidor) ou journalctl -u k3s-agent -f (agente).

Erro de certificado ao usar o kubectl remoto

O endereço usado no kubeconfig não está no certificado. Inclua-o em tls-san e reinicie com systemctl restart k3s.

Instalei em container LXC e deu erro

Kubernetes precisa de módulos de kernel, cgroups e privilégios que um LXC sem privilégio não oferece. Use VMs (veja Containers LXC ou VMs no Proxmox VE).

Como desinstalar

Use /usr/local/bin/k3s-uninstall.sh nos servidores e /usr/local/bin/k3s-agent-uninstall.sh nos agentes. Isso apaga os dados do cluster.

Perguntas frequentes

k3s é Kubernetes de verdade?

Sim. É uma distribuição certificada pela CNCF; manifestos, Helm charts e o kubectl funcionam igual. O que muda é o empacotamento e os componentes que já vêm instalados.

Posso rodar o k3s direto no Proxmox, sem VM?

Não é recomendado. O host do Proxmox deve ficar só como hypervisor; misture as duas coisas e uma atualização de um pode quebrar o outro.

Um nó só serve para produção?

Serve para cargas que toleram alguns minutos de parada em manutenção, desde que você tenha backup (veja Backup de Kubernetes com etcd snapshot e Velero).

Como atualizo o k3s?

Rode de novo o script de instalação com a nova versão, um nó por vez, começando pelos servidores. Não pule versões menores (ex.: de 1.34 direto para 1.36).

Leitura complementar

Precisa de ajuda?

Se o servidor ficou inacessível depois de mudar rede ou firewall, use o console IPMI/iLO. Para dúvidas sobre o bloco de IPs ou a rede do datacenter, abra um ticket.

Esta resposta lhe foi útil? 0 Usuários acharam útil (0 Votos)

Leia também