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

# Guía de actualización de Midaz con Helm

> Actualiza tu despliegue de Midaz con Helm: inicio rápido, los releases con cambios incompatibles entre v5 y v8, actualizaciones de plugins y verificaciones posteriores.

<Warning>
  La orientación sobre CRM y Fees marcada como legacy en esta página se aplica solo a los releases legacy que ya existen. Midaz v4 despliega el Ledger unificado y sirve CRM y Fees en `/v2`.
</Warning>

El repositorio de Helm conserva una carga de trabajo `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.

Esta guía te lleva por la actualización de tu despliegue de Midaz con Helm a la línea de charts actual.

<Tip>
  Para repasar la instalación de Midaz con Helm, consulta la guía [Instalar Midaz con Helm](/es/platform/deploy/midaz/midaz-installation) antes de empezar tu actualización.
</Tip>

## Inicio rápido

***

### 1. Revisa los prerrequisitos

* **Helm v3.8+** instalado y disponible (`helm version`), obligatorio para la compatibilidad con registries OCI.
* **Respalda** tus bases de datos y tu archivo de values.

### 2. Identifica tu versión actual

```bash theme={null}
helm list -n midaz
```

La columna `CHART` muestra la versión de tu chart, como `midaz-helm-<version>`.

### 3. Ejecuta el comando de actualización

```bash theme={null}
helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
  --version <target-version> \
  -n midaz \
  -f your-values.yaml
```

### 4. Verifica la actualización

```bash theme={null}
helm list -n midaz
kubectl get pods -n midaz
```

## Compatibilidad de versiones

***

| Componente | Requisito                                                                                                                       |
| :--------- | :------------------------------------------------------------------------------------------------------------------------------ |
| Kubernetes | Una release menor con soporte vigente. El chart renderiza `autoscaling/v2` y `policy/v1`, así que el cluster debe servir ambos. |
| Helm       | 3.8+ (compatibilidad OCI)                                                                                                       |
| PostgreSQL | 13+                                                                                                                             |
| MongoDB    | 4.4+                                                                                                                            |
| Valkey     | 7.x                                                                                                                             |

El chart incluye PostgreSQL, MongoDB, RabbitMQ y Valkey como dependencias de subchart. Apunta el chart a tus propias instancias administradas deshabilitando cada dependencia (`postgresql.enabled: false`, y así con las demás). Consulta [Values de producción](/es/platform/deploy/midaz/midaz-production-values).

## Releases con cambios incompatibles que debes considerar

***

<Warning>
  No saltes varias versiones mayores en un solo `helm upgrade`. Lee cada [nota de actualización del repositorio del chart](https://github.com/LerianStudio/helm/tree/main/charts/midaz/docs) (`UPGRADE-*.md`) relevante entre tu chart actual y tu objetivo.
</Warning>

| Release del chart | Qué cambió                                                                                                                                                                                                                                                                                       |
| :---------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **v7.0.0**        | Los servicios `onboarding` y `transaction` se eliminaron por completo. Toda la funcionalidad pasó al único servicio `ledger`. Los componentes de Console y NGINX se fueron con ellos, y también los helpers de template de los servicios antiguos.                                               |
| **v8.4.0**        | El subchart `otel-collector-lerian` ya no se instala. La clave ahora solo inyecta variables de entorno de OTEL, y su esquema acepta **solo** `enabled`. Las claves legacy (`external`, `extraEnvs`, `exporters`, `opentelemetry-collector`) fallan la validación al momento de la actualización. |

Si todavía ejecutas un chart v4.x o v5.x, migra por las rutas de [Resumen de migración](/es/platform/deploy/midaz/midaz-migrating-overview) en lugar de actualizar directo a la línea actual.

## Actualizar Midaz core

***

<Warning>
  Cuando actualices Midaz o cualquier plugin, actualiza siempre el Helm chart correspondiente.

  Actualizar versiones de aplicación sin actualizar el Helm chart puede causar fallas de despliegue o entornos inconsistentes.
</Warning>

### 1. Revisa las versiones disponibles

Los charts se distribuyen **solo como artefactos OCI**. No hay un índice de repositorio de Helm donde buscar, así que `helm search repo` no funciona aquí. Recorre los tags de release para descubrir versiones y luego inspecciona una en particular:

```bash theme={null}
helm show chart oci://registry-1.docker.io/lerianstudio/midaz-helm --version <version>
```

O recorre los tags de release:

* Visita [https://github.com/LerianStudio/helm/tags](https://github.com/LerianStudio/helm/tags)
* Filtra por el prefijo `midaz-v`

### 2. Revisa los cambios antes de actualizar

Compara tus values actuales con los valores predeterminados del chart objetivo:

```bash theme={null}
helm show values oci://registry-1.docker.io/lerianstudio/midaz-helm --version <target-version> > new-defaults.yaml
```

Luego renderiza la actualización sin aplicarla:

```bash theme={null}
helm template midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
  --version <target-version> \
  -n midaz \
  -f your-values.yaml
