Do Docker ao k3s — a decisão de usar Kubernetes de verdade

⚡ A keyword que eu não sabia usar

O meu currículo passou por uma auditoria ATS (Applicant Tracking System) — o software que filtra currículos antes de qualquer humano ver. O score chegou a 98.8/100. Faltavam duas keywords: Automation/Automação (seria keyword stuffing — cada idioma já tem a sua) e Kubernetes.

Kubernetes. A plataforma que orquestra containers em produção. Recrutador técnico vê essa palavra e presta atenção. E eu não usava. Aparecer no CV sem usar seria mentira — e mentira técnica é o tipo de coisa que um entrevistador bom descobre na primeira pergunta.

A alternativa era pior: deixar de fora e perder o match. Então a decisão foi a única honesta: adotar Kubernetes de verdade.

🧠 A pergunta certa: onde faz sentido?

Kubernetes não é bala de prata. Pra site estático (Portifólio, LifeLog), é overkill gigante. Pra Jellyfin/TDarr (GPU passthrough, volumes, rede host), é um pesadelo. Mas o Arachne tem arquitetura real de microserviços:

Dez serviços, filas, GPU, banco vetorial. Isso é exatamente o tipo de workload que Kubernetes foi feito pra orquestrar: isolamento de workers (crash não derruba a fila), rolling updates sem downtime, self-healing (container morreu → sobe de novo), secrets nativos.

🔧 A escolha: k3s single-node

Opções avaliadas:

O k3s (Rancher) é a distribuição Kubernetes leve para edge — um binário, menos de 100MB de footprint, e compatível com K8s padrão. Roda em WSL2 sem drama. É Kubernetes de verdade: mesmo API server, mesmo kubectl, mesmo manifesto.

Riscos aceitos (e o critério de parada):

• RAM é o recurso crítico: host tem 11GB total, ~3.7GB available. Overhead do k3s ~500MB-1GB. Se apertar, PARAR e reportar — nunca sacrificar produção.
• GPU no WSL2 + K8s: nvidia-container-toolkit + device plugin (config chata, mas documentada).
• Manutenção nova: k3s updates, certificados.

📋 O plano em fases (com rollback a qualquer momento)

A regra era simples: nunca quebrar o que está funcionando. O Docker Compose atual fica intacto até a última fase.

F0  Plano detalhado (docs oficiais k3s primeiro)
F1  Instalar k3s + medir overhead RAM real
F2  Portar stateless (api, worker, nginx, crawl4ai, redis)
    → rodando em PARALELO com o compose (portas diferentes)
F3  Portar stateful (postgres, umami-db) com volumes migrados
F4  GPU pro worker VLM + validar fila arachne-vlm-jobs
F5  Cutover DNS/tunnel + desligar compose + monitorar 72h

Cada fase tem teste com evidência: health check, fila RQ processando, RAG respondendo, VLM processando imagem, umami coletando. Nada de “funciona” sem prova.

Rollback: se qualquer fase falhar, volta pro compose em minutos — ele nunca foi desligado.

🎯 Aprendizados (até aqui)

1. Não mentir no CV é decisão de arquitetura — a keyword virou um driver real de infraestrutura. Honestidade virou roadmap.
2. Avaliar projeto por projeto — K8s só faz sentido onde a arquitetura pede. Forçar em tudo é moda, não engenharia.
3. RAM como critério de parada — em ambiente pessoal com 11GB, overhead importa. Ter um limite explícito evita sacrificar produção por ego.
4. Rollback é o que dá coragem — saber que o compose está intacto até F5 permite executar com confiança.

╔══════════════════════════════════════╗
║  Samuel Medeiros                    ║
║  Senior Software Engineer           ║
║  Stack: Python · TypeScript · Rust  ║
║  Projetos: Arachne, Dogwalk,        ║
║            Capivara, TatuEngine      ║
╚══════════════════════════════════════╝
      

🚀 O que vem a seguir

A migração roda em fases com aprovação em cada uma. Quando o k3s estabilizar em produção por 1-2 meses, “Kubernetes (k3s)” entra no CV de verdade. E o cluster multi-node (a opção B) fica anotado como experimento futuro — primeiro o single-node precisa provar o valor.