> ## 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.

# Migración de v4.x a v5.x

> Migra tu despliegue Helm de Midaz de v4.x a v5.x — sigue la lista previa, ejecuta migraciones y valida el nuevo release.

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

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

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

  <Step>
    **Decisión requerida**: Elige tu estrategia de despliegue (servicio Ledger o Onboarding/Transaction legacy).
  </Step>

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

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

## 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.

<Warning>
  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.
</Warning>

**Valores predeterminados:**

| Configuración       | v4.x (antes) | v5.x (después)                                          |
| :------------------ | :----------- | :------------------------------------------------------ |
| ledger.enabled      | N/A          | false                                                   |
| onboarding.enabled  | true         | true (auto-deshabilitado cuando Ledger está habilitado) |
| transaction.enabled | true         | true (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**.

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

## 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:

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

  onboarding:
    enabled: true

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

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:

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

  onboarding:
    enabled: true

  transaction:
    enabled: true

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

<Warning>
  Este modo está destinado 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 nueva arquitectura y migra al servicio unificado Ledger:

<Steps>
  <Step>
    **Antes de actualizar**: Asegúrate de que tus bases de datos estén listas (mismas bases de datos, nuevos nombres de variables de entorno).
  </Step>

  <Step>
    **Actualiza secretos**: Crea nuevos secretos con prefijos específicos por módulo (ver [Referencia de configuración](/es/platform/helm/midaz/midaz-configuration-reference)).
  </Step>

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

  <Step>
    **Verifica**: Comprueba que el servicio Ledger esté saludable y los ingresses funcionen.
  </Step>
</Steps>

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

  onboarding:
    enabled: false

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

## 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:**

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

<Note>
  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.
</Note>

### 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.enabled | migration.allowAllServices | destino ingress onboarding | destino ingress transaction |
| :------------- | :------------------------- | :------------------------- | :-------------------------- |
| false          | false (por defecto)        | midaz-onboarding           | midaz-transaction           |
| true           | false (por defecto)        | midaz-ledger               | midaz-ledger                |
| true           | true                       | midaz-onboarding           | midaz-transaction           |

### Integración del servicio CRM

El servicio CRM ahora está disponible como componente integrado, moviéndose de `midaz-plugins` al namespace `midaz`.

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

**Migración desde plugin-crm:**

<Steps>
  <Step>
    Despliega el nuevo CRM 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 antiguo MongoDB al nuevo (si usas bases de datos separadas).
  </Step>

  <Step>
    Actualiza tu ingress/DNS para apuntar al nuevo servicio CRM.
  </Step>

  <Step>
    Elimina el antiguo release plugin-crm del namespace 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 reversión

<CodeGroup>
  ```bash Shell theme={null}
  # 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
  ```
</CodeGroup>

## 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`