Midaz Terraform Foundation

O Midaz Terraform Foundation é um repositório de exemplos prontos de Terraform. Use-os para criar a infraestrutura base que o Midaz precisa na AWS, GCP ou Azure. Os exemplos seguem as melhores práticas de cada provedor de nuvem. Essa infraestrutura base inclui:

Rede (VPC, subnets)
DNS
Banco de dados
Redis/Valkey
Cluster Kubernetes (EKS, GKE ou AKS)

Os templates provisionam um banco de dados compatível com MongoDB e um broker de mensagens apenas em alguns provedores. A AWS usa o Amazon DocumentDB e o Amazon MQ (RabbitMQ). O Azure usa o Cosmos DB com a API do MongoDB. O GCP não tem um equivalente gerenciado, então você precisa provisionar o MongoDB e o RabbitMQ por conta própria no GCP.

Por que usar

O provisionamento de infraestrutura não deveria ser lento, inconsistente ou propenso a erros. O midaz-terraform-foundation segue as melhores práticas da Lerian para segurança, observabilidade e escalabilidade. As tabelas abaixo o comparam com uma configuração manual ou ad-hoc.

Velocidade e padronização

Critério	Com Midaz Terraform	Configuração manual / Scripts ad-hoc
Velocidade de setup	Rápido – provisiona tudo em minutos com um único `apply`.	Lento – leva dias para configurar e testar.
Padrão de arquitetura	Padronizado – segue as melhores práticas da Lerian.	Imprevisível – pode ser inconsistente.
Reusabilidade	Alta – suporta múltiplos ambientes com alterações mínimas.	Baixa – difícil de reutilizar entre projetos.

Segurança e observabilidade

Critério	Com Midaz Terraform	Configuração manual / Scripts ad-hoc
Segurança por padrão	Sim – seguro por design (VPCs isoladas, IAM, secrets, etc.).	Não – depende da equipe, aumentando o risco de exposição.
Observabilidade integrada	Integrada – integra com Prometheus, Grafana e mais.	Manual – requer configuração separada, frequentemente ignorada.
Pronto para produção?	Sim – alta disponibilidade e autoscaling prontos para uso.	Incerto – precisa de esforço extra para fortalecer.

Manutenção e suporte

Critério	Com Midaz Terraform	Configuração manual / Scripts ad-hoc
Manutenibilidade	Fácil – modular e versionado para atualizações sem dor.	Difícil – scripts quebram facilmente.
Suporte Lerian	Incluído – verificado e suportado pela Lerian.	Nenhum – não garantido.
Tempo estimado de implantação	1 dia – incluindo validação.	1–2 semanas – com maior risco operacional.

Use este repositório para uma configuração mais rápida e testada.O midaz-terraform-foundation segue os padrões de engenharia da Lerian. Ele ajuda você a implantar mais rápido e evitar erros comuns de configuração.

O que você vai precisar

Antes de começar, certifique-se de ter:

Terraform v1.5.0 ou superior — os exemplos de AWS RDS e Route 53 exigem >= 1.5.0; os outros módulos exigem >= 1.0.0
Uma conta em um provedor de nuvem (AWS, GCP ou Azure).
Um bucket de armazenamento para os arquivos de estado do Terraform.
A ferramenta CLI do seu provedor de nuvem:
- aws para AWS
- gcloud para GCP
- az para Azure

Integração CI/CD

Este repositório fornece exemplos de Terraform para implantar infraestrutura base. Ele não inclui um pipeline de CI/CD. Crie um que atenda às necessidades do seu projeto. Você já executa um pipeline de CI/CD com Terraform? Siga estes passos:

Pule o script de deploy. Ele é apenas para uso local.

Copie as configurações de exemplo relevantes para o seu repositório privado de Infrastructure as Code.

Integre as configurações do Terraform ao seu pipeline conforme necessário.

Use o gerenciamento de secrets integrado da sua plataforma de CI/CD para lidar com credenciais de forma segura.

Estrutura do projeto

Cada provedor de nuvem tem sua própria estrutura no repositório. Cada componente da infraestrutura segue um layout modular e controlado. Você pode implantar apenas os componentes que precisa, ou toda a fundação.

