Base de Conhecimento

K3s na VPS: Kubernetes leve no seu servidor

  • k3s, kubernetes, vps, contêineres, linux
  • Usuários acharam útil: 0

Kubernetes num binário único: instalação pelo script oficial, portas fora da internet, kubeconfig protegido, primeiro Deployment, novo nó com token e backup do cluster.

Por Redação Eleven Host · @robson.direitodigital · 22 de novembro de 2026 · 10 min de leitura

Arte da Eleven Host: janela de terminal com o título: K3s na VPS: Kubernetes leve no seu servidor

Capa da Redação Eleven Host para o guia: K3s na VPS: Kubernetes leve no seu servidor Arte: Eleven Host

K3s na VPS é rodar uma distribuição do Kubernetes empacotada num binário único, instalada com um script, para orquestrar contêineres em um servidor ou em poucos servidores ligados entre si.

Atualizado em 22/11/2026. Nada aqui foi executado no seu servidor: confira cada comando antes de usar e teste primeiro numa máquina sem dados importantes.

Em 22/11/2026, a versão do canal stable do K3s era a v1.37.2+k3s1, publicada em 03/11/2026, e o repositório k3s-io/k3s estava ativo, sob licença Apache-2.0. O único alerta de segurança de gravidade alta publicado no repositório, de 2023, já tem versões corrigidas, e as versões atuais estão fora do intervalo afetado.

O que é o Kubernetes e o que o K3s empacota

O Kubernetes é um sistema que mantém contêineres rodando conforme uma descrição. Três termos aparecem o tempo todo. O Pod é um grupo de um ou mais contêineres que dividem rede e armazenamento. O Deployment acompanha a saúde dos Pods, reinicia o contêiner que parar e é o jeito recomendado de criar e escalar Pods. O Service é a forma de expor um Pod: por padrão, ele só responde pelo IP interno do cluster.

Pela documentação oficial, o K3s é uma distribuição do Kubernetes totalmente compatível, distribuída como um binário único de menos de 100 MB, que só pede um kernel moderno e os cgroups montados. O banco padrão do cluster é o SQLite; etcd embutido, MySQL e PostgreSQL também são aceitos. Junto vêm, segundo a documentação oficial:

  • containerd: o motor que roda os contêineres;
  • Flannel: a rede entre os Pods;
  • CoreDNS: o DNS interno do cluster;
  • Traefik: o controlador de Ingress, que recebe o tráfego web;
  • ServiceLB: o balanceador para Services do tipo LoadBalancer;
  • Kube-router: o controlador de network policy;
  • Local-path-provisioner: volumes persistentes em pastas do próprio nó;
  • Spegel: um espelho distribuído de imagens de contêiner.

Para quem o K3s faz sentido

O K3s costuma interessar a uma pequena empresa ou a um desenvolvedor com 1 a 3 servidores que já usa contêineres e quer o jeito Kubernetes de trabalhar: arquivos YAML versionados, reinício automático, várias réplicas do mesmo app e a opção de somar outro servidor ao cluster depois. Também serve para aprender Kubernetes num ambiente real.

Nosso conselho: para um app só, com um banco e um proxy, o Docker Compose costuma bastar (há um artigo sobre ele na base, "Docker Compose: como usar na VPS, passo a passo"). O K3s passa a valer quando a equipe quer o modelo do Kubernetes. Uma VPS é um servidor virtual em que você instala e administra os programas; o que é e como escolher uma está em O que é servidor VPS: guia simples para iniciantes.

Um servidor para o primeiro nó

No K3s, o primeiro nó é o servidor, onde fica a API do cluster.

A máquina do primeiro nó pode ser um servidor virtual privado da Eleven Host. VPS a partir de R$ 29,90/mês no Plano Bronze; confira na loja o que cada plano inclui. Ver planos de VPS

Requisitos e portas

Pela página de requisitos, cada nó precisa de, no mínimo:

  • servidor: 2 núcleos de CPU e 2 GB de RAM;
  • agente: 1 núcleo de CPU e 512 MB de RAM.

A documentação recomenda SSD e avisa que versões antigas do Debian podem ter um bug conhecido do iptables. Recomendamos comparar esses mínimos com o servidor que você escolher, somando o que os seus apps vão usar.

Entre as portas de entrada que a documentação lista estão estas (há outras, só para recursos como Flannel WireGuard e o registro Spegel):

  • 6443/TCP: supervisor do K3s e API do Kubernetes, usada pelos agentes para falar com o servidor;
  • 8472/UDP: rede Flannel VXLAN entre os nós;
  • 10250/TCP: métricas e API do kubelet, entre os nós;
  • 2379-2380/TCP: só em alta disponibilidade com etcd embutido.

