Saltar al contenido principal

​
Migrando de v4.x a v5.x

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

1
Respalda los releases de Helm existentes:
helm get values -n midaz midaz > midaz-v4-backup.yaml
2
Decisión requerida: Elige tu estrategia de despliegue (servicio Ledger o Onboarding/Transaction legacy).
3
Si migras al servicio Ledger, prepara nuevos secretos con prefijos específicos por módulo.
4
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ónv4.x (antes)v5.x (después)
ledger.enabledN/Afalse
onboarding.enabledtruetrue (auto-deshabilitado cuando Ledger está habilitado)
transaction.enabledtruetrue (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:
1
Antes de actualizar: Asegúrate de que tus bases de datos estén listas (mismas bases de datos, nuevos nombres de variables de entorno).
2
Actualiza secretos: Crea nuevos secretos con prefijos específicos por módulo (ver Referencia de configuración).
3
Actualiza: Ejecuta helm upgrade con la nueva versión del chart.
4
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.enabledmigration.allowAllServicesdestino ingress onboardingdestino ingress transaction
falsefalse (por defecto)midaz-onboardingmidaz-transaction
truefalse (por defecto)midaz-ledgermidaz-ledger
truetruemidaz-onboardingmidaz-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:
1
Despliega el nuevo CRM en el namespace midaz:
crm:
  enabled: true
  configmap:
    MONGO_HOST: "midaz-mongodb"
    MONGO_NAME: "crm"
2
Migra tus datos del antiguo MongoDB al nuevo (si usas bases de datos separadas).
3
Actualiza tu ingress/DNS para apuntar al nuevo servicio CRM.
4
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