Se você só vai rodar um blog, um banco de dados e alguns contêineres, o guia de configuração de produção de VPS com Docker Compose costuma ser mais direto. Escolha o K3s quando precisar de Helm, Ingress, Operators, atualizações graduais ou quiser aprender a API do Kubernetes.

O K3s recomenda oficialmente no mínimo 1 núcleo de CPU e 512 MB de memória, sugere pelo menos 2 núcleos e 1 GB de memória e indica o uso de SSD. Porém, esse número só basta para o próprio cluster e cargas de trabalho muito leves; para uma compra real, comece pelo seguinte:

Se estiver em dúvida sobre a configuração, leia primeiro Como escolher a configuração de uma VPS. Este artigo usa como exemplo Ubuntu 24.04 e uma VPS KVM com IPv4 pública. Antes de instalar, confirme:

• O registro A do domínio já aponta para a VPS;
• TCP 80 e 443 estão abertos para a internet;
• Um nó único não precisa expor a 6443 para a internet; para administração remota, prefira uma VPN ou restrinja os IPs de origem;
• Com vários nós, permita que os nós acessem TCP 6443, UDP 8472 e TCP 10250 apenas pela rede privada;
• A UDP 8472 é a porta VXLAN do Flannel e nunca deve ser aberta para toda a internet.

Primeiro atualize o sistema e verifique se as portas 80/443 estão ocupadas:

sudo apt update
sudo apt upgrade -y
sudo ss -lntup | grep -E ':(80|443|6443)\b' || true

Se Nginx, Caddy ou contêineres Docker já ocupam as portas 80/443, o Traefik padrão não conseguirá vinculá-las. Primeiro use o guia de diagnóstico de portas ocupadas em VPS para identificar o processo; não encerre serviços desconhecidos diretamente.

Use o script de instalação oficial:

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

O instalador cria e habilita o serviço k3s e também instala kubectl, crictl, ctr, um script de parada e um script de desinstalação. Verifique o status:

sudo systemctl status k3s --no-pager
sudo k3s kubectl get nodes -o wide
sudo k3s kubectl get pods -A

O nó deve estar em Ready, e os Pods de kube-system, como CoreDNS, Traefik, metrics-server e local-path-provisioner, devem ir entrando em Running ou Completed.

O kubeconfig de administrador fica em /etc/rancher/k3s/k3s.yaml, com permissões padrão 600. A forma mais segura é continuar usando:

sudo k3s kubectl get nodes

Se precisar executar kubectl com sua conta pessoal, você pode copiar o kubeconfig e restringir as permissões:

mkdir -p "$HOME/.kube"
sudo cp /etc/rancher/k3s/k3s.yaml "$HOME/.kube/config"
sudo chown "$(id -u):$(id -g)" "$HOME/.kube/config"
chmod 600 "$HOME/.kube/config"
kubectl get nodes

Não envie o kubeconfig para ferramentas de chat nem o envie ao Git; ele contém credenciais de administrador do cluster.

Crie whoami.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: whoami
spec:
  replicas: 2
  selector:
    matchLabels:
      app: whoami
  template:
    metadata:
      labels:
        app: whoami
    spec:
      containers:
        - name: whoami
          image: traefik/whoami:latest
          ports:
            - containerPort: 80
          resources:
            requests:
              cpu: 20m
              memory: 32Mi
            limits:
              cpu: 200m
              memory: 128Mi
---
apiVersion: v1
kind: Service
metadata:
  name: whoami
spec:
  selector:
    app: whoami
  ports:
    - port: 80
      targetPort: 80

Aplique e verifique:

kubectl apply -f whoami.yaml
kubectl rollout status deployment/whoami
kubectl get pods,svc

Em produção, não use a longo prazo uma imagem latest flutuante; fixe uma versão ou um digest verificados.

O K3s implanta o Traefik por padrão, e o ServiceLB usa as portas 80/443 do host. Primeiro crie um Ingress HTTP:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: whoami
spec:
  ingressClassName: traefik
  rules:
    - host: app.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: whoami
                port:
                  number: 80

kubectl apply -f ingress.yaml
kubectl get ingress
curl -I http://app.example.com

O Traefik cuida da entrada HTTPS, mas o certificado ainda precisa ser fornecido por você. Se já tiver um certificado, crie um Secret TLS:

kubectl create secret tls app-example-tls \
  --cert=fullchain.pem \
  --key=privkey.pem

Depois adicione-o ao spec do Ingress:

tls:
  - hosts:
      - app.example.com
    secretName: app-example-tls

Se precisar de emissão e renovação automáticas, instale o cert-manager e depois crie um Issuer/ClusterIssuer ACME. Não modifique manualmente o /var/lib/rancher/k3s/server/manifests/traefik.yaml; o K3s restaura o conteúdo padrão na inicialização. Para personalizar o Traefik, use um HelmChartConfig adicional.