```

Una violación de esquema (por ejemplo, una clave legacy `otel-collector-lerian`) falla aquí y no a mitad de la actualización.

### 3. Ejecuta la actualización

```bash theme={null}
helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
  --version <target-version> \
  -n midaz \
  -f your-values.yaml \
  --wait --timeout 10m
```

<Warning>
  Sin argumentos de values, Helm arrastra de forma predeterminada los values almacenados del release. Pasar `-f` (como arriba) o `--set` aplica esos nuevos overrides a los valores predeterminados del chart objetivo en lugar de arrastrar los values almacenados. Agrega `--reuse-values` cuando necesites combinar los nuevos overrides con los values almacenados del release. Usa `--reset-values` para descartar los values almacenados y partir de los valores predeterminados del chart objetivo.
</Warning>

### 4. Verifica la actualización

* **Revisa el estado del release**

```bash theme={null}
helm list -n midaz
```

* **Verifica el estado de los pods**

```bash theme={null}
kubectl get pods -n midaz
```

* **Revisa los logs de los pods en busca de errores**

```bash theme={null}
kubectl logs -n midaz deployment/midaz-ledger --tail=50
```

Si mantienes la carga de trabajo de compatibilidad legacy de CRM (`crm.enabled: true`):

```bash theme={null}
kubectl logs -n midaz deployment/midaz-crm --tail=50
```

Todos los pods deberían mostrar el estado `Running` y un conteo de contenedores listos.

<Note>
  `midaz-ledger` es el único Deployment de aplicación que el chart crea de forma predeterminada. `midaz-crm` se agrega cuando `crm.enabled: true`. `midaz-onboarding` y `midaz-transaction` ya no existen a partir del chart v7.0.0.
</Note>

## Actualizar los plugins

***

<Note>
  Actualiza siempre Midaz Core **antes** de actualizar los plugins. Los plugins dependen de las APIs de Midaz Core.
</Note>

Los plugins son releases separados y se instalan en su propio namespace, `midaz-plugins`. Revisa los tags de release del propio plugin en [https://github.com/LerianStudio/helm/tags](https://github.com/LerianStudio/helm/tags) para conocer la versión actual.

### CRM

CRM es un módulo dentro del chart `midaz-helm`. Lo habilitas con el bloque de values `crm`. No existe un chart de CRM. Cuando lo habilitas, verifica sus pods después de actualizar el core:

```bash theme={null}
kubectl get pods -n midaz -l app.kubernetes.io/name=midaz-crm
```

### Fees

```bash theme={null}
helm upgrade plugin-fees oci://registry-1.docker.io/lerianstudio/plugin-fees-helm \
  --version <target-version> \
  -n midaz-plugins \
  -f plugin-fees-values-backup.yaml
```

```bash theme={null}
kubectl get pods -n midaz-plugins -l app.kubernetes.io/instance=plugin-fees
```

### Pix

```bash theme={null}
helm upgrade plugin-br-pix-direct-jd \
  oci://registry-1.docker.io/lerianstudio/plugin-br-pix-direct-jd-helm \
  --version <target-version> \
  -n midaz-plugins \
  -f plugin-pix-values-backup.yaml
```

```bash theme={null}
kubectl get pods -n midaz-plugins -l app.kubernetes.io/instance=plugin-br-pix-direct-jd
```

<Note>
  El chart etiqueta cada carga de trabajo con el conjunto de labels `app.kubernetes.io/*`. Un selector como `-l app=midaz-crm` no coincide con nada.
</Note>