Midaz Terraform Foundation

Midaz Terraform Foundation é um repositório de exemplos Terraform prontos. Use-os para criar a infraestrutura base que o Midaz precisa na AWS, GCP ou Azure. Os exemplos seguem as boas 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 message broker apenas em alguns provedores. A AWS usa Amazon DocumentDB e Amazon MQ (RabbitMQ). O Azure usa Cosmos DB com a API do MongoDB. A GCP não tem equivalente gerenciado, então você precisa provisionar o MongoDB e o RabbitMQ por conta própria na GCP.

Por que usar

O midaz-terraform-foundation segue as boas práticas da Lerian para segurança, observabilidade e escalabilidade. As tabelas abaixo comparam essa abordagem 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 configuração	Rápida – provisiona tudo em minutos com um único `apply`.	Lenta – leva dias para configurar e testar.
Padrão de arquitetura	Padronizada – segue as boas práticas da Lerian.	Imprevisível – pode ser inconsistente.
Reusabilidade	Alta – aceita vários ambientes com mudanças mínimas.	Baixa – difícil de reusar entre projetos.

Segurança e observabilidade

Critério	Com Midaz Terraform	Configuração manual / scripts ad-hoc
Segurança por padrão	Sim – segura por design (VPCs isoladas, IAM, segredos etc.).	Não – depende da equipe, o que aumenta o risco de exposição.
Observabilidade nativa	Nativa – integra com Prometheus, Grafana e outras ferramentas.	Manual – exige configuração separada, muitas vezes deixada de lado.
Pronta para produção?	Sim – alta disponibilidade e autoscaling prontos de fábrica.	Incerto – exige esforço extra para reforçar.

Manutenção e suporte

Critério	Com Midaz Terraform	Configuração manual / scripts ad-hoc
Manutenibilidade	Fácil – modular e versionada, atualizações sem dor de cabeça.	Difícil – scripts quebram com facilidade.
Suporte Lerian	Incluído – verificado e suportado pela Lerian.	Nenhum – sem garantia.
Tempo estimado de deploy	1 dia – incluindo validação.	1–2 semanas – com risco operacional maior.

Use esse repositório para uma configuração mais rápida e testada.O midaz-terraform-foundation segue os padrões de engenharia da Lerian.

O que você vai precisar

Antes de começar, confirme que você tem:

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 storage bucket para os arquivos de estado do Terraform.
A ferramenta de linha de comando do seu provedor de nuvem:
- aws para AWS
- gcloud para GCP
- az para Azure

Integração com CI/CD

Este repositório fornece exemplos Terraform para fazer o deploy da infraestrutura de fundação. Ele não inclui um pipeline de CI/CD. Crie um que atenda às necessidades do seu projeto. Se você já roda um pipeline de CI/CD do Terraform, siga estes passos:

Pule o script de deploy. Ele é só 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 segredos nativo da sua plataforma de CI/CD para lidar com credenciais com segurança.

Estrutura do projeto

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

.
├── 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 deploy importa

Para evitar erros e conectar tudo corretamente, faça o deploy dos componentes nesta ordem:

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

Criando o armazenamento de estado

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

AWS

Substitua REGION e UNIQUE_BUCKET_NAME pelos seus próprios valores.

Criar um bucket S3

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

Habilitar versionamento

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

Habilitar criptografia

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

Bloquear 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

Criar um bucket GCS

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

Habilitar versionamento

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

Azure

Criar um resource group

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

Criar uma storage account

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

Criar um container

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

Requisitos de configuração

Antes de fazer o deploy da infraestrutura, crie e configure o arquivo de variáveis de cada componente de nuvem:

Copiar 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. Esse arquivo guarda a configuração-chave da sua infraestrutura.

Credenciais de produção e deploy

Em ambientes de produção, você deve gerenciar credenciais com cuidado.

Autenticação do provedor de nuvem