.
├── examples/
    ├── aws/
    │   ├── vpc/
    │   ├── route53/
    │   ├── rds/
    │   ├── documentdb/
    │   ├── amazonmq/
    │   ├── valkey/
    │   └── eks/
    ├── gcp/
    │   ├── vpc/
    │   ├── cloud-dns/
    │   ├── cloud-sql/
    │   ├── valkey/
    │   └── gke/
    └── azure/
        ├── network/
        ├── dns/
        ├── database/
        ├── cosmosdb/
        ├── redis/
        └── aks/

A ordem de implantação importa

Para evitar erros e conectar tudo corretamente, implante os componentes nesta ordem:

VPC / Network
DNS
Banco de dados
Redis/Valkey
Cluster Kubernetes

Criando o armazenamento de estado

O Terraform requer um backend remoto para gerenciar seu estado. Antes de usar esses templates, crie um bucket de armazenamento para os arquivos de estado do Terraform.

AWS

Substitua REGION e UNIQUE_BUCKET_NAME pelos seus próprios valores.

Crie um bucket S3

 aws s3api create-bucket \
    --bucket UNIQUE_BUCKET_NAME \
    --region REGION \
    --create-bucket-configuration LocationConstraint=REGION

Habilite o versionamento

aws s3api put-bucket-versioning \
    --bucket UNIQUE_BUCKET_NAME \
    --versioning-configuration Status=Enabled

Habilite a criptografia

aws s3api put-bucket-encryption \
    --bucket UNIQUE_BUCKET_NAME \
    --server-side-encryption-configuration \
    '{"Rules":[{"ApplyServerSideEncryptionByDefault":{"SSEAlgorithm":"AES256"}}]}'

Bloqueie o acesso público

aws s3api put-public-access-block \
    --bucket UNIQUE_BUCKET_NAME \
    --public-access-block-configuration \    '{"BlockPublicAcls":true,"IgnorePublicAcls":true,"BlockPublicPolicy":true,"RestrictPublicBuckets":true}'

Google Cloud Platform

Crie um bucket GCS

gsutil mb -l us-central1 gs://your-terraform-state-bucket

Habilite o versionamento

gsutil versioning set on gs://your-terraform-state-bucket

Azure

Crie um resource group

az group create --name terraform-state-rg --location eastus

Crie uma storage account

az storage account create --name tfstate$RANDOM --resource-group terraform-state-rg --sku Standard_LRS

Crie um container

az storage container create --name terraform-state --account-name <storage-account-name>

Requisitos de configuração

Antes de implantar a infraestrutura, crie e configure o arquivo de variáveis para cada componente de nuvem:

Copie o arquivo de exemplo

cd examples/<provider>/<component>
cp midaz.tfvars-example midaz.tfvars

Substitua todos os placeholders no arquivo midaz.tfvars pelos seus valores reais. \i. Este arquivo contém a configuração principal para o setup da sua infraestrutura.

Credenciais de produção e implantação

Em ambientes de produção, você precisa gerenciar as credenciais com cuidado. Este guia mostra como lidar com as credenciais de forma segura.

Autenticação no provedor de nuvem

Quando você executa o script de deploy localmente, use as ferramentas de autenticação CLI do provedor de nuvem em vez de credenciais brutas. Este método é mais seguro. Ele gerencia a rotação de credenciais, MFA e refresh de tokens automaticamente. Por que adotar essa abordagem?

Tokens são atualizados automaticamente.
Integração com MFA e SSO pronta para uso.
Rotaciona e armazena as credenciais de forma segura.
Trilha de auditoria completa para eventos de autenticação.

AWS

Use a AWS CLI para assumir uma role.

aws sso login --profile your-profile

aws sts assume-role --role-arn arn:aws:iam::ACCOUNT_ID:role/ROLE_NAME --role-session-name terraform

GCP

Use a autenticação do gcloud.

gcloud auth application-default login

Para service accounts, use o seguinte comando:

gcloud auth activate-service-account --key-file=path/to/service-account.json

Azure

Use a Azure CLI.

az login

Para service principals, use o seguinte comando:

az login --service-principal

