Saltar al contenido principal
Esta guía te acompaña durante la actualización de tu despliegue de Midaz Helm a la última versión (v5.x.x). Encontrarás un inicio rápido para operadores experimentados, seguido de rutas de migración desde versiones anteriores, cambios importantes detallados y verificaciones post-actualización.
¿Necesitas un repaso sobre la instalación de Midaz con Helm? Consulta la guía Usando Helm en Estrategias de despliegue antes de comenzar tu actualización.

​
Inicio rápido

​
1. Verifica los requisitos previos

  • Helm v3.8+ instalado y disponible (helm version).
  • Kubernetes v1.20+ clúster en ejecución.
  • Respaldo de tu instalación existente.

​
2. Identifica tu versión actual

helm list -n midaz

​
3. Ejecuta el comando de actualización

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

​
4. Verifica la actualización

helm list -n midaz
kubectl get pods -n midaz

​
Compatibilidad de versiones

Componentev3.xv4.xv5.x
Kubernetes1.20+1.20+1.20+
Helm3.8+3.8+3.8+
PostgreSQL13+13+13+
MongoDB4.4+4.4+4.4+
Valkey7.x7.x7.x

​
Elige tu ruta de migración

Selecciona tu versión actual del chart de Helm para ver los pasos de migración relevantes:

​
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.1.
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 de Ledger abajo).
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"

​
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

​
Referencia de configuración del servicio Ledger

El servicio Ledger usa configuraciones de base de datos específicas por módulo: 
ledger:
  enabled: false
  name: "ledger"
  replicaCount: 1

  image:
    repository: lerianstudio/midaz-ledger
    tag: ""  # Por defecto Chart.AppVersion
    pullPolicy: IfNotPresent

  configmap:
    # Configuración de la aplicación
    ENV_NAME: "production"
    LOG_LEVEL: "debug"
    SERVER_PORT: "3000"
    SERVER_ADDRESS: ":3000"

    # Configuración de autenticación
    PLUGIN_AUTH_ENABLED: "false"
    PLUGIN_AUTH_HOST: ""

    # Configuración de contabilidad
    ACCOUNT_TYPE_VALIDATION: ""
    TRANSACTION_ROUTE_VALIDATION: ""

    # PostgreSQL - Módulo Onboarding
    DB_ONBOARDING_HOST: "midaz-postgresql-primary.midaz.svc.cluster.local."
    DB_ONBOARDING_USER: "midaz"
    DB_ONBOARDING_NAME: "onboarding"
    DB_ONBOARDING_PORT: "5432"
    DB_ONBOARDING_SSLMODE: "disable"
    DB_ONBOARDING_REPLICA_HOST: "midaz-postgresql-replication.midaz.svc.cluster.local."

    # PostgreSQL - Módulo Transaction
    DB_TRANSACTION_HOST: "midaz-postgresql-primary.midaz.svc.cluster.local."
    DB_TRANSACTION_USER: "midaz"
    DB_TRANSACTION_NAME: "transaction"
    DB_TRANSACTION_PORT: "5432"
    DB_TRANSACTION_SSLMODE: "disable"
    DB_TRANSACTION_REPLICA_HOST: "midaz-postgresql-replication.midaz.svc.cluster.local."

    # MongoDB - Módulo Onboarding
    MONGO_ONBOARDING_HOST: "midaz-mongodb.midaz.svc.cluster.local."
    MONGO_ONBOARDING_NAME: "onboarding"
    MONGO_ONBOARDING_USER: "midaz"
    MONGO_ONBOARDING_PORT: "27017"

    # MongoDB - Módulo Transaction
    MONGO_TRANSACTION_HOST: "midaz-mongodb.midaz.svc.cluster.local."
    MONGO_TRANSACTION_NAME: "transaction"
    MONGO_TRANSACTION_USER: "midaz"
    MONGO_TRANSACTION_PORT: "27017"

    # Redis (compartido)
    REDIS_HOST: "midaz-valkey-primary.midaz.svc.cluster.local.:6379"

    # RabbitMQ (compartido)
    RABBITMQ_HOST: "midaz-rabbitmq.midaz.svc.cluster.local."

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

  secrets:
    # Módulo Onboarding
    DB_ONBOARDING_PASSWORD: ""
    DB_ONBOARDING_REPLICA_PASSWORD: ""
    MONGO_ONBOARDING_PASSWORD: ""

    # Módulo Transaction
    DB_TRANSACTION_PASSWORD: ""
    DB_TRANSACTION_REPLICA_PASSWORD: ""
    MONGO_TRANSACTION_PASSWORD: ""

    # Compartidos
    REDIS_PASSWORD: ""
    RABBITMQ_DEFAULT_PASS: ""
    RABBITMQ_CONSUMER_PASS: ""

​
Soporte para secretos externos

ledger:
  useExistingSecret: true
  existingSecretName: <nombre-secreto-existente>

​
Referencia de flags de despliegue

FlagPor defectoDescripción
ledger.enabledfalseHabilita el servicio Ledger unificado
onboarding.enabledtrueHabilita onboarding (auto-deshabilitado cuando Ledger está habilitado)
transaction.enabledtrueHabilita transaction (auto-deshabilitado cuando Ledger está habilitado)
migration.allowAllServicesfalseFlag oculto para permitir todos los servicios simultáneamente

​
Recomendación para producción

No recomendamos usar las dependencias predeterminadas del chart de Helm de Midaz (bases de datos, caché y broker de mensajes) en entornos de producción. Para despliegues de grado de producción, sigue nuestras mejores prácticas para operar estas dependencias con seguridad, observabilidad, respaldos, recuperación ante desastres y SLOs adecuados.

​
Verificación post-actualización

​
1. Verificar estado de pods

kubectl get pods -n midaz
Todos los pods deben estar Running y READY.

​
2. Verificar servicios

kubectl get svc -n midaz

​
3. Revisar logs

# Si usas el servicio Ledger (v5.x)
kubectl logs -n midaz deployment/midaz-ledger

# Si usas servicios legacy
kubectl logs -n midaz deployment/midaz-onboarding
kubectl logs -n midaz deployment/midaz-transaction

# Revisar logs de RabbitMQ (importante para actualizaciones v4.x+)
kubectl logs -n midaz statefulset/midaz-rabbitmq

# Revisar logs de CRM (si está habilitado)
kubectl logs -n midaz deployment/midaz-crm

​
4. Verificar enrutamiento de ingress (v5.x con Ledger)

kubectl get ingress -n midaz
kubectl describe ingress midaz-onboarding -n midaz
kubectl describe ingress midaz-transaction -n midaz

​
Procedimiento general de reversión

Si encuentras problemas después de cualquier actualización: 
# Listar historial de releases
helm history midaz -n midaz

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

# Verificar reversión
helm list -n midaz
kubectl get pods -n midaz