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

> Aprovisiona la infraestructura base para Midaz en AWS, GCP o Azure con ejemplos de Terraform listos — redes, bases de datos y Kubernetes.

Midaz Terraform Foundation es un repositorio con ejemplos de Terraform listos para usar que te ayudan a crear la infraestructura base necesaria para ejecutar Midaz, utilizando las mejores prácticas de los principales proveedores de nube: AWS, GCP o Azure.

Esta infraestructura base incluye:

* Red (VPC, subredes)
* DNS
* Base de datos
* Redis/Valkey
* Clúster de Kubernetes (EKS, GKE o AKS)

<Danger>
  Las plantillas de Midaz Terraform Foundation **no incluyen MongoDB** ni **RabbitMQ**. Estos servicios no se ofrecen consistentemente como servicios administrados en todos los principales proveedores de nube (AWS, GCP, Azure).
</Danger>

## Por qué usarlo

***

Aprovisionar infraestructura no debería ser lento, inconsistente o propenso a errores. `midaz-terraform-foundation` te ayuda a moverte rápido mientras te mantienes alineado con las mejores prácticas de Lerian para seguridad, observabilidad y escalabilidad. Así es como se compara con configuraciones manuales o ad-hoc:

### Velocidad y estandarización

| **Criterio**                   | **Con Midaz Terraform**                                       | **Configuración manual / Scripts ad-hoc**         |
| :----------------------------- | :------------------------------------------------------------ | :------------------------------------------------ |
| **Velocidad de configuración** | **Rápido** – aprovisiona todo en minutos con un solo `apply`. | **Lento** – toma días configurar y probar.        |
| **Estándar de arquitectura**   | **Estandarizado** – sigue las mejores prácticas de Lerian.    | **Impredecible** – puede ser inconsistente.       |
| **Reusabilidad**               | **Alta** – admite múltiples entornos con cambios mínimos.     | **Baja** – difícil de reutilizar entre proyectos. |

### Seguridad y observabilidad

| **Criterio**                 | **Con Midaz Terraform**                                          | **Configuración manual / Scripts ad-hoc**                        |
| :--------------------------- | :--------------------------------------------------------------- | :--------------------------------------------------------------- |
| **Seguridad por defecto**    | **Sí** – seguro por diseño (VPCs aislados, IAM, secretos, etc.). | **No** – depende del equipo, aumentando el riesgo de exposición. |
| **Observabilidad integrada** | **Integrada** – se integra con Prometheus, Grafana y más.        | **Manual** – requiere configuración separada, a menudo omitida.  |
| **¿Listo para producción?**  | **Sí** – alta disponibilidad y autoescalado listos para usar.    | **Incierto** – necesita esfuerzo adicional para endurecer.       |

### Mantenimiento y soporte

| **Criterio**                      | **Con Midaz Terraform**                                          | **Configuración manual / Scripts ad-hoc**       |
| :-------------------------------- | :--------------------------------------------------------------- | :---------------------------------------------- |
| **Mantenibilidad**                | **Fácil** – modular y versionado para actualizaciones sin dolor. | **Difícil** – los scripts se rompen fácilmente. |
| **Soporte de Lerian**             | **Incluido** – verificado y soportado por Lerian.                | **Ninguno** – no garantizado.                   |
| **Tiempo estimado de despliegue** | **1 día** – incluida la validación.                              | **1–2 semanas** – con mayor riesgo operacional. |

<Tip>
  ¿Buscas velocidad, confiabilidad y soporte a largo plazo?

  `midaz-terraform-foundation` te ayuda a desplegar más rápido, evitar trampas comunes y escalar con confianza, todo respaldado por los estándares de ingeniería de Lerian.
</Tip>

## Qué necesitarás

***

Antes de comenzar, asegúrate de tener:

