Pular para o conteúdo principal
O Midaz Terraform Foundation é um repositório com exemplos prontos de Terraform para ajudar você a criar a infraestrutura base necessária para rodar o Midaz, seguindo as melhores práticas dos principais provedores de nuvem: AWS, GCP ou Azure. Essa infraestrutura base inclui:
  • Rede (VPC, subnets)
  • DNS
  • Banco de dados
  • Redis/Valkey
  • Cluster Kubernetes (EKS, GKE ou AKS)
Os templates do Midaz Terraform Foundation não incluem MongoDB nem RabbitMQ. Esses serviços não são oferecidos de forma consistente como serviços gerenciados em todos os principais provedores de nuvem (AWS, GCP, Azure).

​
Por que usar

Provisionar infraestrutura não deveria ser lento, inconsistente ou propenso a erros. O midaz-terraform-foundation ajuda você a avançar rápido mantendo-se alinhado com as melhores práticas da Lerian para segurança, observabilidade e escalabilidade. Veja como ele se compara a configurações manuais ou ad-hoc:

​
Velocidade e padronização

CritérioCom Midaz TerraformConfiguração manual / Scripts ad-hoc
Velocidade de setupRápido – provisiona tudo em minutos com um único apply.Lento – leva dias para configurar e testar.
Padrão de arquiteturaPadronizado – segue as melhores práticas da Lerian.Imprevisível – pode ser inconsistente.
ReusabilidadeAlta – suporta múltiplos ambientes com alterações mínimas.Baixa – difícil de reutilizar entre projetos.

​
Segurança e observabilidade

CritérioCom Midaz TerraformConfiguração manual / Scripts ad-hoc
Segurança por padrãoSim – seguro por design (VPCs isoladas, IAM, secrets, etc.).Não – depende da equipe, aumentando o risco de exposição.
Observabilidade integradaIntegrada – 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érioCom Midaz TerraformConfiguração manual / Scripts ad-hoc
ManutenibilidadeFácil – modular e versionado para atualizações sem dor.Difícil – scripts quebram facilmente.
Suporte LerianIncluído – verificado e suportado pela Lerian.Nenhum – não garantido.
Tempo estimado de implantação1 dia – incluindo validação.1–2 semanas – com maior risco operacional.
Procurando velocidade, confiabilidade e suporte a longo prazo?O midaz-terraform-foundation ajuda você a implantar mais rápido, evitar armadilhas comuns e escalar com confiança — tudo respaldado pelos padrões de engenharia da Lerian.

​
O que você vai precisar

Antes de começar, certifique-se de ter:
  • Terraform v1.0.0 ou superior
  • 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. Você precisará criar um com base nas necessidades do seu projeto. Já está rodando um pipeline de CI/CD com Terraform? Veja o que fazer:
1
Pule o script de deploy; ele é destinado apenas para uso local.
2
Copie as configurações de exemplo relevantes para o seu repositório privado de Infrastructure as Code.
3
Integre as configurações do Terraform ao seu pipeline conforme necessário.
4
Use o gerenciamento de secrets integrado da sua plataforma de CI/CD para lidar com credenciais de forma segura.

​
Estrutura do projeto

O repositório é projetado com uma estrutura única para cada provedor de nuvem. Isso significa que cada componente da infraestrutura é organizado para suportar uma abordagem modular e controlada. Você tem a flexibilidade de implantar apenas o que precisa, ou ir com tudo e usar a fundação completa. 
.
├── examples/
    ├── aws/
    │   ├── vpc/
    │   ├── route53/
    │   ├── rds/
    │   ├── valkey/
    │   └── eks/
    ├── gcp/
    │   ├── vpc/
    │   ├── cloud-dns/
    │   ├── cloud-sql/
    │   ├── valkey/
    │   └── gke/
    └── azure/
        ├── network/
        ├── dns/
        ├── database/
        ├── redis/
        └── aks/

​
A ordem de implantação importa

Para evitar erros e garantir que tudo se conecte corretamente, recomendamos implantar os componentes nesta sequência:
  1. VPC / Network
  2. DNS
  3. Banco de dados
  4. Redis/Valkey
  5. Cluster Kubernetes

​
Criando o armazenamento de estado

O Terraform requer um backend remoto para gerenciar seu estado. Para começar com esses templates, é essencial configurar primeiro um bucket de armazenamento para os arquivos de estado do Terraform.