Boas práticas de gerenciamento de credenciais

Mantenha-se seguro e em conformidade seguindo as orientações oficiais do seu provedor de nuvem:

AWS: Gerenciando chaves de acesso AWS.
GCP: Gerenciando chaves de service account.
Azure: Boas práticas de gerenciamento de identidade.

Práticas recomendadas

Rotacione credenciais em um cronograma regular.
Use controle de acesso baseado em roles (RBAC) sempre que possível.
Exija MFA para contas de usuário.
Prefira credenciais temporárias e de curta duração.
Monitore e audite o uso das credenciais.
Nunca faça commit de credenciais no controle de versão.

Usando o script de deploy

O script deploy.sh cuida da sequência de setup, destaca problemas e implanta cada componente na ordem correta.

O que ele faz

Permite que você escolha seu provedor de nuvem (AWS, Azure ou GCP).
Oferece opções para implantar ou destruir a stack.
Verifica se todos os placeholders de configuração do backend têm valores.
Executa comandos do Terraform na ordem correta para cada componente.
Exibe logs claros e coloridos para que você saiba o que está acontecendo em cada etapa.

Como usar

Certifique-se de que todos os pré-requisitos estejam completos e de que você criou seu bucket de estado remoto.

Preencha todos os placeholders nos arquivos backend.tf.

Torne o script executável

chmod +x deploy.sh

Execute o script

./deploy.sh

Quando solicitado, selecione seu provedor de nuvem.

O script irá automaticamente

i. Verificar os placeholders restantes. \ii. Executar terraform init, plan e apply para cada componente. \iii. Implantar na ordem correta e parar se algo falhar.

Tratamento de erros

Construímos o script para falhar rapidamente e fornecer uma explicação. Se algo der errado, ele irá:

Parar imediatamente se encontrar placeholders que você esqueceu de preencher.
Sair se qualquer comando do Terraform falhar.
Mostrar exatamente qual componente falhou e em qual etapa.

Instalando o Midaz

Após implantar a infraestrutura base, você pode instalar o Midaz usando Helm. Para mais informações, consulte a página Implantando com Helm.

Pré-requisitos

Um cluster Kubernetes em execução (EKS, GKE ou AKS).
kubectl configurado para acessar o cluster.
Helm v3.x instalado.
Acesso ao repositório Helm do Midaz.

Passos de instalação

Adicione o repositório Helm do Midaz:

helm repo add midaz https://lerianstudio.github.io/helm
helm repo update

Crie um arquivo de valores (values.yaml) com sua configuração:

# Exemplo values.yaml
# Desabilite as dependências empacotadas
valkey:
  enabled: false

postgresql:
  enabled: false

## Point the ledger at your external PostgreSQL and Valkey/Redis.
## The ledger serves the onboarding and transaction modules in one process,
## so the DSNs are namespaced per module (DB_ONBOARDING_* / DB_TRANSACTION_*).
ledger:
  configmap:
    DB_ONBOARDING_HOST: "postgresql.midaz.internal"
    DB_ONBOARDING_USER: "midaz"
    DB_ONBOARDING_NAME: "onboarding"
    DB_ONBOARDING_PORT: "5432"
    DB_ONBOARDING_REPLICA_HOST: "postgresql-replica.midaz.internal"
    DB_ONBOARDING_REPLICA_USER: "midaz"
    DB_ONBOARDING_REPLICA_NAME: "onboarding"
    DB_ONBOARDING_REPLICA_PORT: "5432"
    DB_TRANSACTION_HOST: "postgresql.midaz.internal"
    DB_TRANSACTION_USER: "midaz"
    DB_TRANSACTION_NAME: "transaction"
    DB_TRANSACTION_PORT: "5432"
    DB_TRANSACTION_REPLICA_HOST: "postgresql-replica.midaz.internal"
    DB_TRANSACTION_REPLICA_USER: "midaz"
    DB_TRANSACTION_REPLICA_NAME: "transaction"
    DB_TRANSACTION_REPLICA_PORT: "5432"
    # REDIS_HOST carries host and port together.
    REDIS_HOST: "valkey.midaz.internal:6379"
  secrets:
    DB_ONBOARDING_PASSWORD: "<your-db-password>"
    DB_ONBOARDING_REPLICA_PASSWORD: "<your-replica-db-password>"
    DB_TRANSACTION_PASSWORD: "<your-db-password>"
    DB_TRANSACTION_REPLICA_PASSWORD: "<your-replica-db-password>"
    REDIS_PASSWORD: "<your-redis-password>"