Se você tem mais familiaridade com um proxy reverso independente, também pode desativar o Traefik durante a instalação e consultar o guia de HTTPS automático com Caddy, mas é obrigatório definir explicitamente --disable=traefik na configuração da primeira instalação para evitar conflitos de porta.

O K3s inclui o Local Path Provisioner, então você pode criar PVCs diretamente:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: app-data
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: local-path
  resources:
    requests:
      storage: 5Gi

kubectl apply -f pvc.yaml
kubectl get pvc,pv

O local-path usa o disco local do nó onde o Pod é executado. Depois que o Pod é recriado, os dados normalmente continuam lá, mas, se o nó for danificado permanentemente, os dados não aparecerão automaticamente em outro nó. Portanto:

• Um nó único pode ser usado para aplicações leves, mas backups em outra máquina são obrigatórios;
• Em bancos de dados com vários nós, não trate o local-path como armazenamento compartilhado ou replicado;
• Quando precisar de persistência entre nós, avalie Longhorn, CSI de disco em nuvem ou um banco de dados gerenciado externamente;
• Antes de expandir, confirme o modo de acesso, a topologia e o processo de recuperação do PVC.

Por padrão, um único nó Server usa SQLite. Os requisitos oficiais são fazer backup de:

• /var/lib/rancher/k3s/server/db/;
• /var/lib/rancher/k3s/server/token;
• Cópias seguras dos manifestos de aplicações, dos values do Helm e dos Secrets;
• Dados de negócio, como local-path, bancos de dados e arquivos enviados pelos usuários.

Para obter uma cópia consistente, você pode parar o K3s durante uma janela de manutenção e depois copiar o banco de dados e o token:

sudo systemctl stop k3s
sudo tar -C /var/lib/rancher/k3s/server \
  -czf /root/k3s-control-plane-$(date +%F).tar.gz db token
sudo systemctl start k3s
sudo k3s kubectl get nodes

Um backup do plano de controle não é o mesmo que um backup dos dados de negócio; o conteúdo dos PVCs deve ser copiado separadamente para outra máquina ou para armazenamento de objetos. Para uma estratégia completa, consulte o guia de simulação de backup e recuperação em VPS.

Só quando usar etcd embarcado você deve seguir o processo k3s etcd-snapshot; no SQLite padrão de nó único, não copie os comandos de snapshot do etcd. Independentemente do datastore, a recuperação exige o token original do servidor; caso contrário, os dados criptografados podem ficar inutilizáveis.

No Server, leia o token de entrada:

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

Execute na nova VPS:

curl -sfL https://get.k3s.io | \
  K3S_URL=https://SERVER_PRIVATE_IP:6443 \
  K3S_TOKEN='替换为真实Token' sh -

Cada máquina deve usar um hostname exclusivo. Depois, verifique no Server:

sudo k3s kubectl get nodes -o wide

Adicionar um Agent apenas aumenta a capacidade de computação; não torna o plano de controle altamente disponível. A HA real exige vários nós Server com etcd embarcado ou um banco de dados externo, além de redesenhar o ponto de entrada de carga e a persistência.

Faça backup antes de atualizar e registre os parâmetros originais da instalação. Oficialmente, é possível atualizar executando novamente o script de instalação com a mesma configuração; se você esquecer as variáveis de ambiente ou os parâmetros originais, poderá perder a configuração. Negócios estáveis também devem seguir a política de diferença de versões do Kubernetes e não pular versões menores intermediárias.

Comandos comuns de diagnóstico:

kubectl get nodes
kubectl get pods -A -o wide
kubectl describe pod POD_NAME
kubectl logs POD_NAME --previous
sudo journalctl -u k3s -n 200 --no-pager
kubectl top nodes
kubectl top pods -A

• Pending: verifique solicitações de CPU/memória, PVCs, taints e eventos de agendamento;
• CrashLoopBackOff: verifique os logs atuais, os logs de --previous, as variáveis de ambiente e as verificações de integridade;
• Falha de acesso ao Ingress: verifique DNS, 80/443, grupos de segurança, Pods do Traefik e o backend do Ingress;
• Nó NotReady: verifique os logs de k3s/k3s-agent, a conectividade com a 6443, a sincronização de horário e o firewall do Flannel;
• Métricas vazias: confirme que o metrics-server está saudável e permita TCP 10250 entre os nós.

Para operação de longo prazo, você pode combinar com a solução de monitoramento Prometheus + Grafana para observar nós, Pods, discos e datas de expiração dos certificados.

O comando de desinstalação de um nó Server é:

sudo /usr/local/bin/k3s-uninstall.sh

Ele para o K3s e exclui o datastore local do cluster, os dados dos PVs do Local Storage, a configuração do nó e os scripts relacionados. Antes de executá-lo, você deve confirmar que tanto o plano de controle quanto os dados de negócio foram verificados como recuperáveis em outra máquina; não é um comando comum de "parar o serviço".