From a58c85d855f5dc5b136d985b76675d8ee0579b9e Mon Sep 17 00:00:00 2001 From: esther Date: Tue, 4 Aug 2026 21:41:08 -0300 Subject: [PATCH 1/3] docs: arquitetura C2, requisitos, trade-offs, ADRs e melhorias --- docs/architecture.md | 88 ++++++++++++++++++++++++++ docs/docs/adr/000-template.md | 18 ++++++ docs/docs/adr/001-kubernetes-deploy.md | 25 ++++++++ docs/docs/adr/002-dbaas-postgresql.md | 31 +++++++++ 4 files changed, 162 insertions(+) create mode 100644 docs/architecture.md create mode 100644 docs/docs/adr/000-template.md create mode 100644 docs/docs/adr/001-kubernetes-deploy.md create mode 100644 docs/docs/adr/002-dbaas-postgresql.md diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..ad2e670 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,88 @@ +# Arquitetura da Solução + +## Visão geral + +API de pedidos containerizada, rodando em um cluster K3s (nó único) numa VM +na Magalu Cloud, com banco PostgreSQL gerenciado externo, imagens no Container +Registry e deploy automatizado pelo GitHub Actions. + +## Diagrama C2 · Container + +# Arquitetura da Solução + +## Visão Geral + +API de pedidos containerizada, rodando em um cluster K3s (nó único) numa VM na Magalu Cloud, com banco PostgreSQL gerenciado externo, imagens no Container Registry e deploy automatizado pelo GitHub Actions. + +## Diagrama C2 · Container + +```mermaid +flowchart LR + cliente["Cliente HTTP"] + gh["GitHub Actions"] + + subgraph mgc["Magalu Cloud"] + subgraph vm["VM BV2-2-40 · K3s"] + svc["Klipper ServiceLB :80"] + app["cloud-application · 2 pods (FastAPI)"] + end + db[("DBaaS PostgreSQL · orders, items")] + reg["Container Registry"] + end + + cliente -->|HTTP / JSON · TCP 80| svc + svc -->|HTTP / JSON · TCP 8000| app + app -->|SQL · TCP 5432| db + gh -->|Docker Push · HTTPS 443| reg + gh -->|kubectl apply · HTTPS 6443| app + reg -->|Pull Image · HTTPS 443| app +``` + +## Componentes + +| Componente | Serviço MGC | Função | +|------------|-------------|--------| +| API | K3s (VM single node) — 2 réplicas | Processa as requisições HTTP | +| Banco de dados | DBaaS PostgreSQL | Persiste pedidos e itens | +| Imagens | Container Registry | Armazena versões da aplicação | +| Tráfego externo | Klipper ServiceLB (IP da VM, porta 80) | Distribui entre as réplicas e dá acesso externo | +| CI/CD | GitHub Actions | Automatiza testes, build e deploy | + +## Requisitos não-funcionais + +| Requisito | Como medir | Alvo | +|---|---|---| +| Disponibilidade | Erros 5xx e uptime das probes no Grafana | 99,5% mensal | +| Latência | `histogram_quantile(0.95, ...)` do `/metrics` | P95 < 500 ms | +| Escalabilidade | Teste de carga (k6) + `rate(http_requests_total)` | 300 req/s sem degradar | +| Custo | VM + DBaaS + IP na calculadora MGC | Teto definido em ADR | + +## Estilo arquitetural + +A solução é um **monolito em camadas** (apresentação → serviço → dados), +implantado como container único com duas réplicas. O estilo-alvo, caso o +domínio de notificações cresça, seria extrair um segundo serviço — um próximo +passo, não uma decisão desta entrega. + +## Trade-offs das decisões + +| Aspecto | Decisão tomada | Alternativa não escolhida | Motivo da escolha | +|---------|---------------|--------------------------|-------------------| +| Deploy | K3s em VM | MKS (Kubernetes Gerenciado) | Custo menor, provisionamento < 2 min, manifests idênticos | +| Banco | DBaaS gerenciado | PostgreSQL em container | Backup automático, sem administração | +| CI/CD | GitHub Actions | Deploy manual | Consistência e rastreabilidade | +| Réplicas | 2 pods | 1 pod | Disponibilidade mínima sem custo excessivo | +| API | FastAPI (Python) | Node.js, Go, Java | Curva de aprendizado baixa, alta produtividade | + +## Pontos de melhoria e próximos passos + +| Melhoria | Por quê | +|----------|---------| +| HTTPS / TLS | Toda API em produção deve ser acessada por HTTPS | +| Autoscaler (HPA) | Escala o número de réplicas automaticamente conforme a carga de CPU | +| Versionamento de API (`/v1/orders`) | Evoluir sem quebrar clientes existentes | +| Rate limiting | Evita abuso e protege o banco de sobrecargas | +| Migrações de schema (Alembic) | Controle de versão das mudanças no banco | +| Testes de carga (k6) | Valida o comportamento sob alto tráfego | +| Migrar para MKS | Quando precisar de HA real: como os manifests são idênticos, basta trocar o kubeconfig | + diff --git a/docs/docs/adr/000-template.md b/docs/docs/adr/000-template.md new file mode 100644 index 0000000..9ad2e8e --- /dev/null +++ b/docs/docs/adr/000-template.md @@ -0,0 +1,18 @@ +# ADR NNN — Título curto da decisão + +**Status:** Aceito | Proposto | Rejeitado | Substituído por NNN +**Data:** AAAA-MM-DD + +## Contexto +Qual problema ou necessidade gerou a decisão, e quais restrições existiam. + +## Alternativas consideradas +- **Opção A** — prós e contras +- **Opção B** — prós e contras + +## Decisão +O que foi escolhido e por qual critério. + +## Consequências +**Positivas:** o que melhora. +**Negativas:** o que piora ou passa a ser risco. diff --git a/docs/docs/adr/001-kubernetes-deploy.md b/docs/docs/adr/001-kubernetes-deploy.md new file mode 100644 index 0000000..66e0ec4 --- /dev/null +++ b/docs/docs/adr/001-kubernetes-deploy.md @@ -0,0 +1,25 @@ +# ADR 001 — Uso de K3s em VM na Magalu Cloud para Deploy + +**Status:** Aceito +**Data:** 2026-08-04 + +## Contexto +A aplicação precisa ser executada em ambiente containerizado com orquestração de containers, capacidade de autorrecuperação (self-healing) e facilidade para atualização sem parada (rolling update). O orçamento é limitado para a fase atual do projeto. + +## Alternativas Consideradas +- **K3s em VM BV2-2-40 (Ubuntu 24.04)** — Distribuição Kubernetes leve, de rápido provisionamento e baixo custo operacional. Requer gestão manual do nó da VM. +- **MKS (Magalu Kubernetes Service)** — Cluster Kubernetes totalmente gerenciado. Possui alta disponibilidade no control plane, porém com custo mais elevado e tempo de provisionamento maior para o escopo atual. +- **VM com Docker Compose** — Solução simples de containerização, mas carece de recursos nativos de orquestração como autorrecuperação de pods, ServiceLB e escalabilidade simplificada via manifests standard de K8s. + +## Decisão +Utilizar o **K3s em uma VM única (BV2-2-40)** na Magalu Cloud. O critério decisivo foi o equilíbrio entre o custo reduzido e a compatibilidade total com os manifests padrão do Kubernetes (Deployments, Services, Secrets), garantindo um caminho direto de migração para o MKS no futuro caso a aplicação necessite de HA no cluster. + +## Consequências +**Positivas:** +- Baixo custo mensal de infraestrutura. +- Provisionamento do ambiente em menos de 2 minutos. +- Uso de manifests universais de Kubernetes. + +**Negativas:** +- Ponto único de falha (SPOF) no nível do nó/VM. +- A manutenção do nó (S.O., runtime K3s) é de responsabilidade interna. \ No newline at end of file diff --git a/docs/docs/adr/002-dbaas-postgresql.md b/docs/docs/adr/002-dbaas-postgresql.md new file mode 100644 index 0000000..0d58213 --- /dev/null +++ b/docs/docs/adr/002-dbaas-postgresql.md @@ -0,0 +1,31 @@ +# ADR 002 — Usar DBaaS PostgreSQL da Magalu Cloud + +**Status:** Aceito +**Data:** 2026-08-04 + +## Contexto +A aplicação precisa de um banco relacional durável, que sobreviva a +reinicializações de containers e atenda múltiplas réplicas da API ao mesmo +tempo. O cluster K3s roda em uma única VM. + +## Alternativas consideradas +- **DBaaS PostgreSQL gerenciado (externo)** — backup, patch e HA pelo provedor; + custo maior; menos controle fino sobre configurações. +- **PostgreSQL em pod com PVC** — custo baixo, tudo em um lugar; volume, backup + e recuperação por nossa conta; o dado morre junto com o cluster. + +## Decisão +Usar o serviço DBaaS PostgreSQL da Magalu Cloud, fora do cluster, acessado via +`Secret db-secret`. Critério decisivo: disponibilidade e custo de operação — +estado é caro de operar manualmente. + +## Consequências +**Positivas:** +- Backup automático e patches de segurança pelo provedor. +- O banco sobrevive a qualquer redeploy do cluster. +- Conexões simultâneas de múltiplos pods sem conflito. + +**Negativas:** +- Custo por hora de uso, mesmo com pouco tráfego. +- Menor controle sobre configurações avançadas do PostgreSQL. +- Dependência de conectividade de rede entre o cluster e o DBaaS. From 9308051648a68332f5d9ff2419b519f49a5ba6cf Mon Sep 17 00:00:00 2001 From: Esther Sant'Ana Gomes Date: Tue, 4 Aug 2026 21:55:22 -0300 Subject: [PATCH 2/3] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- docs/architecture.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/architecture.md b/docs/architecture.md index ad2e670..69849cc 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -23,6 +23,7 @@ flowchart LR subgraph mgc["Magalu Cloud"] subgraph vm["VM BV2-2-40 · K3s"] + kube["K3s API Server :6443"] svc["Klipper ServiceLB :80"] app["cloud-application · 2 pods (FastAPI)"] end @@ -34,7 +35,8 @@ flowchart LR svc -->|HTTP / JSON · TCP 8000| app app -->|SQL · TCP 5432| db gh -->|Docker Push · HTTPS 443| reg - gh -->|kubectl apply · HTTPS 6443| app + gh -->|kubectl apply · HTTPS 6443| kube + kube -->|cria/atualiza Deployments| app reg -->|Pull Image · HTTPS 443| app ``` From b82db10b748ff29c46281bbc6df7876045b845a5 Mon Sep 17 00:00:00 2001 From: esther Date: Tue, 4 Aug 2026 22:09:44 -0300 Subject: [PATCH 3/3] docs: ajusta diagrama C2 para incluir K3s API Server --- docs/architecture.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index 69849cc..a743144 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -20,7 +20,7 @@ API de pedidos containerizada, rodando em um cluster K3s (nó único) numa VM na flowchart LR cliente["Cliente HTTP"] gh["GitHub Actions"] - + subgraph mgc["Magalu Cloud"] subgraph vm["VM BV2-2-40 · K3s"] kube["K3s API Server :6443"] @@ -36,7 +36,7 @@ flowchart LR app -->|SQL · TCP 5432| db gh -->|Docker Push · HTTPS 443| reg gh -->|kubectl apply · HTTPS 6443| kube - kube -->|cria/atualiza Deployments| app + kube -->|Aplica manifests| app reg -->|Pull Image · HTTPS 443| app ```