> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrar de v4.x a v5.x

> Migra tu despliegue de Midaz con Helm de v4.x a v5.x: sigue la lista de verificación previa a la actualización, ejecuta las migraciones y valida el release nuevo.

<Warning>
  Esta migración del chart de v4.x → v5.x es histórica. Consérvala para releases legacy existentes. No es orientación de despliegue para Midaz v4.
</Warning>

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

***

<Steps>
  <Step>
    Respalda los Helm releases existentes:

    <CodeGroup>
      ```bash Shell theme={null}
      helm get values -n midaz midaz > midaz-v4-backup.yaml
      ```
    </CodeGroup>
  </Step>

  <Step>
    **Se requiere una decisión**: elige tu estrategia de despliegue (servicio de Ledger o los Onboarding/Transaction legacy).
  </Step>

  <Step>
    Si migras al servicio de Ledger, prepara secrets nuevos con prefijos específicos de cada módulo.
  </Step>

  <Step>
    Programa una ventana de mantenimiento.
  </Step>
</Steps>

## Cambios incompatibles en v5.x

***

### Servicio de Ledger nuevo disponible

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

<Warning>
  Los servicios separados `onboarding` y `transaction` pasarán a ser legacy en un release futuro. El servicio de Ledger unificado pasará a ser obligatorio. Recomendamos planificar tu migración al servicio de Ledger.
</Warning>

**Valores predeterminados:**

| Ajuste              | v4.x (antes)  | v5.x (después)                                                      |
| :------------------ | :------------ | :------------------------------------------------------------------ |
| ledger.enabled      | no disponible | false                                                               |
| onboarding.enabled  | true          | true (se deshabilita automáticamente cuando ledger está habilitado) |
| transaction.enabled | true          | true (se deshabilita automáticamente cuando ledger está habilitado) |

**Impacto al habilitar Ledger:**

* El chart elimina los deployments `midaz-onboarding` y `midaz-transaction`.
* El chart crea un deployment `midaz-ledger` nuevo.
* Los ingresses redirigen automáticamente al servicio de Ledger (se mantiene la compatibilidad de DNS).
* La estructura de las variables de entorno y los secrets cambia (prefijos específicos de cada módulo).

### Cambio de versión de la aplicación

Los parches posteriores de v5.x suben la versión de la aplicación. Revisa el `Chart.yaml` de la versión exacta del chart que tomas como objetivo.

