Biblioteca de Módulos Terraform AWS

Biblioteca de módulos Terraform reutilizáveis para provisionamento de infraestrutura AWS. Framework interno com padrões e convenções específicas da empresa.

📋 Visão Geral

O projeto contém 95 módulos organizados em duas categorias principais:

• Módulos de recursos (terraform-aws-*): Provisionam recursos AWS (ECS, RDS, Lambda, etc.)
• Módulos de data sources (terraform-aws-data-*): Consultam recursos existentes (VPC, IAM roles, certificados, etc.)

Arquitetura em Camadas

Usuário
  ↓
Módulos de Alto Nível (modules/workloads/, modules/networking/, modules/security/)
  ↓
Módulos Base (stacks/aws/terraform-aws-*)
  ↓
Recursos AWS

🎯 Objetivo

Padronizar e simplificar o provisionamento de infraestrutura AWS através de módulos reutilizáveis que seguem convenções consistentes de nomenclatura, validação e documentação.

⚠️ Uso Obrigatório

DevOps devem SEMPRE usar os módulos desta biblioteca para seguir o padrão da empresa. O uso de recursos Terraform diretos (resources) só é permitido em casos muito específicos e excepcionais.

📊 Conformidade

• 87.5% de conformidade com convenções estabelecidas
• 26 módulos transformados e validados (fevereiro 2026)
• 16/16 testes de integração passando (100%)

🏗️ Estrutura do Projeto

.
├── modules/                # Módulos de alto nível (interface do usuário)
│   ├── workloads/          # Recursos de aplicação AWS (18 módulos)
│   ├── networking/         # Recursos de rede AWS (16 módulos)
│   ├── security/           # Recursos de segurança AWS (7 módulos)
│   └── workloads-azure/    # Recursos Azure DevOps (5 módulos)
├── stacks/                 # Módulos base (implementação)
│   ├── aws/                # Módulos base Terraform AWS (56 módulos)
│   ├── azure-devops/       # Módulos base Azure DevOps
│   └── datadog/            # Módulos para monitoramento Datadog
├── docs-infra/             # Infraestrutura do site de documentação (CloudFront + S3)
├── tests/                  # Testes de integração
├── pipelines/              # Pipelines CI/CD
└── .kiro/                  # Configurações e specs

Módulos de Alto Nível

workloads/ - Aplicações (18 módulos)

Interface principal para provisionamento de recursos de aplicação:

• account, api, certificates, ec2, ecs, ecs-cluster
• elasticache, kinesis, lambda, queue, rds, repositories
• s3bucket, sns-subscription, sns-topic
• task-cron, web

networking/ - Rede (16 módulos)

Interface principal para provisionamento de recursos de rede:

• ipam-allocation-onpremises, ipam-pool, ipam-pool-workloads, ipam-share
• loadbalance, route-53, route-53-zone, tgw-attachment-workloads
• vpc, vpc-share, vpc-share-tags, vpc-share-tags-shared-products
• vpc-share-workloads, vpc-workloads, vpc-workloads-shared-products
• vpn-site-to-site

security/ - Segurança (7 módulos)

Interface principal para provisionamento de recursos de segurança:

• iam, kms, role, securitygroup, ssm
• sso-group-permission, sso-user

Módulos Base (aws/)

57 módulos organizados por categoria:

• Compute (7): ec2, ecs, ecs-autoscalling, ecs-cluster, ecs-start-stop, lambda, state-machine
• Rede (12): api, certificates, loadbalance, vpc, vpc-share, vpn-site-to-site, etc.
• IPAM (4): ipam-allocation-onpremises, ipam-pool, ipam-pool-workloads, ipam-share
• Armazenamento (3): elasticache, rds, s3bucket
• Segurança (9): group, iam, iam-role, kms, securitygroup, ssm, sso-group, sso-permissionset, sso-user
• Mensageria (4): kinesis, queues, snssubscription, snstopic
• Gestão (7): account, organization-unit, repositories, route53, route53-zone, task-cron, web
• Data Sources (10): data-accountid, data-certificates, data-ecs-cluster, data-global-variables, data-kms, data-lb, data-repository, data-role, data-route53, data-vpc

🚀 Como Usar

Exemplo: Criar Serviço ECS

# Use o módulo de alto nível
module "my_api" {
  source = "../../../modules/workloads/ecs"

  ProductName = "MyProduct"
  AppName     = "API"
  VpcName     = "production-vpc"
  ClusterName = "production-cluster"

  Cpu    = 256
  Memory = 512
  Port   = 8080

  ContainerDefinitions = jsonencode([{
    name      = "api"
    image     = "123456789012.dkr.ecr.us-east-1.amazonaws.com/my-api:latest"
    cpu       = 256
    memory    = 512
    essential = true
    portMappings = [{
      containerPort = 8080
      hostPort      = 8080
      protocol      = "tcp"
    }]
  }])
}

Estrutura de um Módulo

Módulo de Alto Nível

modules/workloads/ecs/
├── main.tf          # Chama o módulo base
├── variables.tf     # Inputs do módulo
├── outputs.tf       # Valores exportados
├── providers.tf     # Configuração de providers
├── module_test.tftest.hcl  # Teste unitário
└── README.md        # Documentação