A documentação diz que a 8472 não deve ficar exposta, porque daria acesso à rede do cluster. Nosso conselho é tratar a 6443 e a 10250 do mesmo jeito: nunca abertas para a internet, só para os IPs dos outros nós ou por um túnel. Com um nó só, nosso conselho é não abrir nenhuma delas para fora.

Passo 1: firewall antes da instalação

A página de requisitos recomenda desligar o UFW. Para mantê-lo ligado, ela manda liberar a rede dos Pods (10.42.0.0/16) e a dos Services (10.43.0.0/16), as faixas padrão:

sudo ufw allow from 10.42.0.0/16 to any

sudo ufw allow from 10.43.0.0/16 to any

A mesma página traz ufw allow 6443/tcp, que abre a porta da API para qualquer origem. Em vez disso, nosso conselho, só quando houver um agente, é liberar a 6443 apenas para o IP dele, com uma regra montada por nós (troque o endereço de documentação pelo seu e confira a regra com sudo ufw status):

sudo ufw allow from 192.0.2.60 to any port 6443 proto tcp

Se mudar as faixas padrão de Pods ou Services, ajuste as regras.

Passo 2: instalar o K3s

O comando oficial do guia rápido baixa o script de instalação e o executa:

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

Nosso conselho é ler o script antes de rodar: use os três comandos a seguir no lugar do comando acima, porque a instalação é uma só. Baixe o arquivo, abra e só então execute:

curl -sfL https://get.k3s.io -o install-k3s.sh

less install-k3s.sh

sudo sh install-k3s.sh

O instalador cria um serviço que volta sozinho após reboot ou queda e instala as ferramentas kubectl, crictl, ctr, k3s-killall.sh e k3s-uninstall.sh. Sem opção, ele instala a versão do canal stable.

Opções vão em variáveis ou depois de sh -s -. Quem não vai usar o Traefik embutido pode desligá-lo já nessa instalação, usando o comando abaixo no lugar do anterior; a flag --disable também aceita servicelb, coredns, local-storage e metrics-server:

curl -sfL https://get.k3s.io | sh -s - --disable=traefik

Para não repetir opções a cada atualização, a documentação oferece o arquivo /etc/rancher/k3s/config.yaml, com as mesmas chaves das flags. O Traefik em si tem artigo próprio na base, "Traefik na VPS: como instalar o proxy reverso".

Passo 3: conferir o cluster e o kubeconfig

O kubeconfig, o arquivo com as credenciais do cluster, fica em /etc/rancher/k3s/k3s.yaml, e o kubectl instalado pelo K3s já o usa. Pela documentação, ele nasce com permissão 600 e dono root, por isso os comandos usam sudo:

sudo kubectl get nodes

sudo kubectl get pods -A

Esperamos ver o nó como Ready e os Pods do sistema, no namespace kube-system, como Running (conferência nossa, não da documentação). Esse arquivo dá acesso irrestrito a todo o cluster. A opção --write-kubeconfig-mode=644 deixa qualquer usuário da máquina lê-lo; nosso conselho é manter o 600.

Para usar o kubectl do seu computador, a documentação manda copiar o arquivo para ~/.kube/config e trocar o campo server pelo endereço do servidor. Como a 6443 não deve ficar aberta, faça esse acesso por uma rede privada, como em Tailscale na VPS: acesso privado ao servidor e painéis. O K3s renova os certificados desse arquivo a cada início, então cópias manuais precisam ser atualizadas.

Passo 4: o primeiro deploy

O teste abaixo usa comandos do tutorial oficial do Kubernetes (create, get e expose); a imagem nginx e o port-forward são montados por nós. Ele cria um Deployment, um Service interno e abre um túnel local até ele:

sudo kubectl create deployment web --image=nginx

sudo kubectl get deployments

sudo kubectl expose deployment web --port=80

sudo kubectl port-forward service/web 8080:80

Com ele rodando, teste de outro terminal na VPS com curl -I http://127.0.0.1:8080; esperamos ver o cabeçalho do nginx na resposta (expectativa nossa). Em produção, recomendamos fixar uma tag da imagem em vez de usar o padrão.

O mesmo app pode ser descrito num arquivo, que é o jeito de versionar. Salve como web.yaml e mantenha 2 espaços por nível ao copiar, porque o recuo faz parte do YAML e pode se perder na página:

