Migración de v3.x a v5.x

Actualiza tu despliegue Helm de Midaz directamente de v3.x a v5.x — aborda los cambios incompatibles de ambas versiones en una sola migración.

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:

   Shell

   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:

values.yaml

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)

values.yaml

ledger:
  enabled: false

onboarding:
  enabled: true

transaction:
  enabled: true

rabbitmq:
  authentication:
    erlangCookie:
      value: "<32+ caracteres imprimibles>"

Opción B: Migrar a Ledger (recomendado)

values.yaml

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

Shell

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

​

Qué cambia desde v3.x

Cambio	Versión origen	Impacto
RabbitMQ Groundhog2k	v4.x	Requiere cookie de Erlang, posible pérdida de datos de PVC
Imágenes BitnamiSecure	v4.x	PostgreSQL, MongoDB, Valkey usan imágenes endurecidas
NGINX oficial	v4.x	Revisa configuraciones personalizadas de NGINX
Servicio Ledger	v5.x	Nuevo servicio unificado (opcional pero recomendado)
Integración CRM	v5.x	Se 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

Los overrides de Console y NGINX ya no aplican

• El chart v5.0.0 eliminó por completo los componentes Console y NGINX — templates/console/ ya no existe. Elimina cualquier override console.* o de NGINX de tu archivo de values; son inertes y el esquema del chart los rechaza en versiones más recientes.