> ## 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 Helm para Midaz

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

Esta guía te lleva por la actualización de tu despliegue Helm de Midaz a la línea actual del chart, **v8.x**.

Encontrarás un inicio rápido para operadores experimentados, los releases con cambios incompatibles que no debes saltarte a ciegas, la actualización de plugins y las verificaciones posteriores.

<Tip>
  ¿Necesitas repasar la instalación de Midaz con Helm? Consulta la guía [Instalación de Midaz con Helm](/es/platform/helm/midaz/midaz-installation) antes de comenzar la actualización.
</Tip>

## Inicio rápido

***

### 1. Verifica los prerrequisitos

* **Helm v3.8+** instalado y disponible (`helm version`) — necesario para el soporte de registries OCI.
* Clúster de **Kubernetes v1.20+** en ejecución.
* **Copia de seguridad** de tus bases de datos y de 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 (por ejemplo, `midaz-helm-8.6.0`).

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

```bash theme={null}
helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
  --version <version-objetivo> \
  -n midaz \
  -f tus-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 | 1.20+              |
| Helm       | 3.8+ (soporte OCI) |
| PostgreSQL | 13+                |
| MongoDB    | 4.4+               |
| Valkey     | 7.x                |

El chart incluye PostgreSQL, MongoDB, RabbitMQ y Valkey como dependencias de subcharts. Apunta el chart a tus propias instancias gestionadas deshabilitando cada dependencia (`postgresql.enabled: false`, etc.) — consulta [Values de producción](/es/platform/helm/midaz/midaz-production-values).

## Releases con cambios incompatibles que debes considerar

***

<Warning>
  No saltes varias versiones mayores en un solo `helm upgrade`. Lee la nota de actualización del release en el repositorio del chart (`charts/midaz/docs/UPGRADE-*.md`) para cada versión mayor entre tu chart actual y tu objetivo.
</Warning>

| Release del chart | Qué cambió                                                                                                                                                                                                                                                                              |
| :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **v5.0.0**        | Se eliminaron los componentes Console y NGINX. Con ellos se eliminaron también los templates del stack de observabilidad de Grafana.                                                                                                                                                    |
| **v7.0.0**        | Los servicios `onboarding` y `transaction` se eliminaron por completo — toda su funcionalidad se consolidó en el único servicio `ledger`. Los helpers de templates de los servicios antiguos ya no existen.                                                                             |
| **v8.4.0**        | El subchart `otel-collector-lerian` ya no se instala. La clave solo inyecta variables de entorno de OTEL y su esquema acepta **únicamente** `enabled`; las claves heredadas (`external`, `extraEnvs`, `exporters`, `opentelemetry-collector`) ahora fallan la validación al actualizar. |

Si aún ejecutas un chart v4.x o v5.x, migra siguiendo las rutas de [Descripción general de migraciones](/es/platform/helm/midaz/midaz-migrating-overview) en lugar de actualizar directamente a v8.

## Actualización del core de Midaz

***

<Warning>
  Al actualizar Midaz o cualquier plugin, actualiza siempre el chart de Helm correspondiente.

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

### 1. Consulta las versiones disponibles

Los charts se distribuyen **solo como artefactos OCI**: no hay un índice de repositorio Helm que consultar, por lo que `helm search repo` no funciona aquí. Explora los tags de release para descubrir versiones y luego inspecciona una en concreto:

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

O revisa 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 por defecto del chart objetivo:

```bash theme={null}
helm show values oci://registry-1.docker.io/lerianstudio/midaz-helm --version <version-objetivo> > 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 <version-objetivo> \
  -n midaz \
  -f tus-values.yaml
```

Una violación del esquema (por ejemplo, una clave heredada de `otel-collector-lerian`) falla aquí en lugar de 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 <version-objetivo> \
  -n midaz \
  -f tus-values.yaml \
  --wait --timeout 10m
```

<Warning>
  Pasa siempre tus values con `-f`. Sin ello, Helm no reutiliza nada de tu configuración anterior y el release vuelve a los valores por defecto del chart.
</Warning>

### 4. Verifica la actualización

* **Comprueba el estado del release**

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

* **Verifica que los pods estén en ejecución**

```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 ejecutas CRM (`crm.enabled: true` — está **deshabilitado** por defecto):

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

Todos los pods deben mostrar estado `Running` y sus contenedores listos.

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

## Actualización de plugins

***

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

Los plugins son releases independientes y se instalan en su propio namespace, `midaz-plugins`. Consulta 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 forma parte del chart de Midaz — no hay un release de CRM aparte que actualizar. Si lo habilitas (`crm.enabled: true`), verifica sus pods tras la actualización del core:

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

### Fees Engine

```bash theme={null}
helm upgrade plugin-fees oci://registry-1.docker.io/lerianstudio/plugin-fees-helm \
  --version <version-objetivo> \
  -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 \
  --version <version-objetivo> \
  -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 workload con el conjunto de labels `app.kubernetes.io/*`. Un selector como `-l app=midaz-crm` no coincide con nada.
</Note>