apiVersion: apps/v1

kind: Deployment

metadata:

name: web

spec:

replicas: 2

selector:

matchLabels:

app: web

template:

metadata:

labels:

app: web

spec:

containers:

- name: nginx

image: nginx

ports:

- containerPort: 80

Para trocar o teste pelo arquivo, interrompa o port-forward com Ctrl+C, apague os recursos criados antes e aplique:

sudo kubectl delete service web

sudo kubectl delete deployment web

sudo kubectl apply -f web.yaml

Passo 5: somar outro nó

No servidor, o token de entrada fica em /var/lib/rancher/k3s/server/node-token. Na segunda máquina, o mesmo script vira instalação de agente quando recebe K3S_URL e K3S_TOKEN:

curl -sfL https://get.k3s.io | K3S_URL=https://ENDERECO-DO-SERVIDOR:6443 K3S_TOKEN=CONTEUDO-DO-NODE-TOKEN sh -

Pela documentação, cada máquina precisa de um nome de host único; se não for o caso, defina K3S_NODE_NAME. O token é um segredo: não o cole em chat nem em repositório. Antes de rodar o comando na segunda máquina, libere a 6443 só para o IP do agente, como no passo 1. Pela lista de portas, a 8472/UDP e a 10250/TCP também são entre os nós; no firewall, restrinja-as aos IPs deles.

Passo 6: backup, atualização e desinstalação

Com o banco padrão, o SQLite, a documentação diz que basta copiar a pasta /var/lib/rancher/k3s/server/db/ e guardar também o arquivo /var/lib/rancher/k3s/server/token: sem o mesmo token, o backup não serve na restauração. Recomendamos copiar com o serviço parado, numa janela combinada (exemplo nosso). O arquivo inclui o token, que é um segredo: guarde-o com cuidado:

sudo systemctl stop k3s

sudo tar czf k3s-backup.tar.gz /var/lib/rancher/k3s/server/db /var/lib/rancher/k3s/server/token

sudo systemctl start k3s

Guarde o arquivo fora da VPS, por exemplo com Duplicati na VPS: backup do servidor com painel web. Com etcd embutido, a documentação informa snapshots automáticos às 00:00 e às 12:00, com 5 guardados por servidor, e o comando sudo k3s etcd-snapshot save para um snapshot na hora.

Para atualizar, rode o script de novo com as mesmas opções da instalação; sem opção, ele vai para o canal stable, e INSTALL_K3S_VERSION fixa uma versão. A documentação manda atualizar primeiro os servidores, um por vez, depois os agentes, sem pular versões menores. Recomendamos um backup antes.

Para remover, o servidor usa /usr/local/bin/k3s-uninstall.sh e o agente /usr/local/bin/k3s-agent-uninstall.sh. A documentação avisa que a desinstalação pode causar perda de dados: ela apaga o banco local e os volumes do local-path.

Checklist do K3s na VPS

  • mínimos da página de requisitos conferidos com o servidor escolhido;
  • regras do UFW para 10.42.0.0/16 e 10.43.0.0/16, e 6443 só para IPs de nós;
  • script de instalação lido antes de rodar;
  • kubeconfig com permissão 600 e acesso remoto por rede privada;
  • deploy de teste conferido e apagado;
  • backup da pasta db e do token fora da VPS;
  • atualização com backup, servidores antes dos agentes.

Para endurecer o cluster, a documentação tem um guia CIS, com opções como secrets-encryption: true, que cifra os Secrets guardados no banco.

Nomes para os apps publicados

Recomendamos dar a cada app publicado um nome próprio, como app.suaempresa.com.br.

Um domínio registrado dá aos apps publicados um nome fácil de lembrar. Buscar domínio

Perguntas frequentes

K3s é Kubernetes de verdade?

Pela documentação, é uma distribuição totalmente compatível com o Kubernetes. E o kubectl já vem na instalação.

Preciso de mais de uma VPS?

Não. O guia rápido instala o K3s num servidor só; outros nós entram depois, com o token.

Posso desligar o Traefik?

Sim. Instale com --disable=traefik ou ponha a opção no arquivo de configuração. Pela documentação, o componente desligado é desinstalado.

Onde ficam os dados do cluster?

Com o banco padrão, em /var/lib/rancher/k3s/server/db/. O token em /var/lib/rancher/k3s/server/token precisa entrar no mesmo backup.

Esta resposta lhe foi útil?

Artigos Relacionados