Midaz Terraform Foundation

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 bróker 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, por lo que debes aprovisionar MongoDB y RabbitMQ tú mismo en GCP.

Por qué usarlo

midaz-terraform-foundation sigue las mejores prácticas de Lerian en seguridad, observabilidad y escalabilidad. Las siguientes tablas 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ápida – aprovisiona todo en minutos con un solo `apply`.	Lenta – toma días configurar y probar.
Estándar de arquitectura	Estandarizado – sigue las mejores prácticas de Lerian.	Impredecible – puede ser incoherente.
Reusabilidad	Alta – admite varios 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 predeterminada	Sí – segura por diseño (VPC aisladas, IAM, secretos, etc.).	No – depende del equipo, lo que aumenta el riesgo de exposición.
Observabilidad integrada	Integrada – se integra con Prometheus, Grafana y más.	Manual – requiere una configuración aparte, que a menudo se omite.
¿Lista para producción?	Sí – alta disponibilidad y autoescalado de fábrica.	Incierto – necesita esfuerzo adicional para reforzarse.

Mantenimiento y soporte

Criterio	Con Midaz Terraform	Configuración manual/scripts ad-hoc
Mantenibilidad	Fácil – modular y versionado para actualizaciones sin complicaciones.	Difícil – los scripts se rompen con facilidad.
Soporte de Lerian	Incluido – verificado y respaldado por Lerian.	Ninguno – no está garantizado.
Tiempo estimado de despliegue	1 día – incluida la validación.	1–2 semanas – con mayor riesgo operativo.

Usa este repositorio para lograr una configuración más rápida y probada.midaz-terraform-foundation sigue los estándares de ingeniería de Lerian.

Qué necesitas

Antes de empezar, confirma que tienes lo siguiente:

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 con un proveedor de nube (AWS, GCP o Azure).
Un bucket de almacenamiento para los archivos de estado de Terraform.
La herramienta de CLI de tu proveedor de nube:
- aws para AWS
- gcloud para GCP
- az para Azure

Integración de CI/CD

Este repositorio proporciona ejemplos de Terraform para desplegar la infraestructura base. No incluye un pipeline de CI/CD. Crea uno que se ajuste a las necesidades de tu proyecto. Si ya tienes un pipeline de CI/CD de Terraform en funcionamiento, sigue estos pasos:

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

Copia las configuraciones de ejemplo relevantes en tu repositorio privado de infraestructura como código.

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

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

Estructura del proyecto

Cada proveedor de nube tiene su propia estructura dentro del repositorio. Cada componente de 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:

VPC/Red
DNS
Base de datos
Redis/Valkey
Clúster de Kubernetes

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

Crea un bucket de S3

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

Habilita el versionado

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

Habilita el cifrado

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

Bloquea el 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

Crea un bucket de GCS

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

Habilita el versionado

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

Azure

Crea un grupo de recursos

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

Crea una cuenta de almacenamiento

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

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

Copia el archivo de ejemplo

cd examples/<provider>/<component>
cp midaz.tfvars-example midaz.tfvars

Reemplaza todos los marcadores de posición del archivo midaz.tfvars con tus valores reales. \i. Este archivo contiene la configuración clave para la instalación de tu infraestructura.

Credenciales de producción y despliegue

En los entornos de producción, debes gestionar las credenciales con cuidado.

Autenticación del proveedor de nube

Cuando ejecutes el script de despliegue de forma local, usa las herramientas de autenticación de la CLI del proveedor de nube en lugar de credenciales sin procesar. Este método es más seguro. Gestiona la rotación de credenciales, el MFA y la renovación de tokens de forma automática. ¿Por qué adoptar este enfoque?

Los tokens se renuevan automáticamente.
Integración de MFA y SSO de fábrica.
Rota y almacena las credenciales de forma segura.
Registro de auditoría completo para los eventos de autenticación.

AWS

Usa la CLI de AWS para asumir un rol.

aws sso login --profile your-profile

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

GCP

Usa la 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 la CLI de Azure.

az login

Para las entidades de servicio, usa el siguiente código:

az login --service-principal

Mejores prácticas de gestión de credenciales

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

AWS: Cómo administrar las claves de acceso de AWS.
GCP: Cómo administrar las claves de cuentas de servicio.
Azure: Mejores prácticas de gestión de identidades.

Prácticas recomendadas

Rota las credenciales con una periodicidad regular.
Usa control de acceso basado en roles (RBAC) siempre que sea posible.
Exige MFA para las cuentas de usuario.
Prefiere credenciales temporales de corta duración.
Monitorea y audita el uso de las credenciales.
Nunca subas credenciales al control de versiones.

Usar el script de despliegue

El script deploy.sh gestiona la secuencia de configuración, resalta los problemas y despliega cada componente en el orden correcto.

