Saltar al contenido principal
Esta guía cubre cómo actualizar Midaz y sus plugins usando Helm. Ya sea que estés aplicando un parche, una actualización menor o moviendo entre versiones mayores, sigue estos procedimientos para asegurar una actualización sin problemas.
¿Actualizando de Helm v2.x a v3.x? Consulta la guía de actualización a Helm v3 dedicada para cambios importantes y pasos de migración.

​
Requisitos previos

Antes de comenzar cualquier actualización, asegúrate de tener:
La compatibilidad de versiones entre los charts de Helm y las aplicaciones está definida por la matriz de compatibilidad oficial mantenida en el README del repositorio de Helm.Esta matriz se actualiza automáticamente en cada lanzamiento de aplicación y siempre debe verificarse antes de actualizar.

​
Verifica tus herramientas

Ejecuta los siguientes comandos para verificar tus herramientas:
  • Verificar versión de Helm
helm version
  • Verificar acceso a kubectl
kubectl cluster-info

​
Lista de verificación previa a la actualización

1

Verificar versiones actuales

Revisa las versiones de tu despliegue actual:
  • Listar releases de Helm
helm list -n midaz
  • Verificar pods en ejecución
kubectl get pods -n midaz -o wide
2

Revisar compatibilidad de la versión objetivo

Consulta la tabla de compatibilidad de versiones para asegurar que tu versión objetivo sea compatible con tus plugins e infraestructura.
3

Respaldar valores actuales

Guarda tus valores actuales de Helm como referencia y para una posible reversión:
  • Respaldar valores de Midaz
helm get values midaz -n midaz > midaz-values-backup.yaml
  • Respaldar valores de plugins (ejemplo: CRM)
helm get values plugin-crm -n midaz > plugin-crm-values-backup.yaml
4

Revisar notas de la versión

Consulta el repositorio de Helm para ver las notas de la versión y cambios importantes en tu versión objetivo.
5

Programar ventana de mantenimiento

Coordina con tu equipo y programa una ventana de mantenimiento apropiada para la actualización.
6

Asegurar respaldos de base de datos

Asegúrate de que los respaldos de base de datos estén en su lugar antes de actualizar, especialmente para versiones mayores.
En casos específicos, como ciertos lanzamientos de hotfix, puede que no se requiera una actualización del chart de Helm.Siempre verifica las notas de la versión antes de omitir una actualización de Helm.

​
Actualización de Midaz Core

Al actualizar Midaz o cualquier plugin, siempre actualiza el chart de Helm correspondiente.Actualizar versiones de aplicaciones sin actualizar el chart de Helm puede provocar fallos en el despliegue o entornos inconsistentes.

​
1. Verificar versiones disponibles

Lista las versiones de charts disponibles desde el registro OCI:
  • Listar versiones disponibles
helm search repo lerianstudio/midaz-helm --versions

​
2. Revisar cambios (opcional)

Compara tus valores actuales con los valores por defecto del nuevo chart: 
helm show values oci://registry-1.docker.io/lerianstudio/midaz-helm --version 4.4.8 > new-defaults.yaml

​
3. Ejecutar la actualización

Actualiza a tu versión objetivo:
  • Actualizar con valores existentes
helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
  --version 4.4.8 \
  -n midaz \
  -f midaz-values-backup.yaml
  • Actualizar con nuevos valores
helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
  --version 4.4.8 \
  -n midaz \
  -f my-custom-values.yaml
Si tienes valores personalizados, siempre pásalos con -f para evitar perder tu configuración durante la actualización.

​
4. Verificar la actualización

  • Verificar estado del release
helm list -n midaz
  • Verificar si los pods están en ejecución
kubectl get pods -n midaz
  • Revisar logs de los pods en busca de errores
kubectl logs -n midaz deployment/midaz-console --tail=50
kubectl logs -n midaz deployment/midaz-onboarding --tail=50
kubectl logs -n midaz deployment/midaz-transaction --tail=50
Todos los pods deben mostrar estado Running y estado READY.

​
Actualización de plugins

Siempre actualiza Midaz Core antes de actualizar los plugins. Los plugins dependen de las APIs de Midaz Core.

​
CRM

  • Actualizar plugin CRM
helm upgrade plugin-crm oci://registry-1.docker.io/lerianstudio/plugin-crm \
  --version 3.2.1 \
  -n midaz \
  -f plugin-crm-values-backup.yaml
  • Verificar pods de CRM
kubectl get pods -n midaz -l app=plugin-crm

​
Fees Engine

  • Actualizar plugin Fees Engine
