<PROJECT_NAME> Infrastructure

Repositorio de infraestrutura como codigo (IaC) do projeto <PROJECT_NAME>, gerenciado com Terragrunt/OpenTofu para provisionamento de cloud e manifests Kubernetes para orquestracao do cluster (via ArgoCD).

Template: este repositorio e um template generico. Antes de usar, substitua os placeholders descritos abaixo pelos valores do seu projeto.

Placeholders

Todos os valores especificos do projeto sao representados por tokens no formato <UPPER_SNAKE> — o mesmo padrao ja usado nos manifests do cluster/ (ex: <DOMAIN>). Para encontrar tudo que precisa ser preenchido:

grep -rn '<[A-Z_]\+>' .

Token	Substitui	Exemplo
<PROJECT_NAME>	Slug do projeto. Usado em buckets, locks, profiles e no cluster	acme
<ORG_NAME>	Organizacao responsavel (tag ManagedBy)	platform-team
<DOMAIN>	Zona DNS gerenciada no Cloudflare (tambem nome de diretorio)	example.com
<AWS_REGION>	Regiao AWS	us-east-1
<ENV>	Ambiente / conta	production
<AWS_ACCOUNT_ID>	ID da conta AWS	000000000000
<TRUSTED_AWS_ACCOUNT_ID>	ID de conta AWS externa confiavel (assume-role de terceiros)	111111111111
<CLOUDFLARE_ACCOUNT_ID>	ID da conta Cloudflare	0123...
<EKS_OIDC_ID>	ID do provider OIDC do cluster EKS (IRSA)	ABCDEF0123...
<KMS_KEY_ID>	ID da chave KMS	0fbd...

Secrets: <CLOUDFLARE_TUNNEL_SECRET> (em secrets.tfvars) e <TURBOT_PIPES_EXTERNAL_ID> sao segredos. Nao versione valores reais — injete via variavel de ambiente, *.auto.tfvars ignorado pelo git, ou um secrets manager.

Exemplo de substituicao em massa (revise antes de aplicar):

grep -rl '<PROJECT_NAME>' . | xargs sed -i 's/<PROJECT_NAME>/acme/g'

Estrutura do Repositorio

.
├── cluster/       # Manifests Kubernetes orquestrados por ArgoCD (Helm charts, Applications, configs)
└── providers/     # Infraestrutura cloud gerenciada via Terragrunt/OpenTofu

---

Diretorio cluster/

O diretorio cluster/ contem todos os manifests Kubernetes que descrevem o estado desejado do cluster. O deploy segue o padrao App-of-Apps do ArgoCD: o ArgoCD e instalado via bootstrap e, a partir dele, gerencia continuamente todas as demais cargas de trabalho de forma declarativa (GitOps).

As pastas usam um prefixo numerico que define a ordem logica de provisionamento — das fundacoes do cluster (00_core) ate as aplicacoes finais (70_services).

Hierarquia de diretorios

cluster/
├── 00_core/                        # Fundacao do cluster (instalado antes de tudo)
│   ├── argocd/
│   │   ├── _bootstrap/             # Instalacao inicial do ArgoCD (argocd + oauth GitHub + notifications)
│   │   ├── clusters/               # Registro de clusters gerenciados
│   │   ├── projects/               # AppProjects (system, network, storage, monitoring, operations)
│   │   ├── registries/             # Registries de container
│   │   └── repositories/           # Repositorios Git/Helm conhecidos pelo ArgoCD
│   ├── cilium/
│   │   └── bootstrap.yaml          # CNI Cilium (rede do cluster + Gateway API)
│   └── namespaces.yaml             # Namespaces base
├── 10_plataform/                   # Plataforma / capacidades transversais
│   ├── cert-manager/               # Emissao de certificados TLS (+ ClusterIssuer)
│   ├── external-secrets/           # External Secrets Operator (ESO) + auth Vault
│   ├── reloader/                   # Recarga automatica de pods em mudanca de secret/configmap
│   └── velero/                     # Backup e restore do cluster
├── 20_networking/                  # Rede de entrada (Gateway API)
│   ├── gateway-classes/            # GatewayClasses (ex: internal)
│   └── gateways/                   # Gateways (internal, public)
├── 30_security/                    # Seguranca (reservado)
├── 40_datastores/                  # Bancos de dados e datastores (reservado)
├── 50_infra-services/              # Servicos de infraestrutura (reservado)
├── 60_observability/               # Observabilidade
│   ├── alloy/                      # Grafana Alloy (coleta de telemetria)
│   ├── loki/                       # Loki (logs)
│   └── prometheus/                 # Prometheus (metricas + alerting rules)
└── 70_services/                    # Aplicacoes de negocio (reservado)

Como funciona

