> ## 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 para o Midaz na AWS, GCP ou Azure com exemplos prontos de Terraform — rede, bancos de dados e Kubernetes.

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)

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

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

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

## O que você vai precisar

***

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

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

<Steps>
  <Step>
    **Pule o script de deploy**; ele é destinado apenas 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 secrets integrado da sua plataforma de CI/CD para lidar com credenciais de forma segura.
  </Step>
</Steps>

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

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

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

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

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

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

### Google Cloud Platform

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

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

### Azure

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

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

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

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

<Steps>
  <Step title="Copie 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. **Este arquivo contém a configuração principal para o setup da sua infraestrutura.**
  </Step>
</Steps>

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

* **AWS**: [Gerenciando chaves de acesso 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 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

<Steps>
  <Step>
    Certifique-se de que todos os **pré-requisitos estejam completos** e que seu **bucket de estado remoto tenha sido criado**.
  </Step>

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

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

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

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

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

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

#### 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](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 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>"
    ```
  </Step>

  <Step>
    Instale o Midaz:

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

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

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

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

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

  <Step>
    Faça suas alterações e commite usando Conventional Commits.
  </Step>

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

  <Step>
    Uma vez testado e aprovado, suas alterações serão mescladas na `main`.
  </Step>
</Steps>

Confira nosso [Guia de Contribuição](https://github.com/LerianStudio/midaz-terraform-foundation/blob/main/CONTRIBUTING.md) para saber mais sobre como trabalhamos juntos e o que esperamos dos contribuidores.

## Licença

***

O Midaz é um projeto source-available licenciado sob a [Elastic License 2.0](https://github.com/LerianStudio/midaz-terraform-foundation/blob/main/LICENSE).

## Precisa de ajuda?

***

* Confira o README dentro de cada pasta de componente.
* Procure nas [issues](https://github.com/LerianStudio/terraform-midaz-foundation/issues) existentes.
* Abra uma nova issue se necessário.