Módulo Base

stacks/aws/terraform-aws-ecs/
├── main.tf          # Recursos principais e locals
├── variables.tf     # Inputs do módulo
├── outputs.tf       # Valores exportados
├── README.md        # Documentação completa
└── json/            # Templates JSON (opcional)

📝 Convenções de Nomenclatura

Código Terraform

• Variáveis (interface pública): PascalCase

• Exemplos: ProductName, Environment, AppName

• Locals (implementação interna): snake_case

• Exemplos: service_name, cluster_name, resource_label

• Outputs (valores exportados): snake_case

• Exemplos: service_id, endpoint_url, security_group_id

• Recursos: snake_case com prefixos descritivos

• Exemplos: aws_ecs_service.service, aws_iam_role.execution_role

Módulos

• Módulos de alto nível: Nome descritivo simples (ecs, lambda, vpc)
• Módulos base de recursos: terraform-aws-<recurso> (terraform-aws-ecs)
• Módulos base de data sources: terraform-aws-data-<recurso> (terraform-aws-data-vpc)

Arquivos

• main.tf, variables.tf, outputs.tf: Sempre em minúsculas
• README.md: Sempre em maiúsculas

🔒 Segurança

Regras Críticas

• ❌ NUNCA inclua credenciais, secrets ou tokens no código
• ✅ Use AWS KMS para criptografar dados sensíveis
• ✅ Implemente least privilege em todas as políticas IAM
• ✅ Valide inputs de variáveis para prevenir injeção
• ✅ Use sensitive = true em outputs sensíveis

Exemplo

variable "DatabasePassword" {
  type        = string
  description = "Senha do banco de dados"
  sensitive   = true
}

output "db_endpoint" {
  value     = aws_db_instance.main.endpoint
  sensitive = false
}

✅ Workflow de Modificação

Antes de Modificar

1. Leia o README.md do módulo alvo
2. Identifique impacto das mudanças em módulos dependentes

Durante Modificação

1. Siga a estrutura dos módulos existentes
2. Mantenha consistência de nomenclatura
3. Atualize README.md simultaneamente com código
4. Adicione validações em variáveis quando aplicável

Antes de Finalizar

# 1. Formatar código
terraform fmt -recursive

# 2. Validar módulo
terraform init
terraform validate

# 3. Executar testes (se aplicável)
cd modules/workloads/<modulo>
terraform test

Checklist de Qualidade

• [ ] Código formatado com terraform fmt
• [ ] Validação passou com terraform validate
• [ ] Variáveis têm tipos explícitos
• [ ] Variáveis têm descrições em português
• [ ] Validações adicionadas quando aplicável
• [ ] README.md atualizado
• [ ] Comentários em português para lógica complexa
• [ ] Nenhuma credencial hardcoded
• [ ] Outputs sensíveis marcados com sensitive = true
• [ ] Consistência com padrões existentes

🧪 Testes

Sistema de Testes de Integração

O projeto possui testes automatizados que validam a integração entre módulos de alto nível e módulos base.

Status Atual: - ✅ 16/16 testes passando (100%) - 📊 88.9% de cobertura (16/18 módulos testáveis) - 🎯 Arquitetura de testes individuais

Executar Testes

# Teste individual de um módulo
cd modules/workloads/ecs
terraform test

# Todos os testes (Linux/Mac)
cd tests/integration/workloads
./run_all_tests.sh

# Todos os testes (Windows)
cd tests\integration\workloads
.\run_all_tests.ps1

Documentação de Testes

• Geral: tests/integration/README.md
• Workloads: tests/integration/workloads/README.md
• Changelog: tests/integration/CHANGELOG.md
• Spec: .kiro/specs/module-integration-validation-test/

📚 Documentação

Arquivos de Steering

Regras e convenções do projeto (.kiro/steering/):

• product.md - Visão geral do produto
• structure.md - Estrutura do projeto
• code-standards.md - Padrões de código e segurança
• workflow.md - Workflow de modificação

README.md Obrigatório

Cada módulo deve documentar:

1. Descrição: Propósito e funcionalidade
2. Requisitos: Versão do Terraform, providers, dependências
3. Exemplo de Uso: Código funcional demonstrando uso típico
4. Inputs: Tabela com todas as variáveis
5. Outputs: Tabela com todos os outputs
6. Recursos Criados: Lista dos recursos AWS provisionados

🎓 Prioridades de Desenvolvimento

1. Segurança - Sempre em primeiro lugar
2. Consistência - Siga padrões existentes entre módulos
3. Documentação - README completo e atualizado
4. Manutenibilidade - Código limpo e modular
5. Reutilização - DRY (Don't Repeat Yourself)

🌍 Idioma

• Respostas e documentação: Português brasileiro
• Código Terraform: Inglês (padrão da ferramenta)
• Comentários: Português para lógica complexa

🔗 Links Úteis

• Terraform Documentation
• AWS Provider Documentation
• Terraform Test Framework

📞 Suporte

Para dúvidas ou problemas:

1. Consulte a documentação do módulo específico (README.md)
2. Verifique os arquivos de steering em .kiro/steering/
3. Revise os testes de integração em tests/integration/
4. Entre em contato com a equipe de DevOps

---

Última atualização: Fevereiro 2026