• Bootstrap inicial: Cilium (CNI) e ArgoCD sao instalados primeiro. A partir dai o ArgoCD assume o controle (GitOps).
• Applications: cada componente em 10_plataform/, 20_networking/ e 60_observability/ e um kind: Application do ArgoCD que aponta para um chart Helm (ex: cert-manager, prometheus) e seus valores.
• AppProjects: em 00_core/argocd/projects/ definem fronteiras de seguranca (repos permitidos, destinos e tipos de recurso) por dominio: system, network, storage, monitoring, operations.
• Placeholders: valores como <DOMAIN> nos manifests sao substituidos no momento do deploy conforme o ambiente.
• Pastas .gitkeep: diretorios reservados (30_security, 40_datastores, 50_infra-services, 70_services) ainda nao possuem cargas e existem para fixar a estrutura.

---

Diretorio providers/

O diretorio providers/ contem toda a infraestrutura cloud gerenciada via Terragrunt com OpenTofu como backend. A estrutura segue uma hierarquia que reflete a organizacao dos cloud providers, contas, regioes e recursos.

Hierarquia de diretorios

providers/
├── state-location.hcl                          # Configuracao global de localizacao do state
├── aws/
│   ├── root.hcl                                # Config raiz AWS (provider, remote state S3, inputs globais)
│   └── <ENV>/
│       ├── account.hcl                         # Variaveis da conta (account_name, aws_account_id)
│       ├── _global/
│       │   └── networking/dns/                 # Recursos globais (nao regionais)
│       └── <AWS_REGION>/
│           ├── region.hcl                      # Variaveis da regiao (aws_region)
│           ├── compute/
│           │   └── EKS/                        # Cluster EKS
│           ├── middleware/
│           │   └── sqs/                        # Filas SQS (ex: karpenter-interruption-queue)
│           ├── networking/
│           │   ├── VPC/                        # Virtual Private Cloud
│           │   └── loadbalancer/               # Load Balancer
│           ├── security/
│           │   ├── IAM/policies/               # Policies (external-secrets, karpenter-controller)
│           │   ├── IAM/roles/                  # Roles (efs-csi-controller, external-secrets, karpenter-*, turbot-pipes)
│           │   └── irsa/                       # IAM Roles for Service Accounts (aws-load-balancer-controller, external-secrets)
│           └── storage/
│               └── efs/                        # Elastic File System
└── cloudflare/
    ├── root.hcl                                # Config raiz Cloudflare (provider, remote state S3)
    └── <DOMAIN>/
        ├── account.hcl                         # Variaveis da conta Cloudflare
        ├── dns/                                # Registros DNS da zona <DOMAIN>
        └── zero-trust/
            └── tunnel/                         # Cloudflare Tunnel (Zero Trust)

Como funciona

Arquivos de configuracao hierarquica

O Terragrunt utiliza um sistema de heranca onde cada nivel da hierarquia contribui com variaveis e configuracoes:

Arquivo	Funcao
root.hcl	Configuracao raiz por provider. Define o provider Terraform, backend de remote state (S3 + DynamoDB) e inputs globais
account.hcl	Variaveis no nivel de conta (nome da conta, ID da conta)
region.hcl	Variaveis no nivel de regiao (ex: <AWS_REGION>)
state-location.hcl	Configuracao compartilhada de localizacao do state entre providers
terragrunt.hcl	Configuracao do modulo leaf (fonte do modulo Terraform, dependencias, inputs)

Cada modulo leaf (terragrunt.hcl) herda automaticamente as configuracoes dos arquivos pai atraves de find_in_parent_folders().

Remote State

Todos os states sao armazenados em um bucket S3 (<PROJECT_NAME>-tfstate) com lock via DynamoDB (<PROJECT_NAME>-tf-locks). A chave do state segue o padrao:

• AWS: aws/<path_relativo>/tf.tfstate
• Cloudflare: cloudflare/<path_relativo>/tf.tfstate

Dependencias entre modulos

Os modulos utilizam dependency blocks do Terragrunt para referenciar outputs de outros modulos. Exemplo: o EKS depende da VPC, o DNS do Cloudflare depende do Load Balancer AWS.

Adicionando um novo recurso

1. Crie um diretorio na categoria apropriada (compute, networking, security, storage, middleware)
2. Crie um terragrunt.hcl com:
   • include apontando para o root.hcl do provider
   • terraform.source apontando para o modulo Terraform/OpenTofu
   • dependency blocks para recursos que o novo modulo precisa referenciar
   • inputs com as variaveis do modulo
3. Execute terragrunt plan para validar e terragrunt apply para provisionar

Comandos uteis

# Navegar ate o modulo desejado
cd providers/aws/<ENV>/<AWS_REGION>/compute/EKS

# Planejar alteracoes
terragrunt plan

# Aplicar alteracoes
terragrunt apply

# Planejar todos os modulos de uma vez (a partir de qualquer nivel)
terragrunt run-all plan

# Ver o grafo de dependencias
terragrunt graph-dependencies