Instale o Midaz:

helm install midaz midaz/midaz -f values.yaml

Para opções detalhadas de configuração e setup avançado, consulte o Repositório Helm do Midaz.

Dicas de segurança

A nuvem traz oportunidades e responsabilidades. Para manter sua infraestrutura Midaz segura, siga estas recomendações:

Sempre use clusters Kubernetes privados para limitar a exposição pública.
Acesse a API do Kubernetes via VPN em vez de permitir acesso público.
Configure e aplique RBAC (Controle de Acesso Baseado em Roles) para gerenciar permissões de usuários de forma eficaz.
Armazene todos os secrets no serviço de gerenciamento de secrets do provedor de nuvem.
Dê às service accounts apenas as permissões que realmente precisam.

Contribuindo

Antes de fazer qualquer alteração, configure os Git hooks. Os Git hooks garantem que cada commit siga nossos padrões e passe nas verificações necessárias.

Instale os Git hooks

make hooks

Crie uma nova branch de feature

git checkout -b feature/your-feature

Faça suas alterações e commite usando Conventional Commits.

Abra um pull request direcionado à branch develop.

Depois que os testes passarem e um mantenedor aprovar, suas alterações são mescladas na main.

Confira nosso Guia de Contribuição para saber mais sobre como trabalhamos juntos e o que esperamos dos contribuidores.

Licença

O Midaz Terraform Foundation usa a Apache License 2.0.

Precisa de ajuda?

Confira o README dentro de cada pasta de componente.
Procure nas issues existentes.
Abra uma nova issue se necessário.

Midaz Core

CRM

Fees

Midaz Terraform Foundation

Por que usar

Velocidade e padronização

Segurança e observabilidade

Manutenção e suporte

O que você vai precisar

Integração CI/CD

Estrutura do projeto

A ordem de implantação importa

Criando o armazenamento de estado

AWS

Google Cloud Platform

Azure

Requisitos de configuração

Credenciais de produção e implantação

Autenticação no provedor de nuvem

AWS

GCP

Azure

Boas práticas de gerenciamento de credenciais

Práticas recomendadas

Usando o script de deploy

O que ele faz

Como usar

Tratamento de erros

Instalando o Midaz

Pré-requisitos

Passos de instalação

Dicas de segurança

Contribuindo

Licença

Precisa de ajuda?

​Por que usar

​Velocidade e padronização

​Segurança e observabilidade

​Manutenção e suporte

​O que você vai precisar

​Integração CI/CD

​Estrutura do projeto

​A ordem de implantação importa

​Criando o armazenamento de estado

​AWS

​Google Cloud Platform

​Azure

​Requisitos de configuração

​Credenciais de produção e implantação

​Autenticação no provedor de nuvem

​AWS

​GCP

​Azure

​Boas práticas de gerenciamento de credenciais

​Práticas recomendadas

​Usando o script de deploy

​O que ele faz

​Como usar

​Tratamento de erros

​Instalando o Midaz

​Pré-requisitos

​Passos de instalação

​Dicas de segurança

​Contribuindo

​Licença

​Precisa de ajuda?

Por que usar

Velocidade e padronização

Segurança e observabilidade

Manutenção e suporte

O que você vai precisar

Integração CI/CD

Estrutura do projeto

A ordem de implantação importa

Criando o armazenamento de estado

AWS

Google Cloud Platform

Azure

Requisitos de configuração

Credenciais de produção e implantação

Autenticação no provedor de nuvem

AWS

GCP

Azure

Boas práticas de gerenciamento de credenciais

Práticas recomendadas

Usando o script de deploy

O que ele faz

Como usar

Tratamento de erros

Instalando o Midaz

Pré-requisitos

Passos de instalação

Dicas de segurança

Contribuindo

Licença

Precisa de ajuda?