Migración de v4.x a v5.x

Lista de verificación previa a la actualización

Respalda los releases de Helm existentes:

helm get values -n midaz midaz > midaz-v4-backup.yaml

Decisión requerida: Elige tu estrategia de despliegue (servicio Ledger o Onboarding/Transaction legacy).

Si migras al servicio Ledger, prepara nuevos secretos con prefijos específicos por módulo.

Programa una ventana de mantenimiento.

Cambios importantes en v5.x

Nuevo servicio Ledger disponible

A partir de la versión 5.0, el servicio Ledger está disponible (ledger.enabled: false por defecto). Cuando está habilitado, este servicio combina la funcionalidad de los módulos onboarding y transaction en un solo despliegue.

Los servicios separados onboarding y transaction se convertirán en legacy en una futura versión. El servicio unificado Ledger será obligatorio. Recomendamos encarecidamente planificar tu migración al servicio Ledger.

Valores predeterminados:

Configuración	v4.x (antes)	v5.x (después)
ledger.enabled	N/A	false
onboarding.enabled	true	true (auto-deshabilitado cuando Ledger está habilitado)
transaction.enabled	true	true (auto-deshabilitado cuando Ledger está habilitado)

Impacto al habilitar Ledger:

Los despliegues midaz-onboarding y midaz-transaction serán eliminados.
Se creará un nuevo despliegue midaz-ledger.
Los ingresses redirigirán automáticamente al servicio Ledger (compatibilidad DNS mantenida).
Cambios en la estructura de variables de entorno y secretos (prefijos específicos por módulo).

Actualización de versión de la aplicación

Midaz ha sido actualizado a v3.5.3.

Consulta el changelog de la aplicación para la lista completa de cambios.

Opciones de migración

Opción 1: mantener Onboarding y Transaction (migración gradual)

Agrega lo siguiente a tu override de values para mantener el comportamiento actual:

ledger:
  enabled: false

onboarding:
  enabled: true

transaction:
  enabled: true

Esto te permite actualizar la versión del chart sin cambiar tu infraestructura.

Opción 2: ejecutar todos los servicios simultáneamente (pruebas/período de migración)

Usa el flag oculto migration.allowAllServices para ejecutar los tres servicios durante la migración:

ledger:
  enabled: true

onboarding:
  enabled: true

transaction:
  enabled: true

migration:
  allowAllServices: true

Este modo está destinado solo para pruebas y migración. No lo uses en producción a largo plazo.

Opción 3: migrar a Ledger (recomendado)

Acepta la nueva arquitectura y migra al servicio unificado Ledger:

Antes de actualizar: Asegúrate de que tus bases de datos estén listas (mismas bases de datos, nuevos nombres de variables de entorno).

Actualiza secretos: Crea nuevos secretos con prefijos específicos por módulo (ver Referencia de configuración).

Actualiza: Ejecuta helm upgrade con la nueva versión del chart.

Verifica: Comprueba que el servicio Ledger esté saludable y los ingresses funcionen.

ledger:
  enabled: true

onboarding:
  enabled: false

transaction:
  enabled: false

Nuevas características en v5.x

Servicio Ledger unificado

Un nuevo servicio Ledger que combina los módulos onboarding y transaction en un solo despliegue. Características clave:

Endpoint HTTP único (puerto 3000 por defecto)
Configuraciones de base de datos separadas para cada módulo
Conexiones compartidas de Redis y RabbitMQ
Nuevo Balance Sync Worker para procesamiento en segundo plano

Nuevas variables de entorno:

# Balance Sync Worker
BALANCE_SYNC_WORKER_ENABLED: "false"
BALANCE_SYNC_MAX_WORKERS: "5"

Estas variables de entorno han sido renombradas en versiones posteriores. Los nombres actuales de las variables son: BALANCE_SYNC_BATCH_SIZE, BALANCE_SYNC_FLUSH_TIMEOUT_MS y BALANCE_SYNC_POLL_INTERVAL_MS. Consulta la Referencia de Configuración para los valores predeterminados actuales.

Redirección de Ingress a Ledger

Cuando Ledger está habilitado, los ingresses existentes redirigen automáticamente el tráfico al servicio Ledger, manteniendo compatibilidad DNS.

ledger.enabled	migration.allowAllServices	destino ingress onboarding	destino ingress transaction
false	false (por defecto)	midaz-onboarding	midaz-transaction
true	false (por defecto)	midaz-ledger	midaz-ledger
true	true	midaz-onboarding	midaz-transaction

Integración del servicio CRM

El servicio CRM ahora está disponible como componente integrado, moviéndose de midaz-plugins al namespace midaz.

Para más detalles, consulta la Documentación de CRM.

Migración desde plugin-crm:

Despliega el nuevo CRM en el namespace midaz:

crm:
  enabled: true
  configmap:
    MONGO_HOST: "midaz-mongodb"
    MONGO_NAME: "crm"

Migra tus datos del antiguo MongoDB al nuevo (si usas bases de datos separadas).

Actualiza tu ingress/DNS para apuntar al nuevo servicio CRM.

Elimina el antiguo release plugin-crm del namespace midaz-plugins.

Comando de actualización

helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm --version 5.x.x -n midaz

Procedimiento de reversión

# Listar historial de releases
helm history midaz -n midaz

# Revertir a la versión anterior
helm rollback midaz <REVISION> -n midaz

# O deshabilitar Ledger explícitamente
helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
  --set ledger.enabled=false \
  --set onboarding.enabled=true \
  --set transaction.enabled=true \
  -n midaz

Problemas comunes

El servicio Ledger falla al iniciar

Verifica que todas las variables de entorno y secretos específicos por módulo estén configurados con los nuevos prefijos (DB_ONBOARDING_*, DB_TRANSACTION_*, etc.).

Ingress no enruta a Ledger

Asegúrate de que ledger.enabled: true y migration.allowAllServices no esté configurado como true.

Secretos faltantes después de habilitar Ledger

Crea nuevos secretos con prefijos por módulo:
- DB_ONBOARDING_PASSWORD en lugar de DB_PASSWORD
- DB_TRANSACTION_PASSWORD en lugar de DB_PASSWORD
- MONGO_ONBOARDING_PASSWORD en lugar de MONGO_PASSWORD
- MONGO_TRANSACTION_PASSWORD en lugar de MONGO_PASSWORD

​Lista de verificación previa a la actualización

​Cambios importantes en v5.x

​Nuevo servicio Ledger disponible

​Actualización de versión de la aplicación

​Opciones de migración

​Opción 1: mantener Onboarding y Transaction (migración gradual)

​Opción 2: ejecutar todos los servicios simultáneamente (pruebas/período de migración)

​Opción 3: migrar a Ledger (recomendado)

​Nuevas características en v5.x

​Servicio Ledger unificado

​Redirección de Ingress a Ledger

​Integración del servicio CRM

​Comando de actualización

​Procedimiento de reversión

​Problemas comunes

Lista de verificación previa a la actualización

Cambios importantes en v5.x

Nuevo servicio Ledger disponible

Actualización de versión de la aplicación

Opciones de migración

Opción 1: mantener Onboarding y Transaction (migración gradual)

Opción 2: ejecutar todos los servicios simultáneamente (pruebas/período de migración)

Opción 3: migrar a Ledger (recomendado)

Nuevas características en v5.x

Servicio Ledger unificado

Redirección de Ingress a Ledger

Integración del servicio CRM

Comando de actualización

Procedimiento de reversión

Problemas comunes