Saltar al contenido principal

​
Migrando de v3.x a v5.x (saltando v4.x)

Si estás actualizando directamente de v3.x a v5.x, necesitas abordar los cambios importantes de ambas versiones.

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

1
Respalda los releases de Helm existentes:
helm get values -n midaz midaz > midaz-v3-backup.yaml
2
Crítico: Respalda los datos y definiciones de RabbitMQ (cambio importante de v4.x).
3
Decisión requerida: Elige tu estrategia de despliegue - servicio Ledger o Onboarding/Transaction legacy (cambio importante de v5.x).
4
Si migras al servicio Ledger, prepara nuevos secretos con prefijos específicos por módulo.
5
Programa una ventana de mantenimiento.

​
Cambios importantes a abordar

​
De v4.x: cambio de dependencia de RabbitMQ

La dependencia del chart de RabbitMQ cambió de Bitnami a Groundhog2k. Esto puede provocar pérdida de datos de PVC. Respalda los datos de RabbitMQ antes de actualizar.
Configuración requerida: 
rabbitmq:
  authentication:
    erlangCookie:
      value: "<32+ caracteres imprimibles sin espacios>"

​
De v5.x: nuevo servicio Ledger

El servicio unificado Ledger está disponible y será obligatorio en una futura versión. Planifica tu estrategia de migración.
Elige una de estas configuraciones: Opción A: Mantener servicios legacy (migración gradual) 
ledger:
  enabled: false

onboarding:
  enabled: true

transaction:
  enabled: true

rabbitmq:
  authentication:
    erlangCookie:
      value: "<32+ caracteres imprimibles>"
Opción B: Migrar a Ledger (recomendado) 
ledger:
  enabled: true

onboarding:
  enabled: false

transaction:
  enabled: false

rabbitmq:
  authentication:
    erlangCookie:
      value: "<32+ caracteres imprimibles>"
Si usas la Opción B, crea nuevos secretos con prefijos específicos por módulo:
  • DB_ONBOARDING_PASSWORD, DB_TRANSACTION_PASSWORD
  • MONGO_ONBOARDING_PASSWORD, MONGO_TRANSACTION_PASSWORD

​
Comando de actualización

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

​
Qué cambia desde v3.x

CambioVersión origenImpacto
RabbitMQ Groundhog2kv4.xRequiere cookie de Erlang, posible pérdida de datos de PVC
Imágenes BitnamiSecurev4.xPostgreSQL, MongoDB, Valkey usan imágenes endurecidas
NGINX oficialv4.xRevisa configuraciones personalizadas de NGINX
Servicio Ledgerv5.xNuevo servicio unificado (opcional pero recomendado)
Integración CRMv5.xSe mueve de midaz-plugins al namespace midaz

​
Problemas comunes

RabbitMQ falla al iniciar
  • Asegúrate de que la cookie de Erlang esté configurada correctamente (32+ caracteres imprimibles, sin espacios).
Pérdida de datos de PVC de RabbitMQ
  • Esto es esperado debido al cambio de dependencia de v4.x de Bitnami a Groundhog2k. Exporta las definiciones de RabbitMQ antes de actualizar y restáuralas después.
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
Problemas de configuración de NGINX
  • La actualización de v4.x reemplazó Bitnami NGINX con plantillas oficiales de NGINX. Revisa las nuevas plantillas en templates/console/ y actualiza tus overrides.