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

<Steps>
  <Step>
    Respalda los releases de Helm 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 definiciones de RabbitMQ (cambio importante de v4.x).
  </Step>

  <Step>
    **Decisión requerida**: Elige tu estrategia de despliegue - servicio Ledger o Onboarding/Transaction legacy (cambio importante de v5.x).
  </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 a abordar

### De v4.x: cambio de 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 requerida:**

<CodeGroup>
  ```yaml values.yaml theme={null}
  rabbitmq:
    authentication:
      erlangCookie:
        value: "<32+ caracteres imprimibles sin espacios>"
  ```
</CodeGroup>

### De v5.x: nuevo servicio Ledger

<Warning>
  El servicio unificado Ledger está disponible y será obligatorio en una futura versión. Planifica tu estrategia de migración.
</Warning>

**Elige una de estas configuraciones:**

**Opción A: Mantener 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+ caracteres imprimibles>"
  ```
</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+ caracteres imprimibles>"
  ```
</CodeGroup>

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

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

**Problemas de configuración de NGINX**

* La actualización de v4.x reemplazó Bitnami NGINX con plantillas oficiales de NGINX. Revisa las nuevas plantillas en `templates/console/` y actualiza tus overrides.