Este projeto representa uma transformação fundamental na forma como a Messagefy opera sua infraestrutura. O objetivo é implantar, de forma controlada e completamente rastreável, uma nova fundação tecnológica que elimina a fragilidade operacional e estabelece padrões de engenharia rigorosos para toda a plataforma.
O conceito central é simples mas poderoso: tudo o que existe no ambiente precisa ser reproduzível a partir de código versionado, e qualquer mudança deve acontecer através de um fluxo auditável. Isso significa abandonar definitivamente o modelo "configuração manual em servidor" e adotar um modelo onde o ambiente pode ser reconstruído, escalado e recuperado por automação.
O Desafio Atual e a Visão de Futuro
Cenário Atual
- Componentes distribuídos sem padrão consistente
- Gaps de segurança e pontos de fragilidade operacional
- Configurações "snowflake" dependentes de conhecimento manual
- Dificuldade para escalar e recuperar de falhas
- Ausência de rastreabilidade completa de mudanças
Ambiente Alvo
- Infraestrutura reproduzível a partir de código versionado
- Padrões de segurança aplicados por design
- Automação completa de provisionamento e configuração
- Rastreabilidade end-to-end de todas as mudanças
- Capacidade de recuperação rápida e previsível
A arquitetura final é baseada em infraestrutura bare-metal virtualizada com Proxmox, orquestrada com Kubernetes e governada por três pilares fundamentais: Infrastructure as Code, GitOps e CI/CD com DevSecOps.
Arquitetura Alvo: Visão de Camadas
Ao final da implementação, a plataforma será estruturada em camadas bem definidas, cada uma com responsabilidades claras e interfaces padronizadas. Esta arquitetura foi projetada para suportar crescimento sustentável e operação previsível.
Borda e Gateway
Cloudflare para proteção, DNS e otimizações, combinado com Ingress Controller para entrada HTTP/HTTPS e API Gateway (APISIX) para controle de autenticação, rate limiting e gestão de consumers.
Serviços Centrais
RabbitMQ para mensageria, Dragonfly para cache distribuído, PostgreSQL Core com CloudNativePG, ETCD para configuração do gateway, e stack completa de observabilidade com métricas, logs e dashboards.
Camada de Aplicação
Messagefy API/Webhook para recepção de requisições, Workers/Dispatcher para processamento assíncrono, e Storagefy para gestão de objetos e mídias com deduplicação inteligente.
Provedores WhatsApp
Frota de instâncias Whatsmeow com estratégia de escala horizontal, integração otimizada com RabbitMQ e persistência de sessão projetada para minimizar tempo de spawning e pressão no banco.
Storage e Backup
Cloudflare R2 como backend para mídias/objetos (Storagefy) e destino de backup via Velero, eliminando custos de egress e complexidade operacional de soluções auto-gerenciadas.
Execução por Fases: Da Fundação ao Ambiente Completo
A implementação acontece por fases deliberadas, porque a construção depende de camadas. Cada fase estabelece uma fundação sólida para a próxima, com entregáveis verificáveis e critérios de aceite claros.
O projeto começa pela fundação física e de virtualização, preparando e padronizando o ambiente bare-metal para ser consumível por automação via APIs e templates. Uma vez estabelecida essa base, o pipeline de provisionamento Terraform cria VMs de forma repetível, com endereçamento previsível e inventário automatizado.
Com as VMs provisionadas, o Ansible transforma essas máquinas em nós Kubernetes, aplicando hardening, ajustes de kernel, instalação do runtime e bootstrap completo do cluster. Ao final desta fase, o cluster está operacional e pronto para receber componentes.
A partir desse ponto, o projeto migra para o modelo GitOps: o ArgoCD passa a gerenciar o estado do cluster, substituindo comandos manuais por sincronização automática a partir do Git. Então são implantados os componentes fundamentais (ingress, storage, observabilidade, backup) e a camada de segurança (RBAC, Network Policies, gestão de segredos).
Finalmente, com toda a fundação pronta, são estabelecidas as pipelines de CI/CD padronizadas e, somente então, as aplicações são implantadas sobre essa plataforma robusta e auditável.
Visão Geral Detalhada: Propósito e Escopo
Projeto Messagefy (Chat Guru) - Plano de Implementação
Este documento funciona como o guia operacional completo da implementação. Ele responde, sem ambiguidades, o que será implementado, em qual ordem, com quais ferramentas, como cada etapa funciona, e quais pipelines e artefatos serão criados.
Objetivos e Entregas do Projeto
Base de infraestrutura preparada
Ambiente para o Messagefy operar com previsibilidade, controle e escala. Cluster Kubernetes em infraestrutura bare-metal/Proxmox, provisionado via IaC com Terraform e Ansible.
Padronização de deploy via GitOps
ArgoCD como controlador central com repositório de manifestos e organização clara de ambientes (dev, staging, prod). O Git se torna a fonte única de verdade.
Pipelines de CI/CD completas
GitLab CI padronizado para IaC, bootstrap, build de imagens com scan de segurança via Harbor, e promoção de releases via GitOps. Controles DevSecOps integrados (secret detection, SCA, SAST, IaC scanning).
Camada de storage e backup
Longhorn para StorageClasses com perfis de performance, Velero para backup de volumes e metadados, e Cloudflare R2 como backend de object storage e destino de backup.
Segurança do cluster (baseline)
RBAC por ServiceAccount com mínimo privilégio, Network Policies deny-by-default, gestão de segredos com Vault, certificados via cert-manager, audit log e hardening de SO via Ansible.
Runbooks operacionais
Documentação completa de procedimentos e critérios de aceite por fase, permitindo operação consistente e transferência de conhecimento.
Premissas e Decisões Arquiteturais
Premissas Fundamentais
O ambiente alvo assume Bare Metal First como estratégia principal, priorizando custo previsível, performance superior e eliminação de custos de egress — fatores críticos para uma plataforma de alto volume como o Messagefy.
Glossário Técnico: Componentes da Stack
IaC e GitOps
IaC: Infraestrutura descrita como código versionado. GitOps: Git como fonte de verdade, cluster aplica mudanças lendo repositório.
Terraform e Ansible
Terraform: cria/gerencia recursos de forma declarativa. Ansible: configura e prepara máquinas (SO, runtime, Kubernetes).
ArgoCD e Harbor
ArgoCD: controla aplicações no K8s via Git (modelo pull). Harbor: registry corporativo com scan de vulnerabilidades.
Longhorn e Velero
Longhorn: storage distribuído para Kubernetes bare metal. Velero: backup/restore de metadados e volumes.
Cilium
CNI (Container Network Interface) e implementação de Network Policies usando eBPF para alta performance e segurança avançada.
Organização dos Repositórios: Estrutura de Código
A base de código será organizada em repositórios especializados, cada um com responsabilidades bem definidas e pipelines específicas. Esta separação facilita governança, controle de acesso e evolução independente.
infra-iac
Infraestrutura e Bootstrap
- Módulos Terraform (Proxmox, rede, VMs)
- Inventário dinâmico via outputs
- Playbooks/roles Ansible (hardening, runtime, K8s bootstrap, CNI)
- Pipelines: terraform fmt/validate/plan/apply, ansible-lint, Checkov (IaC scanning)
gitops-manifests
Estado Desejado do Cluster
- Pastas por ambiente: dev/, staging/, prod/
- Manifests Helm/Kustomize por stack (infra, observability, security, apps)
- "App of Apps" do ArgoCD: aplicação raiz que referencia todas as outras
service-*
Código dos Microsserviços
- Dockerfile e configurações da aplicação
- .gitlab-ci.yml padronizado
- Testes automatizados
- Pipeline: build, scan, push, promoção via GitOps
Plano de Implementação por Fases
Cada fase termina com entregáveis verificáveis e um checklist de aceite rigoroso. A fase seguinte depende do aceite da anterior, garantindo fundação sólida em cada etapa.
"A implementação não é um grande salto — é uma sequência de passos validados, onde cada etapa estabelece a fundação para a próxima."
Fase 0: Preparação e Alinhamento
Kickoff Técnico-Operacional
Entradas Necessárias
- Acesso aos ambientes atuais (read-only quando possível)
- Definição do provedor bare metal e especificações
- Convenções de naming (clusters, domínios, namespaces)
- Padrões de labels e annotations
Saídas Esperadas
- Matriz RACI (responsabilidades definidas)
- Plano de naming e padrões documentado
- Checklist de pré-requisitos completo
Fase 1: Fundação Física e Virtualização
Bare Metal + Proxmox VE
Transformar "servidor contratado" em "plataforma consumível por IaC" — esta é a fundação de tudo que vem depois.
Provisionamento Bare Metal
Contratação e configuração inicial dos servidores físicos com especificações validadas na Fase 0.
Instalação Proxmox VE 8.x
Setup da camada de virtualização com configuração de bridges, VLANs e roteamento básico.
Automação e Templates
Criação de usuários/tokens de API para automação e templates de VM (Debian 12 + cloud-init).
Entregáveis e Aceite
Entregáveis:
- Proxmox VE operacional
- Template Debian 12 com cloud-init
- Token de API configurado
Critérios de Aceite:
- API Proxmox acessível pelo pipeline
- Criação de VM via API testada e validada
Fase 2: Provisionamento Automatizado (Terraform)
Criar VMs e rede "apertando um botão", sem ações manuais repetitivas. O Terraform garante idempotência e reprodutibilidade completa do ambiente.
Estrutura e Conceitos
Módulos Terraform
- proxmox-vm/ (criação de VMs)
- proxmox-network/ (bridges e rede)
- Perfis: control-plane, worker, storage
Cloud-init Integration
- Usuário padrão pré-configurado
- Chaves SSH injetadas
- IP fixo e gateway
Backend e Estado
- tfstate em backend remoto (GitLab/S3/R2)
- Lock de estado habilitado
- Outputs gerando inventário automático
Pipeline GitLab CI
Pipeline em quatro estágios: fmt (formatação), validate (validação sintática), plan (preview de mudanças) e apply (execução aprovada). O estágio apply requer aprovação manual em branch protegida.
Fase 3: Bootstrap do Kubernetes (Ansible)
Transformar "VM recém-criada" em "nó Kubernetes pronto" através de automação completa. O Ansible aplica configurações, hardening e inicializa o cluster de forma repetível.
Hardening e Baseline
Desabilitar swap, ajustar sysctl (rede, conntrack, fs.inotify), configurar limites de arquivos, NTP, módulos de kernel e baseline SSH.
Instalação do Runtime
Containerd 2.0+ com configuração padrão compatível com Kubernetes, garantindo consistência em todos os nós.
Bootstrap do Cluster
Inicialização do primeiro control plane, join dos outros control planes via kubeadm e join dos workers no cluster.
CNI (Cilium)
Instalação via Helm/CLI e validação completa de conectividade através do cilium connectivity test.
Fase 4: GitOps com ArgoCD
Parar de operar via SSH, começar a operar via Git
A partir deste ponto, o modelo operacional muda fundamentalmente. O ArgoCD se torna o controlador central, e mudanças no Git se traduzem automaticamente em mudanças no cluster.
Modelo "App of Apps"
Uma aplicação raiz no ArgoCD aponta para o repositório gitops-manifests. Essa aplicação raiz referencia todas as outras aplicações (infra, observability, security, apps), criando uma árvore de dependências gerenciada automaticamente.
Infra
Ingress, cert-manager, external-secrets, Longhorn
Observability
Prometheus, Grafana, Loki para métricas e logs
Security
RBAC, NetworkPolicies, audit policy
Apps
Messagefy, workers, Storagefy, Whatsmeow
Drift Correction: O ArgoCD detecta e corrige automaticamente divergências entre o estado desejado (Git) e o estado real (cluster), garantindo consistência operacional contínua.
Fase 5: Infraestrutura Base via GitOps
Instalação dos componentes padrão do cluster antes das aplicações: ingress, storage, observabilidade e certificados. Todos gerenciados via GitOps para garantir reprodutibilidade.
Storage: Perfis e Estratégia
longhorn-performance
3 réplicas, discos NVMe, dataLocality ajustado. Para PostgreSQL, RabbitMQ e workloads sensíveis a latência.
longhorn-standard
2 réplicas, workloads menos sensíveis. Balanço entre resiliência e uso de recursos.
local-path-nvme
Para casos extremos de latência (cache, buffers temporários). Sem replicação, máxima performance.
Backup: Velero + Cloudflare R2/S3
- Velero instalado via GitOps
- Destino S3-compatible: Cloudflare R2
- Backup diário (retenção 30 dias)
- Backup semanal (retenção 90 dias)
- POC de restore para medir RTO real
Fase 6: Segurança (Baseline de Produção)
Colocar baseline de segurança antes de expor produção — não como um ajuste posterior. Segurança é estrutural, não opcional.
RBAC por ServiceAccount
Cada aplicação tem ServiceAccount própria com Role mínima no namespace e RoleBinding específico. Princípio de mínimo privilégio aplicado rigorosamente.
Network Policies Deny-by-Default
Política global por namespace com default deny para ingress/egress. Liberações explícitas por serviço: API → RabbitMQ, Worker → RabbitMQ, Storagefy → R2, Apps → Postgres.
Gestão de Segredos
Regra absoluta: sem segredos no Git. Vault + External Secrets Operator (com POC Infisical). Certificados públicos via cert-manager + Let's Encrypt.
Auditoria e Hardening
Kubernetes audit policy para rastrear quem fez, quando, qual recurso, de onde. Ansible role de hardening com baseline controlado aplicado em todos os nós.
Fase 7: CI/CD Completo e DevSecOps
A "Fábrica" de Software Segura e Auditável
Criar pipelines padronizadas onde toda build, teste, criação de imagem e promoção de release aconteça de forma controlada, com rastreabilidade completa do commit até produção.
Padrão de Pipeline por Serviço
Lint / Unit Test
Validação de código e testes unitários
Build Image
Construção de imagem Docker
Scan Image
Trivy/Harbor para vulnerabilidades
Push Image
Harbor registry corporativo
Update GitOps
Promoção via manifests
DevSecOps Integrado
Secret Detection
gitleaks/trufflehog para detectar segredos expostos no código
SCA
Análise de dependências vulneráveis
SAST/DAST
Análise estática e dinâmica quando aplicável
IaC Scanning
Checkov para Terraform/K8s manifests
Fase 8: Deploy das Aplicações
Colocar a Plataforma Rodando sobre a Nova Fundação
Somente após toda a fundação estar pronta e validada, as aplicações são implantadas. Esta é a última fase porque depende de todas as camadas anteriores.
Ordem de Implantação Recomendada
PostgreSQL Core (CNPG)
Banco de dados central com alta disponibilidade
RabbitMQ
Message broker para comunicação assíncrona
Dragonfly
Cache distribuído de alta performance
Storagefy
Gestão de objetos com integração R2
Messagefy API
Camada de API e recepção de webhooks
Workers/Dispatcher
Processamento assíncrono de mensagens
Whatsmeow
Frota de instâncias WhatsApp
Storagefy + Cloudflare R2: Detalhes de Integração
Configuração S3-Compatible
- Endpoint: Cloudflare R2
- Bucket configurado com políticas apropriadas
- Credenciais via Vault/ExternalSecrets
- Deduplicação por hash mantida (lógica existente)
Decisões do Cliente
Pendente: Política de retention/lifecycle e versionamento de objetos. Workshop com time de negócio para definir regras de retenção alinhadas com compliance.
Whatsmeow: Persistência de Sessão
PostgreSQL Centralizado
Schema-per-device, consistência forte, queries complexas possíveis
Entrega Final: O Que Estará Pronto
Plataforma Operacional Completa
Ao final do projeto, o cliente terá muito mais do que "Kubernetes rodando" — terá uma plataforma operacional completa onde infraestrutura, segurança e entrega contínua trabalham juntos.
Reproduzível
Cluster pode ser reconstruído por código versionado
Auditável
Aplicações entregues via GitOps com rastreabilidade completa
Seguro
Segurança aplicada por padrão, não como ajuste posterior
Checklist de Go-Live
- ✅ IaC versionada e executável end-to-end
- ✅ Cluster Kubernetes operacional
- ✅ ArgoCD com app-of-apps
- ✅ Harbor com scan de vulnerabilidades
- ✅ Pipelines CI/CD padronizadas
- ✅ Longhorn + StorageClasses configuradas
- ✅ Velero + restore testado
- ✅ RBAC + NetworkPolicy deny-by-default
- ✅ Vault/segredos fora do Git
- ✅ Observabilidade mínima funcional
- ✅ Runbooks operacionais documentados
"Este projeto não é apenas sobre tecnologia — é sobre criar previsibilidade, reduzir risco e estabelecer fundação para crescimento sustentável do negócio."
Plataforma de Infraestrutura Messagefy: Uma Nova Fundação Operacional