Guía de actualización de Midaz con Helm

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.

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.

Para repasar la instalación de Midaz con Helm, consulta la guía Instalar Midaz con Helm antes de empezar tu actualización.

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

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

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

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.

Releases con cambios incompatibles que debes considerar

No saltes varias versiones mayores en un solo helm upgrade. Lee cada nota de actualización del repositorio del chart (UPGRADE-*.md) relevante entre tu chart actual y tu objetivo.

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 en lugar de actualizar directo a la línea actual.

Actualizar Midaz core

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.

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:

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
Filtra por el prefijo midaz-v

2. Revisa los cambios antes de actualizar

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

helm show values oci://registry-1.docker.io/lerianstudio/midaz-helm --version <target-version> > new-defaults.yaml

Luego renderiza la actualización sin aplicarla:

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

helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
  --version <target-version> \
  -n midaz \
  -f your-values.yaml \
  --wait --timeout 10m

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.

4. Verifica la actualización

Revisa el estado del release

helm list -n midaz

Verifica el estado de los pods

kubectl get pods -n midaz

Revisa los logs de los pods en busca de errores

kubectl logs -n midaz deployment/midaz-ledger --tail=50

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

kubectl logs -n midaz deployment/midaz-crm --tail=50

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

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.

Actualizar los plugins

Actualiza siempre Midaz Core antes de actualizar los plugins. Los plugins dependen de las APIs de Midaz Core.

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

kubectl get pods -n midaz -l app.kubernetes.io/name=midaz-crm

Fees

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

kubectl get pods -n midaz-plugins -l app.kubernetes.io/instance=plugin-fees

Pix

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

kubectl get pods -n midaz-plugins -l app.kubernetes.io/instance=plugin-br-pix-direct-jd

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.

Introducción

Midaz

Otros productos

Guía de actualización de Midaz con Helm

Inicio rápido

1. Revisa los prerrequisitos

2. Identifica tu versión actual

3. Ejecuta el comando de actualización

4. Verifica la actualización

Compatibilidad de versiones

Releases con cambios incompatibles que debes considerar

Actualizar Midaz core

1. Revisa las versiones disponibles

2. Revisa los cambios antes de actualizar

3. Ejecuta la actualización

4. Verifica la actualización

Actualizar los plugins

CRM

Fees

Pix

​Inicio rápido

​1. Revisa los prerrequisitos

​2. Identifica tu versión actual

​3. Ejecuta el comando de actualización

​4. Verifica la actualización

​Compatibilidad de versiones

​Releases con cambios incompatibles que debes considerar

​Actualizar Midaz core

​1. Revisa las versiones disponibles

​2. Revisa los cambios antes de actualizar

​3. Ejecuta la actualización

​4. Verifica la actualización

​Actualizar los plugins

​CRM

​Fees

​Pix

Inicio rápido

1. Revisa los prerrequisitos

2. Identifica tu versión actual

3. Ejecuta el comando de actualización

4. Verifica la actualización

Compatibilidad de versiones

Releases con cambios incompatibles que debes considerar

Actualizar Midaz core

1. Revisa las versiones disponibles

2. Revisa los cambios antes de actualizar

3. Ejecuta la actualización

4. Verifica la actualización

Actualizar los plugins

CRM

Fees

Pix