> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Midaz Terraform Foundation

> Provisione a infraestrutura base do Midaz na AWS, GCP ou Azure com exemplos Terraform prontos: rede, bancos de dados e Kubernetes.

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)

<Danger>
  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.
</Danger>

## 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. |

<Tip>
  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.
</Tip>

## O que você vai precisar

***

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

* [Terraform v1.5.0 ou superior](https://developer.hashicorp.com/terraform/install): 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:

<Steps>
  <Step>
    **Pule o script de deploy.** Ele é só para uso local.
  </Step>

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

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

  <Step>
    Use o gerenciamento de segredos nativo da sua plataforma de CI/CD para lidar com credenciais com segurança.
  </Step>
</Steps>

## 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.

```bash theme={null}
.
├── 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:

1. VPC / Rede
2. DNS
3. Banco de dados
4. Redis/Valkey
5. 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.**

<Steps>
  <Step title="Criar um bucket S3">
    ```
     aws s3api create-bucket \
        --bucket UNIQUE_BUCKET_NAME \
        --region REGION \
        --create-bucket-configuration LocationConstraint=REGION
    ```
  </Step>

  <Step title="Habilitar versionamento">
    ```
    aws s3api put-bucket-versioning \
        --bucket UNIQUE_BUCKET_NAME \
        --versioning-configuration Status=Enabled
    ```
  </Step>

  <Step title="Habilitar criptografia">
    ```
    aws s3api put-bucket-encryption \
        --bucket UNIQUE_BUCKET_NAME \
        --server-side-encryption-configuration \
        '{"Rules":[{"ApplyServerSideEncryptionByDefault":{"SSEAlgorithm":"AES256"}}]}'
    ```
  </Step>

  <Step title="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}'
    ```
  </Step>
</Steps>

### Google Cloud Platform

<Steps>
  <Step title="Criar um bucket GCS">
    ```
    gsutil mb -l us-central1 gs://your-terraform-state-bucket
    ```
  </Step>

  <Step title="Habilitar versionamento">
    ```
    gsutil versioning set on gs://your-terraform-state-bucket
    ```
  </Step>
</Steps>

### Azure

<Steps>
  <Step title="Criar um resource group">
    ```
    az group create --name terraform-state-rg --location eastus
    ```
  </Step>

  <Step title="Criar uma storage account">
    ```
    az storage account create --name tfstate$RANDOM --resource-group terraform-state-rg --sku Standard_LRS
    ```
  </Step>

  <Step title="Criar um container">
    ```
    az storage container create --name terraform-state --account-name <storage-account-name>
    ```
  </Step>
</Steps>

## Requisitos de configuração

***

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

<Steps>
  <Step title="Copiar o arquivo de exemplo">
    ```
    cd examples/<provider>/<component>
    cp midaz.tfvars-example midaz.tfvars
    ```
  </Step>

  <Step>
    Substitua todos os placeholders no arquivo `midaz.tfvars` pelos seus valores reais. \\

    i. **Esse arquivo guarda a configuração-chave da sua infraestrutura.**
  </Step>
</Steps>

## 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
```

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 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](https://docs.aws.amazon.com/general/latest/gr/aws-access-keys-best-practices.html).
* **GCP**: [Gerenciando chaves de service account](https://cloud.google.com/iam/docs/best-practices-for-managing-service-account-keys).
* **Azure**: [Boas práticas de gerenciamento de identidade](https://learn.microsoft.com/en-us/azure/security/fundamentals/identity-management-best-practices).

#### 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

<Steps>
  <Step>
    Confirme que todos os **pré-requisitos estão completos** e que você **criou seu bucket de estado remoto**.
  </Step>

  <Step>
    Preencha todos os **placeholders** nos arquivos `backend.tf`.
  </Step>

  <Step title="Tornar o script executável">
    ```
    chmod +x deploy.sh
    ```
  </Step>

  <Step title="Rodar o script">
    ```
    ./deploy.sh
    ```
  </Step>

  <Step>
    Quando solicitado, selecione seu provedor de nuvem.
  </Step>

  <Step title="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.
  </Step>
</Steps>

### 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](/pt/platform/deploy/midaz/midaz-installation).

#### 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](https://github.com/LerianStudio/helm).

### Passos de instalação

<Steps>
  <Step>
    Adicione o repositório Helm do Midaz:

    ```
    helm repo add midaz https://lerianstudio.github.io/helm
    helm repo update
    ```
  </Step>

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

    ```bash expandable theme={null}
    # 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>"
    ```
  </Step>

  <Step>
    Instale o Midaz:

    ```
    helm install midaz midaz/midaz -f values.yaml
    ```
  </Step>
</Steps>

Para opções de configuração detalhadas e configuração avançada, consulte o [repositório Helm do Midaz](https://github.com/LerianStudio/helm).

## 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.

<Steps>
  <Step title="Instalar os Git hooks">
    ```
    make hooks
    ```
  </Step>

  <Step title="Criar uma nova branch de feature">
    ```
    git checkout -b feature/your-feature
    ```
  </Step>

  <Step>
    Faça suas mudanças e o commit usando Conventional Commits.
  </Step>

  <Step>
    Abra um pull request direcionado à branch `develop`.
  </Step>

  <Step>
    Depois que os testes passarem e um mantenedor aprovar, suas mudanças fazem merge na `main`.
  </Step>
</Steps>

Confira nosso [Guia de contribuição](https://github.com/LerianStudio/lerian-terraform-foundation/blob/main/CONTRIBUTING.md).

## Licença

***

O Midaz Terraform Foundation usa a [Apache License 2.0](https://github.com/LerianStudio/lerian-terraform-foundation/blob/main/LICENSE).

## Precisa de ajuda?

***

* Confira o README dentro de cada pasta de componente.
* Pesquise as [issues](https://github.com/LerianStudio/lerian-terraform-foundation/issues) existentes.
* Abra uma nova issue se precisar.