helm upgrade plugin-fees oci://registry-1.docker.io/lerianstudio/plugin-fees \
  --version 3.4.7 \
  -n midaz \
  -f plugin-fees-values-backup.yaml
  • Verificar pods de Fees Engine
kubectl get pods -n midaz -l app=plugin-fees

​
Pix

El plugin Pix aún está en desarrollo.
  • Actualizar plugin Pix
helm upgrade plugin-pix oci://registry-1.docker.io/lerianstudio/plugin-br-pix-direct-jd \
  --version 1.2.6 \
  -n midaz \
  -f plugin-pix-values-backup.yaml
  • Verificar pods de Pix
kubectl get pods -n midaz -l app=plugin-pix

​
Mejores prácticas

​
Orden de actualización

Siempre actualiza en este orden:
  1. Infraestructura (si es necesario)
  2. Midaz Core
  3. Plugins (uno a la vez)

​
Probar primero

Siempre prueba las actualizaciones en un entorno de staging que refleje producción antes de aplicarlas en producción.

​
Monitorear de cerca

Monitorea los logs y métricas de cerca durante los primeros 15-30 minutos después de una actualización.

​
Mantener respaldos

Mantén respaldos de tus valores de Helm y base de datos antes de actualizaciones mayores.

​
Resumen de lista de verificación de actualización

PasoComandoVerificado
Respaldar valoreshelm get values <release> -n midaz > backup.yaml
Verificar compatibilidadRevisar tabla de compatibilidad
Actualizar Midazhelm upgrade midaz ...
Verificar pods de Midazkubectl get pods -n midaz
Actualizar pluginshelm upgrade <plugin> ...
Verificar pods de pluginkubectl get pods -n midaz
Revisar logskubectl logs -n midaz deployment/<name>

​
Procedimientos de reversión

Si algo sale mal después de una actualización, puedes revertir a una versión anterior.

​
Cuándo revertir

Considera revertir si observas:
  • Pods que no inician o están en bucle de reinicio
  • Errores de API o indisponibilidad del servicio
  • Inconsistencias de datos
  • Degradación del rendimiento

​
Verificar historial de releases

Visualiza el historial de revisiones de un release: 
helm history midaz -n midaz
Ejemplo de salida: 
REVISION  STATUS      CHART           APP VERSION  DESCRIPTION
1         superseded  midaz-4.3.4     3.4.6        Install complete
2         deployed    midaz-4.4.8     3.4.7        Upgrade complete

​
Ejecutar reversión

Revierte a una revisión específica:
  • Revertir Midaz a la revisión anterior
helm rollback midaz 1 -n midaz
  • Revertir plugin (ejemplo: CRM)
helm rollback plugin-crm 1 -n midaz

​
Verificar reversión

  • Verificar versión del release
helm list -n midaz
  • Verificar pods
kubectl get pods -n midaz
  • Revisar logs
kubectl logs -n midaz deployment/midaz-console --tail=50
Las reversiones pueden no revertir los cambios del esquema de base de datos. Si la actualización incluyó migraciones de base de datos, puede que necesites restaurar desde un respaldo de base de datos.

​
Solución de problemas

​
Pods atascados en estado Pending

Síntoma: Los pods permanecen en estado Pending después de la actualización. Solución: Verifica restricciones de recursos:
  • Describir pod pendiente
kubectl describe pod <pod-name> -n midaz
  • Verificar recursos de nodos
kubectl top nodes

​
Errores de descarga de imagen

Síntoma: Los pods muestran ImagePullBackOff o ErrImagePull. Solución: Verifica el acceso al registro de imágenes y las credenciales:
  • Verificar eventos del pod
kubectl describe pod <pod-name> -n midaz | grep -A 10 Events
  • Verificar que la imagen existe
docker pull lerianstudio/midaz-console:3.4.6

​
Errores de configuración

Síntoma: Los pods fallan con errores relacionados con la configuración en los logs. Solución: Compara tus valores con los valores por defecto del nuevo chart:
  • Ver valores actuales
helm get values midaz -n midaz
  • Ver valores por defecto del chart
helm show values oci://registry-1.docker.io/lerianstudio/midaz-helm --version 4.4.8

​
Problemas de conexión a base de datos

Síntoma: Los servicios no pueden conectarse a PostgreSQL o MongoDB. Solución: Verifica la conectividad y credenciales de la base de datos:
  • Verificar pods de base de datos
kubectl get pods -n midaz -l app.kubernetes.io/name=postgresql
kubectl get pods -n midaz -l app.kubernetes.io/name=mongodb
  • Verificar logs del servicio
kubectl logs -n midaz deployment/midaz-onboarding | grep -i database

​
Recursos relacionados