> ## 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 v3.x a v5.x

> Actualiza tu despliegue de Midaz con Helm directamente de v3.x a v5.x: resuelve los cambios incompatibles de ambas versiones mayores en una sola migración.

<Warning>
  La orientación sobre CRM y Fees marcada como legacy en esta página aplica solo a un release legacy existente. Midaz v4 despliega el Ledger unificado y sirve CRM y Fees en `/v2`.
</Warning>

<Note>
  Las etiquetas v3.x y v5.x de esta guía se refieren a **releases del Helm chart**, no a versiones de la aplicación Midaz. La línea histórica v5 del chart introdujo el workload de Ledger como una opción. La aplicación Midaz v4 ahora usa el Ledger unificado.
</Note>

El repositorio de Helm conserva un workload `crm.enabled` y el chart `plugin-fees-helm` para releases de aplicación anteriores. Son superficies de compatibilidad legacy, no el modelo de despliegue de Midaz v4.

Si actualizas directamente de v3.x a v5.x, necesitas resolver los cambios incompatibles de ambas versiones.

## 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-v3-backup.yaml
      ```
    </CodeGroup>
  </Step>

  <Step>
    **Crítico**: respalda los datos y las definiciones de RabbitMQ (cambio incompatible de v4.x).
  </Step>

  <Step>
    **Se requiere una decisión para esta migración histórica del chart**: elige el workload de Ledger o los workloads legacy de Onboarding/Transaction.
  </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 que hay que resolver

***

### De v4.x: cambio de la dependencia de RabbitMQ

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

**Configuración obligatoria:**

<CodeGroup>
  ```yaml values.yaml theme={null}
  rabbitmq:
    authentication:
      erlangCookie:
        value: "<32+ printable characters without spaces>"
  ```
</CodeGroup>

### Helm chart v5.x: se introduce el workload de Ledger

<Warning>
  Esta sección describe la transición histórica del chart v5, cuando el workload de Ledger era opcional. La aplicación Midaz v4 ahora requiere el Ledger unificado. No uses la opción legacy para un despliegue nuevo de v4.
</Warning>

**Elige una de estas configuraciones:**

**Opción A: conservar los servicios legacy (migración gradual)**

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

  onboarding:
    enabled: true

  transaction:
    enabled: true

  rabbitmq:
    authentication:
      erlangCookie:
        value: "<32+ printable characters>"
  ```
</CodeGroup>

**Opción B: migrar a Ledger (recomendado)**

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

  onboarding:
    enabled: false

  transaction:
    enabled: false

  rabbitmq:
    authentication:
      erlangCookie:
        value: "<32+ printable characters>"
  ```
</CodeGroup>

Si usas la Opción B, crea secrets nuevos con prefijos específicos de cada módulo:

* `DB_ONBOARDING_PASSWORD`, `DB_TRANSACTION_PASSWORD`
* `MONGO_ONBOARDING_PASSWORD`, `MONGO_TRANSACTION_PASSWORD`

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

## Qué cambia respecto de v3.x

***

| Cambio                    | Versión de origen | Impacto                                                    |
| :------------------------ | :---------------- | :--------------------------------------------------------- |
| RabbitMQ Groundhog2k      | v4.x              | Requiere cookie de Erlang, posible pérdida de datos de PVC |
| Imágenes de BitnamiSecure | v4.x              | PostgreSQL, MongoDB y Valkey usan imágenes endurecidas     |
| NGINX oficial             | v4.x              | Revisa las configuraciones personalizadas de NGINX         |
| Servicio de Ledger        | v5.x              | Servicio unificado nuevo (opcional pero recomendado)       |
| Integración con CRM       | v5.x              | Pasa del namespace midaz-plugins al namespace midaz        |

## Problemas comunes

***

**RabbitMQ no arranca**

* Verifica que configuraste la cookie de Erlang correctamente (32 caracteres imprimibles o más, sin espacios).

**Pérdida de datos de PVC de RabbitMQ**

* Espera que ocurra después del 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 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`

**Los overrides de la Console y de NGINX ya no aplican**

* El chart v7.0.0 eliminó por completo los componentes de la Console y de NGINX. `templates/console/` ya no existe. Elimina de tu archivo de values cualquier override de `console.*` o de NGINX. Son inertes, y el esquema del chart en versiones más nuevas los rechaza.