Qué hace

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 la configuración del backend tengan valores.
Ejecuta los comandos de Terraform en el orden correcto para cada componente.
Genera logs claros y codificados por color para que sepas qué ocurre en cada paso.

Cómo usarlo

Verifica que se cumplan todos los requisitos previos y que hayas creado tu bucket de estado remoto.

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

Haz que el script sea ejecutable

chmod +x deploy.sh

Ejecuta el script

./deploy.sh

Cuando se te solicite, selecciona tu proveedor de nube.

El script automáticamente

i. Verifica los marcadores de posición restantes. \ii. Ejecuta terraform init, plan y apply para cada componente. \iii. Despliega en el orden correcto y se detiene si algo falla.

Manejo de errores

Diseñamos el script para que falle rápido y ofrezca una explicación. Si algo sale mal, hará lo siguiente:

Se detiene de inmediato si encuentra marcadores de posición que olvidaste completar.
Se cierra si algún comando de Terraform falla.
Te muestra exactamente qué componente falló y en qué paso.

Instalar Midaz

Después de desplegar la infraestructura base, puedes instalar Midaz con Helm. Para obtener más información, consulta la página Desplegar con Helm.

Requisitos previos

Un clúster de Kubernetes en funcionamiento (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

Agrega el repositorio Helm de Midaz:

helm repo add midaz https://lerianstudio.github.io/helm
helm repo update

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

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

Instala Midaz:

helm install midaz midaz/midaz -f values.yaml

Para conocer las opciones de configuración detalladas y la instalación avanzada, consulta el repositorio Helm de Midaz.

Consejos de seguridad

Para mantener segura tu infraestructura de Midaz, sigue estas recomendaciones:

Usa siempre clústeres de Kubernetes privados para limitar la exposición pública.
Accede a la API de Kubernetes mediante VPN en lugar de permitir el acceso público.
Configura y aplica RBAC (control de acceso basado en roles) para gestionar los permisos de los usuarios.
Almacena todos los secretos en el servicio de gestión de secretos del proveedor de nube.
Otorga a las cuentas de servicio solo los permisos que necesitan.

Contribuir

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.

Instala los Git hooks

make hooks

Crea una nueva rama de funcionalidad

git checkout -b feature/your-feature

Haz tus cambios y confírmalos con Conventional Commits.

Abre un pull request dirigido a la rama develop.

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

Consulta nuestra guía de contribución.

Licencia

Midaz Terraform Foundation usa la Apache License 2.0.

¿Necesitas ayuda?

Revisa el README dentro de cada carpeta de componente.
Busca en los issues existentes.
Abre un nuevo issue si es necesario.

Midaz Core

CRM

Fees

Midaz Terraform Foundation

Por qué usarlo

Velocidad y estandarización

Seguridad y observabilidad

Mantenimiento y soporte

Qué necesitas

Integración de CI/CD

Estructura del proyecto

El orden de despliegue importa

Crear el almacenamiento de estado

AWS

Google Cloud Platform

Azure

Requisitos de configuración

Credenciales de producción y despliegue

Autenticación del proveedor de nube

AWS

GCP

Azure

Mejores prácticas de gestión de credenciales

Prácticas recomendadas

Usar el script de despliegue

Qué hace

Cómo usarlo

Manejo de errores

Instalar Midaz

Requisitos previos

Pasos de instalación

Consejos de seguridad

Contribuir

Licencia

¿Necesitas ayuda?

​Por qué usarlo

​Velocidad y estandarización

​Seguridad y observabilidad

​Mantenimiento y soporte

​Qué necesitas

​Integración de CI/CD

​Estructura del proyecto

​El orden de despliegue importa

​Crear el almacenamiento de estado

​AWS

​Google Cloud Platform

​Azure

​Requisitos de configuración

​Credenciales de producción y despliegue

​Autenticación del proveedor de nube

​AWS

​GCP

​Azure

​Mejores prácticas de gestión de credenciales

​Prácticas recomendadas

​Usar el script de despliegue

​Qué hace

​Cómo usarlo

​Manejo de errores

​Instalar Midaz

​Requisitos previos

​Pasos de instalación

​Consejos de seguridad

​Contribuir

​Licencia

​¿Necesitas ayuda?

Por qué usarlo

Velocidad y estandarización

Seguridad y observabilidad

Mantenimiento y soporte

Qué necesitas

Integración de CI/CD

Estructura del proyecto

El orden de despliegue importa

Crear el almacenamiento de estado

AWS

Google Cloud Platform

Azure

Requisitos de configuración

Credenciales de producción y despliegue

Autenticación del proveedor de nube

AWS

GCP

Azure

Mejores prácticas de gestión de credenciales

Prácticas recomendadas

Usar el script de despliegue

Qué hace

Cómo usarlo

Manejo de errores

Instalar Midaz

Requisitos previos

Pasos de instalación

Consejos de seguridad

Contribuir

Licencia

¿Necesitas ayuda?