From fff6dbb236e884f0ccef11917f6763ee3f4f97a7 Mon Sep 17 00:00:00 2001 From: amanda Date: Wed, 5 Aug 2026 23:20:44 +0000 Subject: [PATCH 01/13] Adiciona manifest Kubernetes e pipeline Deploy --- .github/workflows/deploy.yml | 55 ++++++++++++++++++++++++++++++++++++ k8s/app.yaml | 47 ++++++++++++++++++++++++++++++ 2 files changed, 102 insertions(+) create mode 100644 .github/workflows/deploy.yml create mode 100644 k8s/app.yaml diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml new file mode 100644 index 0000000..7b75bbc --- /dev/null +++ b/.github/workflows/deploy.yml @@ -0,0 +1,55 @@ +name: Deploy + +on: + workflow_dispatch: + +env: + REGISTRY: container-registry.br-se1.magalu.cloud + IMAGE_NAME: cloud-application + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Instalar dependências + run: | + pip install poetry + poetry install --no-root + + - name: Executar testes + run: poetry run pytest + + build-and-deploy: + needs: test + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Login no Container Registry + run: | + docker login https://${{ env.REGISTRY }} \ + -u ${{ secrets.MGC_REGISTRY_USER }} \ + -p ${{ secrets.MGC_REGISTRY_PASSWORD }} + + - name: Build e push da imagem + run: | + IMAGE=${{ env.REGISTRY }}/${{ secrets.MGC_REGISTRY_NAME }}/${{ env.IMAGE_NAME }}:latest + docker build -t $IMAGE . + docker push $IMAGE + + - name: Configurar kubectl + run: | + echo "${{ secrets.MGC_KUBECONFIG }}" > kubeconfig.yaml + + - name: Deploy no Kubernetes + run: | + export KUBECONFIG=kubeconfig.yaml + export MGC_REGISTRY_NAME=${{ secrets.MGC_REGISTRY_NAME }} + envsubst < k8s/app.yaml | kubectl apply -f - + kubectl rollout status deployment/cloud-application diff --git a/k8s/app.yaml b/k8s/app.yaml new file mode 100644 index 0000000..3263e1c --- /dev/null +++ b/k8s/app.yaml @@ -0,0 +1,47 @@ +apiVersion: apps/v1 +kind: Deployment +metadata: + name: cloud-application + labels: + app: cloud-application +spec: + replicas: 2 + selector: + matchLabels: + app: cloud-application + template: + metadata: + labels: + app: cloud-application + spec: + containers: + - name: cloud-application + image: container-registry.br-se1.magalu.cloud/${MGC_REGISTRY_NAME}/cloud-application:latest + ports: + - containerPort: 8000 + livenessProbe: + httpGet: + path: /health + port: 8000 + initialDelaySeconds: 10 + periodSeconds: 30 + readinessProbe: + httpGet: + path: /health + port: 8000 + initialDelaySeconds: 5 + periodSeconds: 10 + +--- + +apiVersion: v1 +kind: Service +metadata: + name: cloud-application +spec: + type: LoadBalancer + selector: + app: cloud-application + ports: + - port: 80 + targetPort: 8000 From f937675bd4e43e33e1459898d05225547f8594e1 Mon Sep 17 00:00:00 2001 From: amanda Date: Wed, 5 Aug 2026 23:36:51 +0000 Subject: [PATCH 02/13] Corrige quebra de linha na variavel IMAGE do pipeline --- .github/workflows/deploy.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 7b75bbc..3447b17 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -39,7 +39,7 @@ jobs: - name: Build e push da imagem run: | - IMAGE=${{ env.REGISTRY }}/${{ secrets.MGC_REGISTRY_NAME }}/${{ env.IMAGE_NAME }}:latest + IMAGE=container-registry.br-se1.magalu.cloud/${{ secrets.MGC_REGISTRY_NAME }}/cloud-application:latest docker build -t $IMAGE . docker push $IMAGE From 827d929ed42015a648bbe58b2444d0f7280ea248 Mon Sep 17 00:00:00 2001 From: amanda Date: Wed, 5 Aug 2026 23:47:40 +0000 Subject: [PATCH 03/13] Corrige sintaxe das variaveis no build do docker --- .github/workflows/deploy.yml | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 3447b17..2591b0c 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -39,9 +39,8 @@ jobs: - name: Build e push da imagem run: | - IMAGE=container-registry.br-se1.magalu.cloud/${{ secrets.MGC_REGISTRY_NAME }}/cloud-application:latest - docker build -t $IMAGE . - docker push $IMAGE + docker build -t ${{ env.REGISTRY }}/${{ secrets.MGC_REGISTRY_NAME }}/${{ env.IMAGE_NAME }}:latest . + docker push ${{ env.REGISTRY }}/${{ secrets.MGC_REGISTRY_NAME }}/${{ env.IMAGE_NAME }}:latest - name: Configurar kubectl run: | From 131a05e49d49c762ada7f7502062fe2b8dfffc53 Mon Sep 17 00:00:00 2001 From: amanda Date: Thu, 6 Aug 2026 00:00:15 +0000 Subject: [PATCH 04/13] Corrige sintaxe e quebra de linha do build --- .github/workflows/deploy.yml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 2591b0c..f86c8b8 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -39,8 +39,9 @@ jobs: - name: Build e push da imagem run: | - docker build -t ${{ env.REGISTRY }}/${{ secrets.MGC_REGISTRY_NAME }}/${{ env.IMAGE_NAME }}:latest . - docker push ${{ env.REGISTRY }}/${{ secrets.MGC_REGISTRY_NAME }}/${{ env.IMAGE_NAME }}:latest + IMAGE=${{ env.REGISTRY }}/${{ secrets.MGC_REGISTRY_NAME }}/${{ env.IMAGE_NAME }}:latest + docker build -t $IMAGE . + docker push $IMAGE - name: Configurar kubectl run: | From 90a6de19e006c602906ad65dcb8a85659c8e137b Mon Sep 17 00:00:00 2001 From: amanda Date: Thu, 6 Aug 2026 00:21:00 +0000 Subject: [PATCH 05/13] Adiciona ajustes na imagem --- .github/workflows/deploy.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index f86c8b8..7b75bbc 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -39,7 +39,7 @@ jobs: - name: Build e push da imagem run: | - IMAGE=${{ env.REGISTRY }}/${{ secrets.MGC_REGISTRY_NAME }}/${{ env.IMAGE_NAME }}:latest + IMAGE=${{ env.REGISTRY }}/${{ secrets.MGC_REGISTRY_NAME }}/${{ env.IMAGE_NAME }}:latest docker build -t $IMAGE . docker push $IMAGE From b35b8b6c53f75de66119161c5c8cb0fd09417ec3 Mon Sep 17 00:00:00 2001 From: amanda Date: Thu, 6 Aug 2026 02:06:10 +0000 Subject: [PATCH 06/13] feat: adiciona criacao do secret no pipeline --- .github/workflows/deploy.yml | 7 +++++++ k8s/app.yaml | 6 ++++++ 2 files changed, 13 insertions(+) diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 7b75bbc..8378bfd 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -47,6 +47,13 @@ jobs: run: | echo "${{ secrets.MGC_KUBECONFIG }}" > kubeconfig.yaml + - name: Criar Secret do banco + run: | + export KUBECONFIG=kubeconfig.yaml + kubectl create secret generic db-secret \ + --from-literal=url=${{ secrets.DATABASE_URL }} \ + --dry-run=client -o yaml | kubectl apply -f - + - name: Deploy no Kubernetes run: | export KUBECONFIG=kubeconfig.yaml diff --git a/k8s/app.yaml b/k8s/app.yaml index 3263e1c..cd38ebe 100644 --- a/k8s/app.yaml +++ b/k8s/app.yaml @@ -19,6 +19,12 @@ spec: image: container-registry.br-se1.magalu.cloud/${MGC_REGISTRY_NAME}/cloud-application:latest ports: - containerPort: 8000 + env: + - name: DATABASE_URL + valueFrom: + secretKeyRef: + name: db-secret + key: url livenessProbe: httpGet: path: /health From 3e730d605902dc98ff33ac79c80f3fd102369283 Mon Sep 17 00:00:00 2001 From: amanda Date: Thu, 6 Aug 2026 02:08:47 +0000 Subject: [PATCH 07/13] fix: corrige indentacao do yaml na linha 51 --- .github/workflows/deploy.yml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 8378bfd..d48a01a 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -48,11 +48,11 @@ jobs: echo "${{ secrets.MGC_KUBECONFIG }}" > kubeconfig.yaml - name: Criar Secret do banco - run: | - export KUBECONFIG=kubeconfig.yaml - kubectl create secret generic db-secret \ - --from-literal=url=${{ secrets.DATABASE_URL }} \ - --dry-run=client -o yaml | kubectl apply -f - + run: | + export KUBECONFIG=kubeconfig.yaml + kubectl create secret generic db-secret \ + --from-literal=url=${{ secrets.DATABASE_URL }} \ + --dry-run=client -o yaml | kubectl apply -f - - name: Deploy no Kubernetes run: | From 7b0bd2bd0002f7ee0b452d0d4d8ff058fd71d00c Mon Sep 17 00:00:00 2001 From: amanda Date: Fri, 7 Aug 2026 11:03:44 +0000 Subject: [PATCH 08/13] docs: adiciona modelagem de dados e garante manifestos atualizados --- docs/data-model.md | 72 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 docs/data-model.md diff --git a/docs/data-model.md b/docs/data-model.md new file mode 100644 index 0000000..1d70dbd --- /dev/null +++ b/docs/data-model.md @@ -0,0 +1,72 @@ +# 📊 Documentação de Modelagem de Dados + +Este documento detalha o modelo relacional de dados da aplicação, especificando os tipos de dados compatíveis com **PostgreSQL** e as restrições de integridade. + +--- + +## 🏗️ Diagrama Entidade-Relacionamento (ERD) + +Abaixo está a representação visual do relacionamento entre as tabelas através da tecnologia Mermaid. + +```mermaid +erDiagram + ORDERS ||--o{ ITEMS : "contém (1:N)" + + ORDERS { + VARCHAR_36 id PK "UUID gerado pela aplicação" + TIMESTAMP created_at "Data e hora do pedido" + VARCHAR_50 status "Status atual (ex: PENDING, PAID, SHIPPED)" + DECIMAL_10_2 total_amount "Valor total do pedido" + } + + ITEMS { + VARCHAR_36 id PK "UUID gerado pela aplicação" + VARCHAR_36 order_id FK "Chave Estrangeira vinculada a ORDERS" + VARCHAR_255 product_name "Nome do produto" + INTEGER quantity "Quantidade comprada" + DECIMAL_10_2 unit_price "Preço unitário do item" + } +``` + +--- + +## 🗄️ Dicionário de Dados (Entidades) + +### 📦 1. Pedido (`orders`) +Armazena as informações principais e o status do pedido de compra. + +| Coluna | Tipo (SQL/PostgreSQL) | Restrições | Descrição | +| :--- | :--- | :--- | :--- | +| `id` | `VARCHAR(36)` / `UUID` | `PRIMARY KEY` | Identificador único universal do pedido. | +| `created_at` | `TIMESTAMP` | `NOT NULL`, `DEFAULT NOW()` | Carimbo de data/hora da criação do registro. | +| `status` | `VARCHAR(50)` | `NOT NULL` | Estado do pedido (ex: `PENDING`, `COMPLETED`, `CANCELED`). | +| `total_amount` | `DECIMAL(10, 2)` | `NOT NULL`, `>= 0` | Valor total financeiro somado do pedido. | + +### 🧩 2. Item (`items`) +Armazena os produtos vinculados a cada pedido (Linhas do pedido). + +| Coluna | Tipo (SQL/PostgreSQL) | Restrições | Descrição | +| :--- | :--- | :--- | :--- | +| `id` | `VARCHAR(36)` / `UUID` | `PRIMARY KEY` | Identificador único universal do item. | +| `order_id` | `VARCHAR(36)` / `UUID` | `FOREIGN KEY` | Vinculo com `orders(id)` com regra `ON DELETE CASCADE`. | +| `product_name` | `VARCHAR(255)` | `NOT NULL` | Nome comercial do produto adquirido. | +| `quantity` | `INTEGER` | `NOT NULL`, `> 0` | Quantidade de unidades compradas deste produto. | +| `unit_price` | `DECIMAL(10, 2)` | `NOT NULL`, `>= 0` | Preço cobrado por uma única unidade do produto. | + +--- + +## 🔗 Relacionamentos e Regras de Negócio + +* **Cardinalidade:** `1:N` (Um para Muitos). Um **Pedido** (`orders`) pode conter um ou vários **Itens** (`items`), mas um item pertence obrigatoriamente a apenas um pedido. +* **Integridade Referencial:** A coluna `order_id` na tabela `items` possui uma restrição de chave estrangeira apontando para `id` na tabela `orders`. +* **Cascata (`ON DELETE CASCADE`):** Caso um pedido seja deletado do sistema, todos os itens associados a ele serão removidos do banco automaticamente para evitar dados órfãos. + +--- + +## 🚀 Engenharia e Estratégia de Persistência + +As tabelas são mapeadas via **SQLAlchemy ORM (Python)** com migrações gerenciadas pelo **Alembic**. + +1. **A aplicação lê o modelo:** As classes declarativas em `app/models.py` definem a estrutura lógica. +2. **Abstração do Banco:** O SQLAlchemy traduz as classes Python em tabelas nativas `DOCKER-POSTGRESQL`. +3. **Idempotência:** A criação e evolução do banco usam rotinas que verificam se as tabelas já existem antes de executar comandos `DDL`. From 284f750f169e900b03955fd0f2ad46c83353cff3 Mon Sep 17 00:00:00 2001 From: amanda Date: Fri, 7 Aug 2026 18:04:47 +0000 Subject: [PATCH 09/13] docs: adiciona especificacao arquitetural e diagrama mermaid --- docs/architecture.md | 60 +++++++++++++++++++++++++++++++++++++++++ k8s/app.yaml | 5 +++- k8s/servicemonitor.yaml | 18 +++++++++++++ 3 files changed, 82 insertions(+), 1 deletion(-) create mode 100644 docs/architecture.md create mode 100644 k8s/servicemonitor.yaml diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..afc9626 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,60 @@ +# Arquitetura da Solução - Monitoramento e Resiliência + +## Diagrama da Arquitetura (Mermaid) + +```mermaid +graph TB + subgraph Internet ["Mundo Externo (Fora da Magalu Cloud)"] + GH[GitHub Actions] + end + + subgraph MGC ["Magalu Cloud (MGC)"] + CR[Container Registry] + DB[(DBaaS PostgreSQL)] + + subgraph VM ["Máquina Virtual (K3s Single Node)"] + LB[Klipper ServiceLB
IP da VM: Porta 80] + + subgraph K8s [Cluster Kubernetes Namespace: default] + API1[API - Réplica 1
Porta 8000] + API2[API - Réplica 2
Porta 8000] + end + end + end + + %% Fluxo de CI/CD + GH -->|1. Envia Imagem Docker via HTTPS| CR + CR -->|2. Pull da Imagem via HTTPS| K8s + + %% Fluxo de Tráfego Externo + Internet -->|3. Requisição HTTP / Porta 80| LB + LB -->|4. Roteia Tráfego / HTTP Porta 8000| API1 + LB -->|4. Roteia Tráfego / HTTP Porta 8000| API2 + + %% Fluxo de Dados + API1 -->|5. Persistência de Dados / TCP 5432| DB + API2 -->|5. Persistência de Dados / TCP 5432| DB +``` + +## Componentes da Arquitetura + +| Componente | Serviço MGC | Função | +| :--- | :--- | :--- | +| **API** | K3s (VM BV2-2-40 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 fornece 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, sum(rate(http_request_duration_seconds_bucket[5m])) by (le))` no endpoint `/metrics` | P95 < 500 ms | +| **Escalabilidade** | Teste de carga (k6) + verificando `rate(http_requests_total[5m])` | 300 req/s sem degradação | +| **Custo** | VM + DBaaS + IP Alocado calculados via plataforma MGC | Teto financeiro definido em ADR | + +## Estilo Arquitetural + +A solução implementada adota o estilo de **Monolito em Camadas** (Apresentação $\rightarrow$ Serviço $\rightarrow$ Dados). O deploy é consolidado em infraestrutura conteinerizada executando de forma resiliente em **duas réplicas simultâneas** sob gerência do K3s, garantindo tolerância a falhas localizadas e auto-recuperação (*self-healing*). Como estratégia de evolução (estilo-alvo), caso o domínio de notificações/eventos apresente gargalos de escalabilidade, a arquitetura prevê o desacoplamento desse componente em um microserviço especializado orientado a eventos. diff --git a/k8s/app.yaml b/k8s/app.yaml index cd38ebe..de15a0f 100644 --- a/k8s/app.yaml +++ b/k8s/app.yaml @@ -44,10 +44,13 @@ apiVersion: v1 kind: Service metadata: name: cloud-application + labels: + app: cloud-application spec: type: LoadBalancer selector: app: cloud-application ports: - - port: 80 + - name: http + port: 80 targetPort: 8000 diff --git a/k8s/servicemonitor.yaml b/k8s/servicemonitor.yaml new file mode 100644 index 0000000..585d169 --- /dev/null +++ b/k8s/servicemonitor.yaml @@ -0,0 +1,18 @@ +apiVersion: monitoring.coreos.com/v1 +kind: ServiceMonitor +metadata: + name: cloud-application + namespace: default + labels: + release: monitoring # obrigatório: identifica este ServiceMonitor para o kube-prometheus-stack +spec: + namespaceSelector: + matchNames: + - default + selector: + matchLabels: + app: cloud-application + endpoints: + - port: http + path: /metrics + interval: 30s From ea08c0da484c6143b8961b0acb09ba1cf6b0f288 Mon Sep 17 00:00:00 2001 From: amanda Date: Fri, 7 Aug 2026 18:10:19 +0000 Subject: [PATCH 10/13] =?UTF-8?q?docs:=20adiciona=20ADR=20001=20e=20ADR=20?= =?UTF-8?q?002=20detalhando=20as=20decis=C3=B5es=20de=20infraestrutura?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/adr/001-kubernetes-deploy.md | 29 +++++++++++++++++++++++++++++ docs/adr/002-dbaas-postgresql.md | 26 ++++++++++++++++++++++++++ 2 files changed, 55 insertions(+) create mode 100644 docs/adr/001-kubernetes-deploy.md create mode 100644 docs/adr/002-dbaas-postgresql.md diff --git a/docs/adr/001-kubernetes-deploy.md b/docs/adr/001-kubernetes-deploy.md new file mode 100644 index 0000000..30530bc --- /dev/null +++ b/docs/adr/001-kubernetes-deploy.md @@ -0,0 +1,29 @@ +# ADR 001 — Usar K3s para deploy da aplicação + +**Status:** Aceito +**Data:** 2026-08-04 + +## Contexto +A aplicação precisa ser implantada na Magalu Cloud de forma acessível publicamente, resiliente a falhas e com capacidade de escalar. + +## Alternativas consideradas +- **K3s em VM** — Kubernetes leve; cobra só a VM; provisionamento < 2 min; sem HA nativa. +- **MKS (Kubernetes Gerenciado)** — control plane e HA gerenciados; custo maior; provisionamento 5-10 min. +- **VM com Docker Compose** — mais simples de subir; sem orquestração, self-healing nem escala declarativa. + +## Decisão +Usar K3s em uma VM BV2-2-40 (Ubuntu 24.04) com Klipper ServiceLB para expor a aplicação na porta 80 do IP público da VM. O script `k3s-mgc` automatiza todo o provisionamento. Critério: menor custo e provisionamento mais rápido, com manifests idênticos a qualquer Kubernetes. + +## Consequências +**Positivas:** +- Custo menor que o MKS (cobra apenas pela VM e não pelo control plane) +- Provisionamento em menos de 2 minutos +- Manifests YAML idênticos a qualquer Kubernetes padrão (sem lock-in) +- Restart automático em caso de falha (liveness probe) +- Escalabilidade horizontal simples (basta aumentar o número de réplicas) + +**Negativas:** +- Single point of failure: sem alta disponibilidade nativa (tudo em uma VM) +- Armazenamento efêmero: volumes locais desaparecem se a VM for recriada +- Sem auto-scaling de nós: capacidade fixa (2 vCPU, 2 GB) +- IP público muda se a VM for substituída diff --git a/docs/adr/002-dbaas-postgresql.md b/docs/adr/002-dbaas-postgresql.md new file mode 100644 index 0000000..2a0ab39 --- /dev/null +++ b/docs/adr/002-dbaas-postgresql.md @@ -0,0 +1,26 @@ +# ADR 002 — Usar DBaaS PostgreSQL da Magalu Cloud + +**Status:** Aceito +**Data:** 2026-08-04 + +## Contexto +A aplicação precisa de persistência de dados. O banco precisa sobreviver a reinicializações de containers e estar disponível para múltiplas réplicas da API simultaneamente. + +## Alternativas consideradas +- **DBaaS PostgreSQL gerenciado (externo)** — backup, patch e HA pelo provedor; custo maior; menos controle fino. +- **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 — banco gerenciado, sem necessidade de operar o servidor de banco de dados. Critério: disponibilidade e custo de operação (estado é caro de operar manualmente). + +## Consequências +**Positivas:** +- Backup automático gerenciado pelo provedor +- Sem custo operacional de administração do banco +- Conexões simultâneas de múltiplos pods sem conflito +- Alta disponibilidade incluída no serviço + +**Negativas:** +- Custo por hora de uso, mesmo com pouco tráfego +- Menor controle sobre configurações avançadas do PostgreSQL +- Dependência do provedor para upgrades de versão From cb3ea17df27618f189e3506ddb88f207623ec4e0 Mon Sep 17 00:00:00 2001 From: amanda Date: Fri, 7 Aug 2026 18:15:04 +0000 Subject: [PATCH 11/13] docs: finaliza documentacao de arquitetura adicionando roadmap e estimativa de custos --- docs/architecture.md | 48 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/docs/architecture.md b/docs/architecture.md index afc9626..ac1601d 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -58,3 +58,51 @@ graph TB ## Estilo Arquitetural A solução implementada adota o estilo de **Monolito em Camadas** (Apresentação $\rightarrow$ Serviço $\rightarrow$ Dados). O deploy é consolidado em infraestrutura conteinerizada executando de forma resiliente em **duas réplicas simultâneas** sob gerência do K3s, garantindo tolerância a falhas localizadas e auto-recuperação (*self-healing*). Como estratégia de evolução (estilo-alvo), caso o domínio de notificações/eventos apresente gargalos de escalabilidade, a arquitetura prevê o desacoplamento desse componente em um microserviço especializado orientado a eventos. + + + +## Análise de Trade-offs + +| 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 + +### Escalabilidade Horizontall e Próximos Passos +A aplicação possui arquitetura *stateless*, permitindo a escalabilidade horizontal simples através da adição de novas réplicas atrás do balanceador de carga. Atualmente, a arquitetura está fixada em 2 réplicas. + +O próximo passo evolutivo para o ambiente é a implementação do **HPA (Horizontal Pod Autoscaler)**, configurado para ajustar dinamicamente o volume de réplicas baseado na utilização de CPU (ex: mínimo de 2, máximo de 6 pods, com alvo de 70% de utilização). + +*Nota de Arquitetura:* É crucial registrar que o escalonamento horizontal da API não resolve gargalos na camada de dados. O **DBaaS PostgreSQL** escala predominantemente na vertical e tende a saturar antes da camada de aplicação caso o volume de requisições cresça indefinidamente. + +### Roadmap de Evolução Técnica + +| Melhoria | Por quê | +| :--- | :--- | +| **HTTPS / TLS** | Toda API em produção deve ser acessada de forma segura e criptografada por HTTPS. | +| **Autoscaler (HPA)** | Garante escala automatizada do ambiente sob picos sazonais de carga. | +| **Versionamento de API** | Uso de prefixos como `/v1/orders` permite evoluir o software sem quebrar os clientes legados. | +| **Rate Limiting** | Evita abusos e ataques de negação de serviço, protegendo a camada de banco de sobrecargas. | +| **Cache (Redis)** | Intercepta requisições repetidas na memória, reduzindo consultas redundantes ao PostgreSQL. | +| **Migrações de Schema (Alembic)** | Garante o controle de versão e rastreabilidade sobre as mudanças estruturais do banco. | +| **Testes de Carga** | Valida de forma proativa o comportamento e resiliência do ecossistema sob alto tráfego. | +| **Migração para MKS** | Transição mandatória para alta disponibilidade (HA) real da infraestrutura; os manifests YAML permanecem idênticos. | + +### Custo Estimado na Magalu Cloud + +Com base na tabela de precificação transparente e faturamento em Real (BRL) da plataforma Magalu Cloud, a composição de custos da infraestrutura atual envolve: + +| Recurso | Especificação | Observação | +| :--- | :--- | :--- | +| **VM K3s** | BV2-2-40 (2 vCPU, 2 GB) | Instância Compute básica calculada e cobrada estritamente por hora de uso. | +| **DBaaS PostgreSQL** | Instância Pequena (Gerenciada) | Banco de dados relacional gerenciado, faturado por hora ativa de uso. | +| **Container Registry** | Armazenamento de Imagens | Custo marginal e otimizado para o armazenamento de imagens consolidadas com volumetria inferior a 500 MB. | + +*(Os preços vigentes e atualizados podem ser validados oficialmente em: https://magalu.cloud/precos/)* From 291e1ff1d2ecc855e1d491f395adb57c692c9ded Mon Sep 17 00:00:00 2001 From: amanda Date: Fri, 7 Aug 2026 19:17:57 +0000 Subject: [PATCH 12/13] =?UTF-8?q?docs:=20adiciona=20documenta=C3=A7=C3=A3o?= =?UTF-8?q?=20de=20arquitetura=20e=20ADRs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/adr/001-kubernetes-deploy.md | 58 +++++++--- docs/adr/002-dbaas-postgresql.md | 49 +++++--- docs/adr/003-github-actions-cicd.md | 48 ++++++++ docs/adr/004-estimativa-custos.md | 41 +++++++ docs/architecture.md | 166 +++++++++++++++------------- 5 files changed, 256 insertions(+), 106 deletions(-) create mode 100644 docs/adr/003-github-actions-cicd.md create mode 100644 docs/adr/004-estimativa-custos.md diff --git a/docs/adr/001-kubernetes-deploy.md b/docs/adr/001-kubernetes-deploy.md index 30530bc..d316df9 100644 --- a/docs/adr/001-kubernetes-deploy.md +++ b/docs/adr/001-kubernetes-deploy.md @@ -1,29 +1,53 @@ # ADR 001 — Usar K3s para deploy da aplicação **Status:** Aceito -**Data:** 2026-08-04 + +**Data:** 2026-08-07 ## Contexto + A aplicação precisa ser implantada na Magalu Cloud de forma acessível publicamente, resiliente a falhas e com capacidade de escalar. ## Alternativas consideradas -- **K3s em VM** — Kubernetes leve; cobra só a VM; provisionamento < 2 min; sem HA nativa. -- **MKS (Kubernetes Gerenciado)** — control plane e HA gerenciados; custo maior; provisionamento 5-10 min. -- **VM com Docker Compose** — mais simples de subir; sem orquestração, self-healing nem escala declarativa. + +### K3s em VM + +- Kubernetes leve +- Menor custo +- Provisionamento rápido +- Sem alta disponibilidade nativa + +### MKS (Kubernetes Gerenciado) + +- Alta disponibilidade nativa +- Gerenciamento simplificado +- Maior custo + +### Docker Compose em VM + +- Simples de configurar +- Sem orquestração +- Sem self-healing ## Decisão -Usar K3s em uma VM BV2-2-40 (Ubuntu 24.04) com Klipper ServiceLB para expor a aplicação na porta 80 do IP público da VM. O script `k3s-mgc` automatiza todo o provisionamento. Critério: menor custo e provisionamento mais rápido, com manifests idênticos a qualquer Kubernetes. + +Utilizar K3s em uma VM BV2-2-40 para executar a aplicação. + +### Critério da decisão + +Menor custo operacional, provisionamento rápido e compatibilidade com Kubernetes padrão. ## Consequências -**Positivas:** -- Custo menor que o MKS (cobra apenas pela VM e não pelo control plane) -- Provisionamento em menos de 2 minutos -- Manifests YAML idênticos a qualquer Kubernetes padrão (sem lock-in) -- Restart automático em caso de falha (liveness probe) -- Escalabilidade horizontal simples (basta aumentar o número de réplicas) - -**Negativas:** -- Single point of failure: sem alta disponibilidade nativa (tudo em uma VM) -- Armazenamento efêmero: volumes locais desaparecem se a VM for recriada -- Sem auto-scaling de nós: capacidade fixa (2 vCPU, 2 GB) -- IP público muda se a VM for substituída + +### Positivas + +- Baixo custo +- Provisionamento rápido +- Facilidade de escalabilidade horizontal +- Compatibilidade com Kubernetes + +### Negativas + +- Ponto único de falha +- Sem alta disponibilidade nativa +- Recursos limitados à VM diff --git a/docs/adr/002-dbaas-postgresql.md b/docs/adr/002-dbaas-postgresql.md index 2a0ab39..ea8641e 100644 --- a/docs/adr/002-dbaas-postgresql.md +++ b/docs/adr/002-dbaas-postgresql.md @@ -1,26 +1,45 @@ # ADR 002 — Usar DBaaS PostgreSQL da Magalu Cloud **Status:** Aceito -**Data:** 2026-08-04 + +**Data:** 2026-08-07 ## Contexto -A aplicação precisa de persistência de dados. O banco precisa sobreviver a reinicializações de containers e estar disponível para múltiplas réplicas da API simultaneamente. + +A aplicação precisa armazenar pedidos e itens de forma persistente e acessível para múltiplas réplicas da API. ## Alternativas consideradas -- **DBaaS PostgreSQL gerenciado (externo)** — backup, patch e HA pelo provedor; custo maior; menos controle fino. -- **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. + +### DBaaS PostgreSQL + +- Backup gerenciado +- Alta disponibilidade +- Menor esforço operacional + +### PostgreSQL em Container + +- Menor custo inicial +- Maior responsabilidade operacional +- Backup manual ## Decisão -Usar o serviço DBaaS PostgreSQL da Magalu Cloud — banco gerenciado, sem necessidade de operar o servidor de banco de dados. Critério: disponibilidade e custo de operação (estado é caro de operar manualmente). + +Utilizar o DBaaS PostgreSQL da Magalu Cloud. + +### Critério da decisão + +Garantir persistência dos dados com menor custo operacional e maior confiabilidade. ## Consequências -**Positivas:** -- Backup automático gerenciado pelo provedor -- Sem custo operacional de administração do banco -- Conexões simultâneas de múltiplos pods sem conflito -- Alta disponibilidade incluída no serviço - -**Negativas:** -- Custo por hora de uso, mesmo com pouco tráfego -- Menor controle sobre configurações avançadas do PostgreSQL -- Dependência do provedor para upgrades de versão + +### Positivas + +- Backup automático +- Menor manutenção +- Alta disponibilidade + +### Negativas + +- Custo recorrente +- Dependência do provedor +- Menor controle de configuração diff --git a/docs/adr/003-github-actions-cicd.md b/docs/adr/003-github-actions-cicd.md new file mode 100644 index 0000000..a9955c1 --- /dev/null +++ b/docs/adr/003-github-actions-cicd.md @@ -0,0 +1,48 @@ +# ADR 003 — Utilizar GitHub Actions para CI/CD + +**Status:** Aceito + +**Data:** 2026-08-07 + +## Contexto + +A aplicação necessita de um processo automatizado para build, testes e deploy, reduzindo erros manuais e aumentando a rastreabilidade das entregas. + +## Alternativas consideradas + +### GitHub Actions + +- Integração nativa com GitHub +- Fácil configuração +- Sem necessidade de servidor dedicado + +### Jenkins + +- Altamente customizável +- Requer administração própria + +### Deploy Manual + +- Simples inicialmente +- Propenso a erros humanos + +## Decisão + +Utilizar GitHub Actions como ferramenta de CI/CD. + +### Critério da decisão + +Integração nativa com o repositório, facilidade de manutenção e automação do processo de entrega. + +## Consequências + +### Positivas + +- Deploy automatizado +- Rastreabilidade das versões +- Menor risco de erro manual + +### Negativas + +- Dependência do GitHub +- Curva inicial de aprendizado para workflows diff --git a/docs/adr/004-estimativa-custos.md b/docs/adr/004-estimativa-custos.md new file mode 100644 index 0000000..aadd6fc --- /dev/null +++ b/docs/adr/004-estimativa-custos.md @@ -0,0 +1,41 @@ +# ADR 004 — Estimativa de Custos da Solução + +**Status:** Aceito + +**Data:** 2026-08-07 + +## Contexto + +A solução deve operar com baixo custo, mantendo disponibilidade adequada para um ambiente de aprendizado e desenvolvimento. + +## Componentes de custo + +| Recurso | Finalidade | +|----------|-----------| +| VM BV2-2-40 | Execução do cluster K3s | +| DBaaS PostgreSQL | Persistência dos dados | +| Container Registry | Armazenamento das imagens Docker | + +## Decisão + +Utilizar recursos de menor porte disponíveis para atender aos requisitos da aplicação. + +### Critério da decisão + +Equilibrar custo, simplicidade operacional e disponibilidade. + +## Consequências + +### Positivas + +- Baixo custo operacional +- Ambiente simples de administrar + +### Negativas + +- Limitação de capacidade +- Necessidade de upgrade caso o tráfego aumente + +## Observação + +Os valores podem variar conforme a tabela de preços vigente da Magalu Cloud. diff --git a/docs/architecture.md b/docs/architecture.md index ac1601d..0a417c1 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,108 +1,126 @@ -# Arquitetura da Solução - Monitoramento e Resiliência +# Arquitetura da Solução -## Diagrama da Arquitetura (Mermaid) +## Diagrama C1 - Contexto + +```mermaid +graph TD + + User[Usuário Final] + GitHub[GitHub Actions] + App[Sistema de Pedidos] + DB[(DBaaS PostgreSQL)] + + User -->|HTTP| App + GitHub -->|CI/CD| App + App -->|CRUD de Pedidos e Itens| DB +``` + +--- + +## Diagrama C2 - Containers ```mermaid graph TB - subgraph Internet ["Mundo Externo (Fora da Magalu Cloud)"] - GH[GitHub Actions] - end - subgraph MGC ["Magalu Cloud (MGC)"] - CR[Container Registry] + Browser[Usuário / Navegador] + + GH[GitHub Actions] + + subgraph MGC [Magalu Cloud] + + Registry[Container Registry] + DB[(DBaaS PostgreSQL)] - subgraph VM ["Máquina Virtual (K3s Single Node)"] - LB[Klipper ServiceLB
IP da VM: Porta 80] - - subgraph K8s [Cluster Kubernetes Namespace: default] - API1[API - Réplica 1
Porta 8000] - API2[API - Réplica 2
Porta 8000] - end + subgraph VM [VM BV2-2-40 - K3s] + + LB[Klipper ServiceLB] + + API1[API Pod 1] + + API2[API Pod 2] + end + end - %% Fluxo de CI/CD - GH -->|1. Envia Imagem Docker via HTTPS| CR - CR -->|2. Pull da Imagem via HTTPS| K8s + Browser -->|Requisição HTTP Porta 80| LB - %% Fluxo de Tráfego Externo - Internet -->|3. Requisição HTTP / Porta 80| LB - LB -->|4. Roteia Tráfego / HTTP Porta 8000| API1 - LB -->|4. Roteia Tráfego / HTTP Porta 8000| API2 + LB -->|HTTP Interno| API1 + LB -->|HTTP Interno| API2 - %% Fluxo de Dados - API1 -->|5. Persistência de Dados / TCP 5432| DB - API2 -->|5. Persistência de Dados / TCP 5432| DB -``` + API1 -->|TCP 5432 Leitura e Escrita| DB + API2 -->|TCP 5432 Leitura e Escrita| DB -## Componentes da Arquitetura + GH -->|Publica imagem Docker via HTTPS| Registry -| Componente | Serviço MGC | Função | -| :--- | :--- | :--- | -| **API** | K3s (VM BV2-2-40 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 fornece acesso externo | -| **CI/CD** | GitHub Actions | Automatiza testes, build e deploy | + GH -->|Atualiza Deployment Kubernetes| VM -## Requisitos Não-Funcionais + VM -->|Pull da imagem via HTTPS| Registry +``` -| Requisito | Como medir | Alvo | -| :--- | :--- | :--- | -| **Disponibilidade** | Erros 5xx e uptime das probes no Grafana | 99,5% mensal | -| **Latência** | `histogram_quantile(0.95, sum(rate(http_request_duration_seconds_bucket[5m])) by (le))` no endpoint `/metrics` | P95 < 500 ms | -| **Escalabilidade** | Teste de carga (k6) + verificando `rate(http_requests_total[5m])` | 300 req/s sem degradação | -| **Custo** | VM + DBaaS + IP Alocado calculados via plataforma MGC | Teto financeiro definido em ADR | +--- -## Estilo Arquitetural +## Componentes da Arquitetura -A solução implementada adota o estilo de **Monolito em Camadas** (Apresentação $\rightarrow$ Serviço $\rightarrow$ Dados). O deploy é consolidado em infraestrutura conteinerizada executando de forma resiliente em **duas réplicas simultâneas** sob gerência do K3s, garantindo tolerância a falhas localizadas e auto-recuperação (*self-healing*). Como estratégia de evolução (estilo-alvo), caso o domínio de notificações/eventos apresente gargalos de escalabilidade, a arquitetura prevê o desacoplamento desse componente em um microserviço especializado orientado a eventos. +| Componente | Serviço | Função | +|------------|----------|---------| +| API | K3s (2 réplicas) | Processar requisições HTTP | +| DBaaS PostgreSQL | Banco Gerenciado | Persistir pedidos e itens | +| Container Registry | Registry MGC | Armazenar imagens Docker | +| Klipper ServiceLB | Balanceador de Carga | Distribuir tráfego entre pods | +| GitHub Actions | CI/CD | Automatizar build e deploy | +--- +## Fluxo de uma Requisição -## Análise de Trade-offs +1. O usuário acessa a aplicação pelo navegador. +2. A requisição HTTP chega ao Klipper ServiceLB através do IP público da VM. +3. O balanceador encaminha a requisição para uma das duas réplicas da API. +4. A API processa a requisição. +5. Caso necessário, a API consulta ou grava dados no DBaaS PostgreSQL pela porta 5432. +6. O banco retorna os dados para a API. +7. A API devolve a resposta HTTP para o usuário. -| 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 | +--- +## Requisitos Não Funcionais +| Requisito | Como medir | Alvo | +|------------|------------|-------| +| Disponibilidade | Erros 5xx e uptime das probes | 99,5% mensal | +| Latência | P95 das requisições | Menor que 500 ms | +| Escalabilidade | Teste de carga k6 | 300 req/s sem degradação | +| Custo | VM + DBaaS + Registry | Conforme orçamento definido nos ADRs | + +--- -## Pontos de Melhoria e Próximos Passos +## Estilo Arquitetural -### Escalabilidade Horizontall e Próximos Passos -A aplicação possui arquitetura *stateless*, permitindo a escalabilidade horizontal simples através da adição de novas réplicas atrás do balanceador de carga. Atualmente, a arquitetura está fixada em 2 réplicas. +A solução segue o estilo arquitetural de **Monólito em Camadas**, composto pelas camadas de apresentação, serviço e dados. -O próximo passo evolutivo para o ambiente é a implementação do **HPA (Horizontal Pod Autoscaler)**, configurado para ajustar dinamicamente o volume de réplicas baseado na utilização de CPU (ex: mínimo de 2, máximo de 6 pods, com alvo de 70% de utilização). +A aplicação é empacotada em um único container Docker e implantada em duas réplicas no cluster Kubernetes K3s. -*Nota de Arquitetura:* É crucial registrar que o escalonamento horizontal da API não resolve gargalos na camada de dados. O **DBaaS PostgreSQL** escala predominantemente na vertical e tende a saturar antes da camada de aplicação caso o volume de requisições cresça indefinidamente. +O banco de dados é executado externamente através do serviço DBaaS PostgreSQL da Magalu Cloud. -### Roadmap de Evolução Técnica +--- -| Melhoria | Por quê | -| :--- | :--- | -| **HTTPS / TLS** | Toda API em produção deve ser acessada de forma segura e criptografada por HTTPS. | -| **Autoscaler (HPA)** | Garante escala automatizada do ambiente sob picos sazonais de carga. | -| **Versionamento de API** | Uso de prefixos como `/v1/orders` permite evoluir o software sem quebrar os clientes legados. | -| **Rate Limiting** | Evita abusos e ataques de negação de serviço, protegendo a camada de banco de sobrecargas. | -| **Cache (Redis)** | Intercepta requisições repetidas na memória, reduzindo consultas redundantes ao PostgreSQL. | -| **Migrações de Schema (Alembic)** | Garante o controle de versão e rastreabilidade sobre as mudanças estruturais do banco. | -| **Testes de Carga** | Valida de forma proativa o comportamento e resiliência do ecossistema sob alto tráfego. | -| **Migração para MKS** | Transição mandatória para alta disponibilidade (HA) real da infraestrutura; os manifests YAML permanecem idênticos. | +## Estado Atual da Solução -### Custo Estimado na Magalu Cloud +- Cluster K3s executando em VM BV2-2-40. +- Duas réplicas da API. +- Banco de dados PostgreSQL gerenciado (DBaaS). +- Deploy automatizado por GitHub Actions. +- Imagens armazenadas no Container Registry. -Com base na tabela de precificação transparente e faturamento em Real (BRL) da plataforma Magalu Cloud, a composição de custos da infraestrutura atual envolve: +--- -| Recurso | Especificação | Observação | -| :--- | :--- | :--- | -| **VM K3s** | BV2-2-40 (2 vCPU, 2 GB) | Instância Compute básica calculada e cobrada estritamente por hora de uso. | -| **DBaaS PostgreSQL** | Instância Pequena (Gerenciada) | Banco de dados relacional gerenciado, faturado por hora ativa de uso. | -| **Container Registry** | Armazenamento de Imagens | Custo marginal e otimizado para o armazenamento de imagens consolidadas com volumetria inferior a 500 MB. | +## Limitações da Arquitetura -*(Os preços vigentes e atualizados podem ser validados oficialmente em: https://magalu.cloud/precos/)* +- Cluster executando em nó único (single node). +- Ponto único de falha na VM. +- Ausência de auto scaling. +- Sem HTTPS/TLS configurado. +- Dependência do DBaaS para persistência dos dados. +- Balanceamento limitado ao Klipper ServiceLB. From a392e54639f98798680086daf0bfbe9e33d2d630 Mon Sep 17 00:00:00 2001 From: amanda Date: Sat, 8 Aug 2026 23:57:34 +0000 Subject: [PATCH 13/13] docs: finaliza arquitetura completa, trade-offs, custos e 3 ADRs --- docs/adr/004-estimativa-custos.md | 41 ------------------ docs/architecture.md | 71 ++++++++++++++++++++++++++----- 2 files changed, 60 insertions(+), 52 deletions(-) delete mode 100644 docs/adr/004-estimativa-custos.md diff --git a/docs/adr/004-estimativa-custos.md b/docs/adr/004-estimativa-custos.md deleted file mode 100644 index aadd6fc..0000000 --- a/docs/adr/004-estimativa-custos.md +++ /dev/null @@ -1,41 +0,0 @@ -# ADR 004 — Estimativa de Custos da Solução - -**Status:** Aceito - -**Data:** 2026-08-07 - -## Contexto - -A solução deve operar com baixo custo, mantendo disponibilidade adequada para um ambiente de aprendizado e desenvolvimento. - -## Componentes de custo - -| Recurso | Finalidade | -|----------|-----------| -| VM BV2-2-40 | Execução do cluster K3s | -| DBaaS PostgreSQL | Persistência dos dados | -| Container Registry | Armazenamento das imagens Docker | - -## Decisão - -Utilizar recursos de menor porte disponíveis para atender aos requisitos da aplicação. - -### Critério da decisão - -Equilibrar custo, simplicidade operacional e disponibilidade. - -## Consequências - -### Positivas - -- Baixo custo operacional -- Ambiente simples de administrar - -### Negativas - -- Limitação de capacidade -- Necessidade de upgrade caso o tráfego aumente - -## Observação - -Os valores podem variar conforme a tabela de preços vigente da Magalu Cloud. diff --git a/docs/architecture.md b/docs/architecture.md index 0a417c1..dbbcd0d 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -63,13 +63,13 @@ graph TB ## Componentes da Arquitetura -| Componente | Serviço | Função | -|------------|----------|---------| +| Componente | Serviço MGC | Função | +|------------|-------------|--------| | API | K3s (2 réplicas) | Processar requisições HTTP | -| DBaaS PostgreSQL | Banco Gerenciado | Persistir pedidos e itens | -| Container Registry | Registry MGC | Armazenar imagens Docker | -| Klipper ServiceLB | Balanceador de Carga | Distribuir tráfego entre pods | -| GitHub Actions | CI/CD | Automatizar build e deploy | +| Banco de dados | DBaaS PostgreSQL | Persistir 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 fornece acesso externo | +| CI/CD | GitHub Actions | Automatiza testes, build e deploy | --- @@ -88,11 +88,11 @@ graph TB ## Requisitos Não Funcionais | Requisito | Como medir | Alvo | -|------------|------------|-------| -| Disponibilidade | Erros 5xx e uptime das probes | 99,5% mensal | -| Latência | P95 das requisições | Menor que 500 ms | -| Escalabilidade | Teste de carga k6 | 300 req/s sem degradação | -| Custo | VM + DBaaS + Registry | Conforme orçamento definido nos ADRs | +|-----------|------------|------| +| 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 | --- @@ -106,6 +106,18 @@ O banco de dados é executado externamente através do serviço DBaaS PostgreSQL --- +## Trade-offs + +| 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 | + +--- + ## Estado Atual da Solução - Cluster K3s executando em VM BV2-2-40. @@ -124,3 +136,40 @@ O banco de dados é executado externamente através do serviço DBaaS PostgreSQL - Sem HTTPS/TLS configurado. - Dependência do DBaaS para persistência dos dados. - Balanceamento limitado ao Klipper ServiceLB. + +--- + +## Estado-alvo + +- Migrar para um cluster com múltiplos nós para garantir alta disponibilidade. + +- Implementar escalonamento automático (HPA). + +- Configurar terminação TLS para habilitar tráfego HTTPS. + +--- + +## Pontos de Melhoria (Próximos passos naturais) + +| Melhoria | Por quê | +|----------|---------| +| HTTPS/TLS | Toda API em produção deve ser acessada por HTTPS | +| Autoscaler (HPA) | Escala automaticamente conforme a carga | +| Versionamento de API | /v1/orders permite evoluir sem quebrar clientes | +| Rate limiting | Evita abuso e protege o banco de sobrecargas | +| Cache (Redis) | Reduz consultas repetidas ao banco | +| Migrações de schema (Alembic) | Controle de versão das mudanças no banco | +| Testes de carga | Valida o comportamento sob alto tráfego | +| Migrar para MKS | Quando precisar de HA real: basta trocar o kubeconfig - os manifests YAML são idênticos | + +--- + +## Custo estimado na Magalu Cloud + +| Recurso | Especificação | Observação | +|---------|---------------|------------| +| VM K3s | BV2-2-40 (2 vCPU, 2 GB) | Cobrada por hora de uso | +| DBaaS PostgreSQL | Instância pequena | Cobrado por hora de uso | +| Container Registry | Por armazenamento | Baixo para imagens < 500 MB | + +*Consulte os preços atualizados em: https://magalu.cloud/precos/*