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 de ejemplos de Terraform listos para usar. Úsalos para crear la infraestructura base que Midaz necesita en AWS, GCP o Azure. Los ejemplos siguen las mejores prácticas de cada proveedor de nube.

Esta infraestructura base incluye:

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

Las plantillas aprovisionan una base de datos compatible con MongoDB y un broker de mensajes solo en algunos proveedores. AWS usa Amazon DocumentDB y Amazon MQ (RabbitMQ). Azure usa Cosmos DB con la API de MongoDB. GCP no tiene un equivalente administrado, así que debes aprovisionar MongoDB y RabbitMQ por tu cuenta en GCP.

​

Por qué usarlo

---

El aprovisionamiento de infraestructura no debería ser lento, inconsistente ni propenso a errores. midaz-terraform-foundation sigue las mejores prácticas de Lerian para seguridad, observabilidad y escalabilidad. Las tablas siguientes lo comparan con una configuración manual 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.

Usa este repositorio para una configuración más rápida y probada.

midaz-terraform-foundation sigue los estándares de ingeniería de Lerian. Te ayuda a desplegar más rápido y evitar errores comunes de configuración.

​

Qué necesitarás

---

Antes de comenzar, asegúrate de tener:

• Terraform v1.5.0 o superior — los ejemplos de AWS RDS y Route 53 requieren >= 1.5.0; los demás módulos requieren >= 1.0.0
• 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. Crea uno que se ajuste a las necesidades de tu proyecto.

¿Ya ejecutas un pipeline CI/CD de Terraform? Sigue estos pasos:

1. Omite el script de despliegue. Es solo para uso local.

2. Copia las configuraciones de ejemplo relevantes en tu repositorio privado de Infraestructura como Código.

3. Integra las configuraciones de Terraform en tu pipeline según sea necesario.

4. Usa la gestión de secretos integrada de tu plataforma CI/CD para manejar credenciales de forma segura.

​

Estructura del proyecto

---

Cada proveedor de nube tiene su propia estructura en el repositorio. Cada componente de la infraestructura sigue un diseño modular y controlado. Puedes desplegar solo los componentes que necesitas, o toda la base.

.
├── examples/
    ├── aws/
    │   ├── vpc/
    │   ├── route53/
    │   ├── rds/
    │   ├── documentdb/
    │   ├── amazonmq/
    │   ├── valkey/
    │   └── eks/
    ├── gcp/
    │   ├── vpc/
    │   ├── cloud-dns/
    │   ├── cloud-sql/
    │   ├── valkey/
    │   └── gke/
    └── azure/
        ├── network/
        ├── dns/
        ├── database/
        ├── cosmosdb/
        ├── redis/
        └── aks/

​

El orden de despliegue importa

Para evitar errores y conectar todo correctamente, despliega los componentes en este orden:

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. Antes de usar estas plantillas, crea un bucket de almacenamiento para los archivos de estado de Terraform.

​

AWS

Reemplaza REGION y UNIQUE_BUCKET_NAME con tus propios valores.

1. Crear un bucket S3

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

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

   aws s3api put-bucket-encryption \
       --bucket UNIQUE_BUCKET_NAME \
       --server-side-encryption-configuration \
       '{"Rules":[{"ApplyServerSideEncryptionByDefault":{"SSEAlgorithm":"AES256"}}]}'
   
4. 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}'
   

​

Google Cloud Platform

1. Crear un bucket GCS

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

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

​

Azure

1. Crear un grupo de recursos

   az group create --name terraform-state-rg --location eastus
   
2. Crear una cuenta de almacenamiento

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

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

​

Requisitos de configuración

---

Antes de desplegar la infraestructura, crea y configura el archivo de variables para cada componente de nube:

1. Copiar el archivo de ejemplo

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

​

Credenciales de producción y despliegue

---

En entornos de producción, debes gestionar las credenciales con cuidado. Esta guía muestra cómo manejar las credenciales de forma segura.

​

Autenticación del proveedor de nube

Cuando ejecutas el script de despliegue localmente, usa las herramientas de autenticación CLI del proveedor de nube en lugar de credenciales sin procesar. Este método es más seguro. Gestiona la rotación de credenciales, MFA y actualización de tokens automáticamente.

¿Por qué adoptar este enfoque?

• Los tokens se actualizan automáticamente.
• Integración de MFA y SSO lista para usar.
• Rota y almacena las credenciales 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.
• GCP: Gestión de claves de cuenta de servicio.
• Azure: Mejores prácticas de gestión de identidad.

​

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 el uso de 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 y despliega cada componente 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 tengan valores.
• 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

1. Asegúrate de que todos los requisitos previos estén completos y de que creaste tu bucket de estado remoto.

2. Completa todos los marcadores de posición en los archivos backend.tf.

3. Hacer el script ejecutable

   chmod +x deploy.sh
   
4. Ejecutar el script

   ./deploy.sh
   
5. Cuando se te solicite, selecciona tu proveedor de nube.

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

​

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.

​

Requisitos previos

• Un clúster de Kubernetes en ejecución (EKS, GKE o AKS).
• kubectl configurado para acceder al clúster.
• Helm v3.x instalado.
• Acceso al repositorio Helm de Midaz.

​

Pasos de instalación

1. Agrega el repositorio Helm de Midaz:

   helm repo add midaz https://lerianstudio.github.io/helm
   helm repo update
   
2. Crea un archivo de valores (values.yaml) con tu configuración:

   # Ejemplo values.yaml
   # Deshabilitar las dependencias incluidas
   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>"
   
3. Instalar Midaz:

   helm install midaz midaz/midaz -f values.yaml
   

Para opciones de configuración detalladas y configuración avanzada, consulta el Repositorio Helm de Midaz.

​

Consejos de seguridad

---

La nube trae oportunidades y responsabilidades. Para mantener segura tu infraestructura de Midaz, sigue estas recomendaciones:

• 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 hacer cualquier cambio, configura los Git hooks. Los Git hooks aseguran que cada commit siga nuestros estándares y pase las verificaciones requeridas.

1. Instalar los Git hooks

   make hooks
   
2. Crear una nueva rama de funcionalidad

   git checkout -b feature/your-feature
   
3. Realiza tus cambios y haz commit usando Conventional Commits.

4. Abre un pull request dirigido a la rama develop.

5. Después de que las pruebas pasen y un maintainer apruebe, tus cambios se fusionan en main.

Consulta nuestra Guía de contribución para aprender más sobre cómo trabajamos juntos y qué esperamos de los contribuyentes.

​

Licencia

---

Midaz Terraform Foundation usa la Apache License 2.0.

​

¿Necesitas ayuda?

---

• Consulta el README dentro de cada carpeta de componente.
• Busca issues existentes.
• Abre un nuevo issue si es necesario.