​
AWS

Não esqueça de substituir REGION e UNIQUE_BUCKET_NAME pelas suas informações.
1

Crie um bucket S3

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

Habilite o versionamento

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

Habilite a criptografia

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

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

1

Crie um bucket GCS

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

Habilite o versionamento

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

​
Azure

1

Crie um resource group

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

Crie uma storage account

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

Crie um container

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

​
Requisitos de configuração

  • Antes de implantar a infraestrutura, certifique-se de ter criado e configurado o arquivo de variáveis para cada componente de nuvem:
1

Copie o arquivo de exemplo

cd examples/<provider>/<component>
cp midaz.tfvars-example midaz.tfvars
2
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

Quando se trata de implantar infraestrutura em ambientes de produção, gerenciar credenciais com cuidado é crucial para manter a segurança. Aqui está um guia sobre como lidar com credenciais de forma segura:

​
Autenticação no provedor de nuvem

Ao usar o script de deploy localmente, recomendamos fortemente utilizar as ferramentas de autenticação CLI do provedor de nuvem em vez de credenciais brutas. Este método é significativamente mais seguro, pois gerencia automaticamente a rotação de credenciais, MFA e refresh de tokens para você! Por que adotar essa abordagem?
  • Tokens são atualizados automaticamente.
  • Integração com MFA e SSO pronta para uso.
  • Credenciais são rotacionadas e armazenadas 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
ou 
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:

​
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 como as credenciais são utilizadas.
  • 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 ao longo do caminho e garante que cada componente seja implantado 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 estão preenchidos corretamente.
  • 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

1
Certifique-se de que todos os pré-requisitos estejam completos e que seu bucket de estado remoto tenha sido criado.
2
Preencha todos os placeholders nos arquivos backend.tf.
3

Torne o script executável

chmod +x deploy.sh
4

Execute o script

./deploy.sh
5
Quando solicitado, selecione seu provedor de nuvem.
6

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

  • Cluster Kubernetes funcionando (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

1
Adicione o repositório Helm do Midaz:
helm repo add midaz https://lerianstudio.github.io/helm
helm repo update
2
Crie um arquivo de valores (values.yaml) com sua configuração:
# Example values.yaml
# Disable default dependencies
valkey:
   enabled: false

postgresql:
   enabled: false

## Configure external PostgreSQL
onboarding:
  configmap:
    DB_HOST: "postgresql.midaz.internal."
    DB_USER: "midaz"
    DB_PORT: "5432"
    DB_REPLICA_HOST: "postgresql-replica.midaz.internal."
    DB_REPLICA_USER: "midaz"
    DB_REPLICA_PORT: "5432"
    REDIS_HOST: "valkey.midaz.internal"
    REDIS_PORT: "6379"
  secrets:
     DB_PASSWORD: "<your-db-password>"
     DB_REPLICA_PASSWORD: "<your-replica-db-password>"
     REDIS_PASSWORD: "<your-redis-password>"

transaction:
  configmap:
    DB_HOST: "postgresql.midaz.internal."
    DB_USER: "midaz"
    DB_PORT: "5432"
    DB_REPLICA_HOST: "postgresql-replica.midaz.internal."
    DB_REPLICA_USER: "midaz"
    DB_REPLICA_PORT: "5432"
    REDIS_HOST: "valkey.midaz.internal"
    REDIS_PORT: "6379"
  secrets:
    DB_PASSWORD: "<your-db-password>"
    DB_REPLICA_PASSWORD: "<your-replica-db-password>"
    REDIS_PASSWORD: "<your-redis-password>"
3
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

Usar a nuvem traz oportunidades fantásticas, mas também vem com responsabilidades importantes. Para ajudar a manter sua infraestrutura Midaz segura, recomendamos:
  • 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, você precisará configurar os Git hooks. Isso ajuda a garantir que cada commit siga nossos padrões e passe nas verificações necessárias.
1

Instale os Git hooks

make hooks
2

Crie uma nova branch de feature

git checkout -b feature/your-feature
3
Faça suas alterações e commite usando Conventional Commits.
4
Abra um pull request direcionado à branch develop.
5
Uma vez testado e aprovado, suas alterações serã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 é um projeto open-source licenciado sob a Elastic 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.