* [Terraform v1.0.0 o superior](https://developer.hashicorp.com/terraform/install)
* Una cuenta de proveedor de nube (AWS, GCP o Azure).
* Un bucket de almacenamiento para archivos de estado de Terraform.
* La herramienta CLI para tu proveedor de nube:
  * `aws` para AWS
  * `gcloud` para GCP
  * `az` para Azure

### Integración CI/CD

Este repositorio proporciona ejemplos de Terraform para desplegar infraestructura base. **No incluye un pipeline CI/CD**. Necesitarás crear uno según las necesidades de tu proyecto.

¿Ya ejecutas un pipeline CI/CD de Terraform? Esto es lo que debes hacer:

<Steps>
  <Step>
    **Omite el script de despliegue**; está diseñado solo para uso local.
  </Step>

  <Step>
    Copia las configuraciones de ejemplo relevantes en tu repositorio privado de Infraestructura como Código.
  </Step>

  <Step>
    Integra las configuraciones de Terraform en tu pipeline según sea necesario.
  </Step>

  <Step>
    Usa la gestión de secretos integrada de tu plataforma CI/CD para manejar credenciales de forma segura.
  </Step>
</Steps>

## Estructura del proyecto

***

El repositorio está diseñado con una estructura única para cada proveedor de nube. Esto significa que cada componente de la infraestructura está organizado para soportar un enfoque modular y controlado. Tienes la flexibilidad de desplegar solo lo que necesitas, o ir con todo con toda la base si lo prefieres.

```bash theme={null}
.
├── examples/
    ├── aws/
    │   ├── vpc/
    │   ├── route53/
    │   ├── rds/
    │   ├── valkey/
    │   └── eks/
    ├── gcp/
    │   ├── vpc/
    │   ├── cloud-dns/
    │   ├── cloud-sql/
    │   ├── valkey/
    │   └── gke/
    └── azure/
        ├── network/
        ├── dns/
        ├── database/
        ├── redis/
        └── aks/
```

### El orden de despliegue importa

Para evitar errores y asegurar que todo se conecte correctamente, recomendamos desplegar los componentes en esta secuencia:

1. VPC / Red
2. DNS
3. Base de datos
4. Redis/Valkey
5. Clúster de Kubernetes

## Creando el almacenamiento de estado

***

Terraform requiere un backend remoto para gestionar su estado. Para comenzar con estas plantillas, es esencial configurar primero un bucket de almacenamiento para los archivos de estado de Terraform.

### AWS

**`No olvides reemplazar REGION y UNIQUE_BUCKET_NAME con tu información.`**

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

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

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

  <Step title="Bloquear acceso 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="Crear un bucket GCS">
    ```
    gsutil mb -l us-central1 gs://your-terraform-state-bucket
    ```
  </Step>

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

### Azure

<Steps>
  <Step title="Crear un grupo de recursos">
    ```
    az group create --name terraform-state-rg --location eastus
    ```
  </Step>

  <Step title="Crear una cuenta de almacenamiento">
    ```
    az storage account create --name tfstate$RANDOM --resource-group terraform-state-rg --sku Standard_LRS
    ```
  </Step>

  <Step title="Crear un contenedor">
    ```
    az storage container create --name terraform-state --account-name <storage-account-name>
    ```
  </Step>
</Steps>

## Requisitos de configuración

***

Antes de desplegar la infraestructura, asegúrate de haber creado y configurado el archivo de variables para cada componente de nube:

<Steps>
  <Step title="Copiar el archivo de ejemplo">
    ```
    cd examples/<provider>/<component>
    cp midaz.tfvars-example midaz.tfvars
    ```
  </Step>

  <Step>
    Reemplaza todos los marcadores de posición en el archivo `midaz.tfvars` con tus valores reales. \\

    i. **Este archivo contiene la configuración clave para tu configuración de infraestructura.**
  </Step>
</Steps>

## Credenciales de producción y despliegue

***

Cuando se trata de desplegar infraestructura en entornos de producción, gestionar las credenciales con cuidado es crucial para mantener la seguridad. Aquí hay una guía sobre cómo manejar las credenciales de forma segura:

### Autenticación del proveedor de nube

Al usar el script de despliegue localmente, recomendamos encarecidamente utilizar herramientas de autenticación CLI del proveedor de nube en lugar de credenciales sin procesar. Este método es significativamente más seguro, ya que gestiona automáticamente la rotación de credenciales, MFA y actualización de tokens.

**¿Por qué adoptar este enfoque?**

* Los tokens se actualizan automáticamente.
* Integración de MFA y SSO lista para usar.
* Las credenciales se rotan y almacenan de forma segura.
* Registro de auditoría completo para eventos de autenticación.

#### AWS

Usa AWS CLI para asumir un rol.

```
aws sso login --profile your-profile
```

o

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

#### GCP

Usa autenticación de gcloud.

```
gcloud auth application-default login
```

**Para cuentas de servicio**, usa el siguiente código:

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

#### Azure

Usa Azure CLI.

```
az login
```

Para service principals, usa el siguiente código:

```
az login --service-principal
```

### Mejores prácticas de gestión de credenciales

Mantente seguro y conforme siguiendo la guía oficial de tu proveedor de nube:

* **AWS**: [Gestión de claves de acceso de AWS](https://docs.aws.amazon.com/general/latest/gr/aws-access-keys-best-practices.html).
* **GCP**: [Gestión de claves de cuenta de servicio](https://cloud.google.com/iam/docs/best-practices-for-managing-service-account-keys).
* **Azure**: [Mejores prácticas de gestión de identidad](https://learn.microsoft.com/en-us/azure/security/fundamentals/identity-management-best-practices).

#### Prácticas recomendadas

* Rota las credenciales en un calendario regular.
* Usa control de acceso basado en roles (RBAC) siempre que sea posible.
* Requiere MFA para cuentas de usuario.
* Prefiere credenciales temporales de corta duración.
* Monitorea y audita cómo se usan las credenciales.
* **Nunca** confirmes credenciales en el control de versiones.

## Usando el script de despliegue

***

El script `deploy.sh` maneja la secuencia de configuración, resalta problemas en el camino y asegura que cada componente se despliegue en el orden correcto.

### Qué hace

* Te permite elegir tu proveedor de nube (AWS, Azure o GCP).
* Ofrece opciones para desplegar o destruir el stack.
* Verifica que todos los marcadores de posición de configuración del backend estén configurados correctamente.
* Ejecuta comandos de Terraform en el orden correcto para cada componente.
* Genera logs claros y codificados por colores para que sepas qué está sucediendo en cada paso.

### Cómo usarlo

<Steps>
  <Step>
    Asegúrate de que todos los **requisitos previos estén completos** y que tu **bucket de estado remoto haya sido creado**.
  </Step>

  <Step>
    Completa todos los **marcadores de posición** en los archivos `backend.tf`.
  </Step>

  <Step title="Hacer el script ejecutable">
    ```
    chmod +x deploy.sh
    ```
  </Step>

  <Step title="Ejecutar el script">
    ```
    ./deploy.sh
    ```
  </Step>

  <Step>
    Cuando se te solicite, selecciona tu proveedor de nube.
  </Step>

  <Step title="El script automáticamente">
    i. Verificará los marcadores de posición restantes. \\

    ii. Ejecutará `terraform init`, `plan` y `apply` para cada componente. \\

    iii. Desplegará en el orden correcto y se detendrá si algo falla.
  </Step>
</Steps>

### Manejo de errores

Construimos el script para fallar rápidamente y proporcionar una explicación. Si algo sale mal, va a:

* Detenerse inmediatamente si encuentra marcadores de posición que olvidaste completar.
* Salir si algún comando de Terraform falla.
* Mostrarte exactamente qué componente falló y en qué paso.

## Instalando Midaz

***

Después de desplegar la infraestructura base, puedes instalar Midaz usando Helm. Para más información, consulta la página [Desplegando usando Helm](/es/platform/helm/midaz/midaz-installation).

#### Requisitos previos

* El clúster de Kubernetes está funcionando (EKS, GKE o AKS).
* `kubectl` configurado para acceder al clúster.
* Helm v3.x instalado.
* Acceso al [repositorio Helm de Midaz](https://github.com/LerianStudio/helm).

### Pasos de instalación

<Steps>
  <Step>
    Agrega el repositorio Helm de Midaz:

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

  <Step>
    Crea un archivo de valores (`values.yaml`) con tu configuración:

    ```bash expandable theme={null}
    # Ejemplo values.yaml
    # Deshabilitar dependencias predeterminadas
    valkey:
       enabled: false

    postgresql:
       enabled: false

    ## Configurar PostgreSQL externo
    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>
    Instalar Midaz:

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

Para opciones de configuración detalladas y configuración avanzada, consulta el [Repositorio Helm de Midaz](https://github.com/LerianStudio/helm).

## Consejos de seguridad

***

Usar la nube trae oportunidades fantásticas, pero también viene con responsabilidades importantes. Para ayudar a mantener tu infraestructura de Midaz segura, recomendamos:

* Siempre usa **clústeres de Kubernetes privados** para limitar la exposición pública.
* Accede a la **API de Kubernetes vía VPN** en lugar de permitir acceso público.
* Configura y **aplica RBAC** (Control de Acceso Basado en Roles) para gestionar los permisos de usuario de manera efectiva.
* Almacena todos los secretos en el **servicio de gestión de secretos del proveedor de nube**.
* Da a las cuentas de servicio solo los **permisos que realmente necesitan**.

## Contribuyendo

***

Antes de realizar cambios, necesitarás configurar Git hooks. Esto ayuda a asegurar que cada commit siga nuestros estándares y pase las verificaciones requeridas.

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

  <Step title="Crear una nueva rama de funcionalidad">
    ```
    git checkout -b feature/your-feature
    ```
  </Step>

  <Step>
    Realiza tus cambios y haz commit usando Conventional Commits.
  </Step>

  <Step>
    Abre un pull request dirigido a la rama `develop`.
  </Step>

  <Step>
    Una vez probado y aprobado, tus cambios se fusionarán en `main`.
  </Step>
</Steps>

Consulta nuestra [Guía de contribución](https://github.com/LerianStudio/midaz-terraform-foundation/blob/main/CONTRIBUTING.md) para aprender más sobre cómo trabajamos juntos y qué esperamos de los contribuyentes.

## Licencia

***

Midaz es un proyecto de código abierto bajo licencia [Elastic License 2.0](https://github.com/LerianStudio/midaz-terraform-foundation/blob/main/LICENSE).

## ¿Necesitas ayuda?

***

* Consulta el README dentro de cada carpeta de componente.
* Busca [issues](https://github.com/LerianStudio/terraform-midaz-foundation/issues) existentes.
* Abre un nuevo issue si es necesario.