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

> Migra tu despliegue Helm de Midaz de v3.x a v4.x — gestiona cambios incompatibles, mapeos de configuración y verificación posterior.

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

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

## Cambios importantes en v4.x

### Cambio de dependencia de RabbitMQ a Groundhog2k

La dependencia del chart de RabbitMQ ha sido reemplazada 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, montajes de volumen y configuración difieren de la dependencia anterior.
</Danger>

**Notas importantes:**

* El chart de Groundhog2k **requiere una cookie de Erlang válida**. Configura `rabbitmq.authentication.erlangCookie.value` con una cadena imprimible de 32+ caracteres sin espacios. Si falta o está vacía, RabbitMQ fallará al iniciar.
* Si necesitas preservar datos existentes, respalda y planifica una migración controlada de PVCs y definiciones antes de actualizar.

**Configuración requerida:**

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

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

### Actualización de versión de la aplicación

Midaz ha sido actualizado a **v3.3.1**.

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

## Nuevas características en v4.x

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

Las imágenes predeterminadas para servicios de datos principales ahora usan los repositorios BitnamiSecure con la etiqueta `latest`:

| Servicio   | Fuente de imagen | Etiqueta |
| :--------- | :--------------- | :------- |
| PostgreSQL | BitnamiSecure    | latest   |
| MongoDB    | BitnamiSecure    | latest   |
| Valkey     | BitnamiSecure    | latest   |

Si requieres fijar una versión específica, anula la etiqueta 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 NGINX para microfrontends

La dependencia anterior de NGINX de Bitnami fue reemplazada con una plantilla interna basada en la imagen oficial `nginx`.

<Note>
  Si previamente personalizaste la configuración de NGINX basada en Bitnami, revisa las nuevas plantillas en `templates/console/` y ajusta tus valores en consecuencia.
</Note>

## Por qué cambiamos las dependencias de Bitnami

Nos alejamos de las dependencias de Bitnami debido a cambios de políticas 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 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
  ```
</CodeGroup>

<Warning>
  Debido al cambio de dependencia de RabbitMQ, la reversión puede requerir intervención manual para restaurar PVCs y datos. Asegúrate de tener respaldos antes de actualizar.
</Warning>

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

**Problemas de configuración de NGINX**

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