DevOpsQuest
0 XP
Módulo 11 · DevSecOps, FinOps e Projeto Final

Documentação, ADRs e o projeto que fecha entrevista

Intermediário 45 min+25 XPMarkdownADRDiagramas

Objetivos desta aula

  • Escrever README que sustenta uma conversa técnica
  • Registrar decisões com ADR
  • Preparar a narrativa da entrevista

Projeto sem documentação não conta como experiência, porque ninguém consegue avaliar. O README precisa responder em dois minutos: o que é, qual a arquitetura, como rodar, como implantar, como observar, como reverter, quanto custa e quais decisões foram tomadas — com o porquê.

ADR (Architecture Decision Record) é um documento curto por decisão: contexto, opções consideradas, escolha e consequências. Ele demonstra exatamente o que entrevista técnica procura: capacidade de comparar alternativas e assumir trade-off consciente.

Para a entrevista, prepare três histórias de dois minutos: um incidente que você diagnosticou (com evidência), uma automação que reduziu tempo ou risco (com número) e uma decisão de arquitetura com trade-off. Com o CloudShop, você tem material real para as três.

1. O README que recrutador lê

Em 30 segundos: o que é, diagrama de arquitetura, como rodar em um comando, decisões principais e resultados (tempo de deploy, SLO, custo).

2. ADR: decisões registradas

Um Architecture Decision Record curto: contexto, decisão, alternativas consideradas e consequências. Em entrevista, mostrar que você escolheu ArgoCD em vez de Flux e por quê vale mais que usar ambos.

3. Runbooks

Para cada alerta: o que significa, como confirmar, como mitigar e quem escalar. Um runbook bom permite que alguém novo resolva o incidente.

4. Diagramas como código

Mermaid ou diagrams.net versionados no repo mantêm a documentação viva junto ao código.

Na prática

Estrutura do README do CloudShop

markdown

# CloudShop Platform

Catalogo e pedidos de produtos 3D. Projeto de engenharia de plataforma end-to-end.

## Arquitetura
Vue (S3 + CloudFront) -> ALB/Ingress -> API Node (Kubernetes) -> PostgreSQL (RDS)
Observabilidade: Prometheus, Grafana, Loki, OpenTelemetry. Entrega: GitHub Actions + ArgoCD.

## Como rodar localmente
docker compose up -d      # http://localhost:8080

## Como implantar
Merge na main -> CI (lint, testes, build, scans) -> imagem no GHCR ->
PR automatico no cloudshop-gitops -> ArgoCD sincroniza staging.
Producao: PR de promocao com aprovacao.

## Observabilidade
- Dashboard: grafana/cloudshop-overview
- SLO: 99,9% disponibilidade / 95% abaixo de 500ms (janela 30 dias)
- Runbooks: docs/runbooks/

## Rollback
git revert do commit de versao no repositorio GitOps (RTO medido: 4 minutos).

## Custo
Ambiente de estudo: ~18 USD/mes. Otimizacoes aplicadas: desligamento noturno de dev,
right-sizing do RDS, VPC endpoint para S3 (reduziu NAT).

## Decisoes (ADRs)
- ADR-001: Kubernetes em vez de ECS — motivo e consequencias
- ADR-002: GitOps com ArgoCD em vez de deploy por pipeline push
- ADR-003: RDS em vez de PostgreSQL autogerenciado

Modelo de ADR

markdown

# ADR-002: GitOps com ArgoCD em vez de deploy push pelo pipeline

- **Status:** aceito (2026-09-20)
- **Contexto:** precisamos de rastreabilidade do que roda em cada ambiente e rollback rapido,
  com apenas uma pessoa operando a plataforma.
- **Opcoes:**
  1. Pipeline push com kubectl/helm — simples, porem estado do cluster nao e auditavel no Git.
  2. ArgoCD com repositorio de manifests — reconciliacao continua e rollback por revert.
- **Decisao:** opcao 2.
- **Consequencias:** mais um componente para operar e curva de aprendizado;
  em troca, drift detectado automaticamente, historico de deploy no Git e rollback em minutos.
- **Revisao:** reavaliar se o time crescer acima de 15 pessoas ou se surgir necessidade multi-cluster.

Modelo de ADR

markdown

# ADR-004: GitOps com ArgoCD
Data: 2026-03-10  |  Status: aceito
## Contexto
Deploys via kubectl no CI exigiam credencial de admin do cluster.
## Decisão
Adotar ArgoCD em modelo pull com repositório cloudshop-gitops.
## Alternativas
Flux (menos interface visual), push via Helm no CI (credencial exposta).
## Consequências
+ auditoria e rollback por Git  - mais um componente para operar

Por que isso importa

Na entrevista, quem documenta consegue provar; quem não documenta precisa que acreditem.

Erro comum

README com apenas instruções de instalação, sem arquitetura, decisões nem custo.

Dica de produção

Escreva o ADR no momento da decisão: reconstruir o raciocínio depois nunca sai igual.

Pergunta de entrevista

Conte uma decisão de arquitetura sua, as alternativas e o trade-off assumido.

Glossário

ADR
Registro curto de uma decisão de arquitetura, com contexto e consequências.
RTO
Recovery Time Objective: tempo alvo para restaurar o serviço.
ADR
Documento curto que registra uma decisão de arquitetura e seu porquê.
Runbook
Procedimento passo a passo para responder a um alerta ou tarefa.

Conexão com o CloudShop

Escrever o README final e os três ADRs principais do CloudShop.

Quiz da aula

  1. 1. O que um ADR registra?

  2. 2. O que um ADR deve conter além da decisão?

Minhas anotações

Salvo automaticamente neste navegador.

AnteriorPróxima