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

> Migra tu despliegue de Midaz con Helm de v3.x a v4.x: maneja los cambios incompatibles, los mapeos de configuración y la verificación posterior a la actualización.

## 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 antes de actualizar.
  </Step>

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

## Cambios incompatibles en v4.x

### Cambio de la dependencia de RabbitMQ a Groundhog2k

La dependencia del chart de RabbitMQ cambió de Bitnami a [Groundhog2k](https://Groundhog2k.github.io/helm-charts).

<Danger>
  Este cambio puede provocar **pérdida de datos de PersistentVolumeClaim (PVC)** al actualizar instalaciones existentes, porque el StatefulSet subyacente, los volume mounts y la configuración difieren de la dependencia anterior.
</Danger>

**Notas importantes:**

* El chart de Groundhog2k **requiere una cookie de Erlang válida**. Define `rabbitmq.authentication.erlangCookie.value` como una cadena imprimible de 32 caracteres o más, sin espacios. Si falta o está vacía, RabbitMQ no arranca.
* Si necesitas preservar los datos existentes, respalda y planifica una migración controlada de los PVC y las definiciones antes de actualizar.

**Configuración obligatoria:**

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

<Note>
  Este cambio incompatible solo afecta a los despliegues que usan el RabbitMQ predeterminado del chart (`rabbitmq.enabled: true`). Si ejecutas un RabbitMQ externo o gestionado, no te afecta.
</Note>

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

Midaz pasa a **v3.3.1**.

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

## Funcionalidades nuevas en v4.x

### Imágenes de BitnamiSecure para los servicios de datos principales

Las imágenes predeterminadas de los servicios de datos principales ahora usan los repositorios de BitnamiSecure con el tag `latest`:

| Servicio   | Origen de la imagen | Tag    |
| :--------- | :------------------ | :----- |
| PostgreSQL | BitnamiSecure       | latest |
| MongoDB    | BitnamiSecure       | latest |
| Valkey     | BitnamiSecure       | latest |

Si necesitas fijar una versión específica, sobrescribe el tag en `values.yaml`:

<CodeGroup>
  ```yaml values.yaml theme={null}
  postgresql:
    image:
      tag: "16.2.0"

  mongodb:
    image:
      tag: "7.0.5"

  valkey:
    image:
      tag: "7.2.4"
  ```
</CodeGroup>

### Imagen oficial de NGINX para los microfrontends

El chart reemplazó la dependencia de NGINX de Bitnami por una plantilla interna basada en la imagen oficial `nginx`.

<Note>
  Si personalizaste antes la configuración de NGINX basada en Bitnami, revisa las plantillas nuevas en `templates/console/` y ajusta tus values según corresponda.
</Note>

## Por qué cambiamos las dependencias de Bitnami

Dejamos las dependencias de Bitnami por cambios de política que afectan la estabilidad y las operaciones. Para más contexto, consulta:

* [bitnami/charts#36215](https://github.com/bitnami/charts/issues/36215)
* [bitnami/containers#86191](https://github.com/bitnami/containers/issues/86191)
* [bitnami/containers#83267](https://github.com/bitnami/containers/issues/83267)

## Comando de actualización

<CodeGroup>
  ```bash Shell theme={null}
  helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm --version 4.0.0 -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
  ```
</CodeGroup>

<Warning>
  Debido al cambio de la dependencia de RabbitMQ, el rollback puede requerir intervención manual para restaurar los PVC y los datos. Confirma que tienes respaldos antes de actualizar.
</Warning>

## 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. Exporta las definiciones de RabbitMQ antes de actualizar y restáuralas después.

**Problemas de configuración de NGINX**

* Revisa las plantillas nuevas de NGINX en `templates/console/` y actualiza tus overrides.