<Note>
  Consulta el [changelog de la aplicación](https://github.com/LerianStudio/midaz/blob/main/CHANGELOG.md) para ver la lista completa de cambios.
</Note>

## Opciones de migración

***

### Opción 1: seguir usando Onboarding y Transaction (migración gradual)

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

<CodeGroup>
  ```yaml values.yaml theme={null}
  ledger:
    enabled: false

  onboarding:
    enabled: true

  transaction:
    enabled: true
  ```
</CodeGroup>

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

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

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

<CodeGroup>
  ```yaml values.yaml theme={null}
  ledger:
    enabled: true

  onboarding:
    enabled: true

  transaction:
    enabled: true

  migration:
    allowAllServices: true
  ```
</CodeGroup>

<Warning>
  Usa este modo solo para pruebas y migración. No lo uses en producción a largo plazo.
</Warning>

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

Acepta la arquitectura nueva y migra al servicio de Ledger unificado:

<Steps>
  <Step>
    **Antes de actualizar**: confirma que tus bases de datos están listas (las mismas bases de datos, nombres de variables de entorno nuevos).
  </Step>

  <Step>
    **Actualiza los secrets**: crea secrets nuevos con prefijos específicos de cada módulo (consulta [Referencia de configuración](/es/platform/deploy/midaz/midaz-configuration-reference)).
  </Step>

  <Step>
    **Actualiza**: ejecuta helm upgrade con la versión nueva del chart.
  </Step>

  <Step>
    **Verifica**: revisa que el servicio de Ledger está sano y que los ingresses funcionan.
  </Step>
</Steps>

<CodeGroup>
  ```yaml values.yaml theme={null}
  ledger:
    enabled: true

  onboarding:
    enabled: false

  transaction:
    enabled: false
  ```
</CodeGroup>

## Funcionalidades nuevas en v5.x

***

### Servicio de Ledger unificado

Un servicio de Ledger nuevo que combina los módulos `onboarding` y `transaction` en un solo deployment.

**Características principales:**

* Un solo endpoint HTTP (puerto 3000 de forma predeterminada)
* Configuraciones de base de datos separadas para cada módulo
* Conexiones compartidas de Redis y RabbitMQ
* Un Balance Sync Worker nuevo para el procesamiento en segundo plano

**Variables de entorno nuevas:**

<CodeGroup>
  ```yaml values.yaml theme={null}
  # Balance Sync Worker
  BALANCE_SYNC_WORKER_ENABLED: "false"
  BALANCE_SYNC_MAX_WORKERS: "5"
  ```
</CodeGroup>

<Note>
  `BALANCE_SYNC_WORKER_ENABLED` y `BALANCE_SYNC_MAX_WORKERS` siguen siendo los nombres actuales. No los elimines. Las versiones posteriores del chart **agregan** tres claves más: `BALANCE_SYNC_BATCH_SIZE` (predeterminado `50`), `BALANCE_SYNC_FLUSH_TIMEOUT_MS` (predeterminado `500`) y `BALANCE_SYNC_POLL_INTERVAL_MS` (predeterminado `50`).
</Note>

### Redirección del ingress hacia Ledger

Cuando habilitas Ledger, los ingresses existentes redirigen el tráfico automáticamente al servicio de Ledger y mantienen la compatibilidad de DNS.

| ledger.enabled | migration.allowAllServices | destino del ingress de onboarding | destino del ingress de transaction |
| :------------- | :------------------------- | :-------------------------------- | :--------------------------------- |
| false          | false (predeterminado)     | midaz-onboarding                  | midaz-transaction                  |
| true           | false (predeterminado)     | midaz-ledger                      | midaz-ledger                       |
| true           | true                       | midaz-onboarding                  | midaz-transaction                  |

### Integración del servicio de CRM

El chart despliega CRM en el namespace `midaz`, no en `midaz-plugins`.

<Tip>
  Para más detalles, consulta la [documentación de CRM](/es/products/midaz/crm/crm-overview).
</Tip>

**Migración desde un release independiente de CRM:**

<Steps>
  <Step>
    Despliega el CRM nuevo en el namespace midaz:

    <CodeGroup>
      ```yaml values.yaml theme={null}
      crm:
        enabled: true
        configmap:
          MONGO_HOST: "midaz-mongodb"
          MONGO_NAME: "crm"
      ```
    </CodeGroup>
  </Step>

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

  <Step>
    Actualiza tu ingress/DNS para que apunte al servicio de CRM nuevo.
  </Step>

  <Step>
    Elimina el release antiguo de CRM de `midaz-plugins`.
  </Step>
</Steps>

## Comando de actualización

***

<CodeGroup>
  ```bash Shell theme={null}
  helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm --version 5.x.x -n midaz
  ```
</CodeGroup>

## Procedimiento de rollback

***

<CodeGroup>
  ```bash Shell theme={null}
  # List release history
  helm history midaz -n midaz

  # Rollback to previous version
  helm rollback midaz <REVISION> -n midaz

  # Or explicitly disable ledger
  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
  ```
</CodeGroup>

## Problemas comunes

***

**El servicio de Ledger no arranca**

* Verifica que configuras todas las variables de entorno y los secrets específicos de cada módulo con los prefijos nuevos (`DB_ONBOARDING_*`, `DB_TRANSACTION_*`, etc.).

**El ingress no enruta hacia Ledger**

* Define `ledger.enabled: true`. No definas `migration.allowAllServices` como `true`.

**Faltan secrets después de habilitar Ledger**

* Crea secrets nuevos con prefijos de 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`