Ao rodar o script de deploy localmente, use as ferramentas de autenticação da CLI do provedor de nuvem em vez de credenciais brutas. Esse método é mais seguro. Ele gerencia rotação de credenciais, MFA e renovação de token automaticamente. Por que adotar essa abordagem?

Os tokens são renovados automaticamente.
Integração com MFA e SSO prontas de fábrica.
Ele rotaciona e armazena credenciais com segurança.
Trilha de auditoria completa para eventos de autenticação.

AWS

Use a AWS CLI para assumir um 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 código:

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 código:

az login --service-principal

Boas práticas de gerenciamento de credenciais

Mantenha-se seguro e em conformidade seguindo a orientação oficial do seu provedor de nuvem:

AWS: Gerenciando chaves de acesso da 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 papéis (RBAC) sempre que possível.
Exija MFA para contas de usuário.
Prefira credenciais temporárias de vida curta.
Monitore e audite o uso de 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 configuração, aponta problemas e faz o deploy de cada componente na ordem correta.

O que ele faz

Permite escolher seu provedor de nuvem (AWS, Azure ou GCP).
Oferece opções para fazer o deploy ou destruir a stack.
Confirma que todos os placeholders de configuração do backend têm valores.
Roda os comandos do Terraform na ordem certa para cada componente.
Mostra logs claros e coloridos para você acompanhar cada passo.

Como usar

Confirme que todos os pré-requisitos estão completos e que você criou seu bucket de estado remoto.

Preencha todos os placeholders nos arquivos backend.tf.

Tornar o script executável

chmod +x deploy.sh

Rodar o script

./deploy.sh

Quando solicitado, selecione seu provedor de nuvem.

O script vai automaticamente

i. Conferir os placeholders restantes. \ii. Rodar terraform init, plan e apply para cada componente. \iii. Fazer o deploy na ordem correta e parar se algo falhar.

Tratamento de erros

Construímos o script para falhar rápido e explicar o motivo. Se algo der errado, ele vai:

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

Instalando o Midaz

Depois de fazer o deploy da infraestrutura de fundação, você pode instalar o Midaz usando Helm. Para mais informações, consulte a página Deploy usando 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:

# Example values.yaml
# Disable the bundled dependencies
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 de configuração detalhadas e configuração avançada, consulte o repositório Helm do Midaz.

Dicas de segurança

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 (Role-Based Access Control) para gerenciar permissões de usuário.
Armazene todos os segredos no serviço de gerenciamento de segredos do provedor de nuvem.
Dê às service accounts apenas as permissões de que precisam.

Contribuindo

Antes de fazer qualquer mudança, configure os Git hooks. Os Git hooks garantem que cada commit siga nossos padrões e passe pelas verificações exigidas.

Instalar os Git hooks

make hooks

Criar uma nova branch de feature

git checkout -b feature/your-feature

Faça suas mudanças e o commit usando Conventional Commits.

Abra um pull request direcionado à branch develop.

Depois que os testes passarem e um mantenedor aprovar, suas mudanças fazem merge na main.

Confira nosso Guia de contribuição.

Licença

O Midaz Terraform Foundation usa a Apache License 2.0.

Precisa de ajuda?

Confira o README dentro de cada pasta de componente.
Pesquise as issues existentes.
Abra uma nova issue se precisar.

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 com CI/CD

Estrutura do projeto

A ordem de deploy importa

Criando o armazenamento de estado

AWS

Google Cloud Platform

Azure

Requisitos de configuração

Credenciais de produção e deploy

Autenticação do 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 com CI/CD

​Estrutura do projeto

​A ordem de deploy importa

​Criando o armazenamento de estado

​AWS

​Google Cloud Platform

​Azure

​Requisitos de configuração

​Credenciais de produção e deploy

​Autenticação do 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 com CI/CD

Estrutura do projeto

A ordem de deploy importa

Criando o armazenamento de estado

AWS

Google Cloud Platform

Azure

Requisitos de configuração

Credenciais de produção e deploy

Autenticação do 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?