Documentação — infrastructure
Índice completo da documentação deste repo. Todo doc vive em .project/docs/, cujo primeiro nível é um
conjunto fechado de pastas. Nome de arquivo em inglês, conteúdo em português.
Este repo não tem features/, plans/, reference/ nem rules/ — não há user story, regra de negócio
em Given/When/Then nem plano de implementação separado das specs.
Guides
How-to operacional: setup, acesso, secrets.
| Doc | Sobre | Certainty |
|---|---|---|
| getting_started.md | Instalar as ferramentas, obter a chave do ward e aplicar as camadas na ordem | medium |
| access.md | Como conseguir e usar acesso ao cluster, e o que o config/access.yml controla |
medium |
| ward_vault.md | Inventário dos vaults de secret e como adicionar/editar chave | medium |
| github_organization_secrets.md | Secrets e variáveis de organização no GitHub geridos pelo stack src/shared/github |
medium |
Architecture
Decisões arquiteturais e suas consequências.
| Doc | Sobre | Certainty |
|---|---|---|
| abstraction.md | Orquestrador + engines: trocar runtime ou provider mudando uma variável, nunca código | high |
Learnings
Aprendizados retrospectivos — pegadinhas já pagas.
| Doc | Sobre | Certainty |
|---|---|---|
| infra_eks_node_group_nao_escala_sozinho.md | Managed node group do EKS não escala sem Cluster Autoscaler ou Karpenter; tag de autodescoberta tem que estar no ASG | high |
| infra_eks_gaps_primeira_migracao_app.md | O que o EKS não entrega por default: EBS CSI, storage class, pull de registry privado, capacidade de pool | high |
| infra_amazon_mq_rabbitmq_cluster.md | Amazon MQ para RabbitMQ em cluster: tipo de instância mínimo, uma subnet, AMQPS 5671 + management 443 | high |
| infra_github_token_admin_org.md | O stack shared/github exige PAT com admin:org; write:org não basta |
high |
Specs
Mudanças planejadas ou executadas, em ordem cronológica. status no frontmatter de cada uma.
| Doc | Sobre | Status | Certainty |
|---|---|---|---|
| 20260304134424_stateful_stateless_reorganization.md | State isolado por serviço, separando recurso com dado de recurso de computação | done | medium |
| 20260310081624_gateway_kubernetes_deployment.md | Gateway no Kubernetes, com namespaces/DNS por Terraform e deploy por Actions + Kustomize | superseded | medium |
| 20260310100110_platform_container_registry_github_secrets.md | Registry como componente de plataforma e secrets de infraestrutura do GitHub por Terraform | superseded | medium |
| 20260314222420_remove_gateway_terraform.md | Terraform do gateway sai deste repo e vai para o repo do gateway | done | high |
| 20260416163719_k8s_rbac_developer_profiles.md | Três perfis de acesso ao cluster (dev, <project>-head, infra) com namespaces dinâmicos |
done | high |
| 20260418121333_centralized_owners_config.md | Um único arquivo de acesso dirigindo RBAC, reviewers de ambiente e console | done | high |
| 20260420013426_infra_restructure.md | Realinhamento da estrutura do repo com o padrão da organização e CI para os stacks de plataforma | done | high |
| 20260420121730_per_project_k8s_rbac.md | ServiceAccounts por projeto com members/owners, e CODEOWNERS gerado |
done | high |
| 20260425143824_migrate_secrets_to_ward.md | Trocar SOPS+age e .env em texto puro pelo ward |
done | high |
| 20260604103000_migrate_shared_k8s_to_eks.md | Cluster compartilhado para EKS, com VPC compartilhada via RAM e ECR | done | high |
| 20260629082325_abstract_kubernetes_provider.md | Extrair o Kubernetes para módulo com provider_type, tornando a migração uma troca de variável |
done | high |
| 20260701144731_migrate_messagebroker_to_amazon_mq.md | Messagebroker compartilhado no Amazon MQ (RabbitMQ, cluster HA) | done | high |
| 20260706113811_add_cluster_autoscaler_eks.md | Cluster Autoscaler com IRSA/OIDC, deixando o caminho aberto para Karpenter | done | high |
| 20260706211540_ci_validate_bootstrap.md | fmt/validate estático em src/bootstrap/** no PR — sem apply, por decisão |
done | high |
| 20260706231511_messagebroker_remove_digitalocean.md | Amazon MQ promovido a canônico; droplet e código legado removidos | done | high |
| 20260706235144_migrate_infrastructure_to_ward.md | Os três últimos stacks para ward; SOPS removido do repo | done | high |
| 20260709164019_platform_registry_to_ecr.md | ECR na conta shared como registry da organização; EKS puxa sem pull secret | done | high |
| 20260710154001_build_pipeline_push_to_ecr.md | package.yml/ship.yml empurrando para o ECR em vez do registry antigo |
done | high |
| 20260710154002_decommission_doks_and_droplets.md | Destruir o cluster legado e remover o stack — ponto sem volta do rollback do gateway | proposed | high |
| 20260710154003_decommission_docr_platform_registry.md | Remover o registry legado e o stack platform/registry |
proposed | high |
| 20260710154004_migrate_tf_state_backend_to_s3.md | Backend de state para S3 nativo — o maior raio de impacto da descontinuação | in_progress | high |
| 20260710154006_link_session_prs_to_asana.md | Vincular os PRs da migração a subtarefas no Asana | proposed | high |
| 20260717223325_eks_iam_developer_access.md | IAM roles + EKS Access Entries: token de 15 min, revogação imediata, contexto único por dev | done | high |
Onde cada tipo de doc vai
| Se o doc… | Vai para |
|---|---|
| descreve uma mudança, planejada ou executada | specs/ |
| é o passo-a-passo de implementação de uma spec | plans/ |
| é aprendizado retrospectivo de bug ou decisão | learnings/ |
| registra decisão arquitetural e consequência | architecture/ |
| ensina a executar algo (setup, deploy, acesso, debug) | guides/ |
| descreve como o sistema é (fluxo, API, contrato) | reference/<scope>/ |
| é instrução para agente de IA | não é doc — CLAUDE.md ou .project/ai/rules/ |
O primeiro nível é um conjunto fechado: specs, plans, features, learnings, architecture,
guides, reference, rules. Nunca crie pasta com outro nome aqui.