Saltar al contenido principal
Esta guía te acompaña en la actualización de tu despliegue de Midaz desde Midaz Helm 2.x.x a v3.x.x. Encontrarás un inicio rápido para operadores experimentados, seguido de un desglose detallado de cambios incompatibles, nuevas funciones y verificaciones posteriores a la actualización.
¿Necesitas un repaso sobre cómo instalar Midaz con Helm? Consulta la guía Usando Helm en Estrategias de despliegue antes de comenzar tu actualización.

​
Inicio rápido

​
1. Verifica los requisitos previos

  • Helm v3.8+ instalado y disponible (helm version).
  • Clúster Kubernetes v1.20+ en ejecución.
  • Copia de seguridad de tu instalación existente.

​
2. Ejecuta el comando de actualización

helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm --version 3.0.0 -n midaz

​
3. Verifica la actualización

helm list -n midaz
kubectl get pods -n midaz

​
Compatibilidad de versiones

Componentev2.xv3.0.0
Kubernetes1.19+1.20+
Helm3.5+3.8+
Redis6.x6.x/7.x*
PostgreSQL13+13+
MongoDB4.4+4.4+
*Nueva configuración de Redis admitida

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

1
Respalda las versiones de Helm existentes:
helm get values -n midaz midaz > midaz-v2-backup.yaml
2
Revisa la sección de Cambios incompatibles a continuación.
3
Verifica los requisitos de recursos para v3.0.0.
4
Programa una ventana de mantenimiento.
5
Informa a tu equipo sobre el plan de actualización.

​
Cambios incompatibles

​
Consolidación de REDIS_PORT en REDIS_HOST

La variable de entorno REDIS_PORT ha sido eliminada. Su valor ahora debe incluirse directamente en la variable REDIS_HOST como <host>:<port>.
Elimina REDIS_PORT de tu entorno y actualiza REDIS_HOST para evitar errores de conexión. Consulta las plantillas de onboarding configmap y transaction configmap para más detalles.
Este cambio afecta a los siguientes componentes:
  • onboarding
  • transaction
Configuración antigua 
REDIS_HOST=redis_host
REDIS_PORT=redis_port
Nueva configuración 
REDIS_HOST=redis_host:redis_port

​
Actualización de versión de la aplicación

Midaz ha sido actualizado a v3.0.0.
Consulta el changelog de la aplicación para la lista completa de cambios.

​
Adiciones

​
Nueva variable de entorno de onboarding

Se ha agregado una nueva variable de entorno (ACCOUNT_TYPE_VALIDATION) al servicio onboarding. Puedes usarla para especificar qué Ledgers son válidos para la creación de cuentas por organización: 
# ACCOUNTING CONFIG
# Lista de <organization-id>:<ledger-id> separados por coma
ACCOUNT_TYPE_VALIDATION=
Consulta la plantilla de onboarding configmap para más detalles.

​
Nueva variable de entorno de transaction

Se ha agregado una nueva variable de entorno (TRANSACTION_ROUTE_VALIDATION) al servicio transaction. Puedes usarla para definir qué Ledgers están permitidos por organización para la validación de enrutamiento de transacciones: 
# ACCOUNTING CONFIG
# Lista de <organization-id>:<ledger-id> separados por coma
TRANSACTION_ROUTE_VALIDATION=
Consulta la plantilla de transaction configmap para más detalles.

​
Nuevas variables de Redis

Se han introducido las siguientes variables de entorno a los servicios onboarding y transaction: 
# USAR SOLO EN SENTINEL
REDIS_MASTER_NAME=

# CONFIGURACIÓN TLS
REDIS_TLS=false
REDIS_CA_CERT=

# AUTENTICACIÓN IAM DE GCP
REDIS_USE_GCP_IAM=false
REDIS_SERVICE_ACCOUNT=
GOOGLE_APPLICATION_CREDENTIALS=
# <= 60 minutos
REDIS_TOKEN_LIFETIME=60
# minutos
REDIS_TOKEN_REFRESH_DURATION=45

# AUTENTICACIÓN Y SELECCIÓN DE BD
REDIS_PASSWORD=lerian
REDIS_DB=0
REDIS_PROTOCOL=3

# CONFIGURACIÓN DE POOL Y REINTENTOS
REDIS_POOL_SIZE=10
REDIS_MIN_IDLE_CONNS=0
# Segundos
REDIS_READ_TIMEOUT=3
REDIS_WRITE_TIMEOUT=3
REDIS_DIAL_TIMEOUT=5
REDIS_POOL_TIMEOUT=2

REDIS_MAX_RETRIES=3
# Milisegundos
REDIS_MIN_RETRY_BACKOFF=8
# Segundos
REDIS_MAX_RETRY_BACKOFF=1
Consulta las plantillas de onboarding configmap y transaction configmap para más detalles.

​
Enterprise: Gateway NGINX para UIs de plugins

Se ha introducido un nuevo componente NGINX opcional para servir como gateway/proxy para las UIs de plugins activados en despliegues empresariales.
  • Por defecto, esta dependencia está deshabilitada.
  • Puede habilitarse por cliente según los plugins a los que tengan acceso.
  • Este gateway simplifica el enrutamiento y montaje de frontends de plugins bajo el dominio midaz-console.

​
Variables de entorno de Midaz Console

Se han agregado nuevas variables de entorno a midaz-console para soportar esta funcionalidad: 
console:
  configmap:
    NEXT_PUBLIC_MIDAZ_CONSOLE_BASE_URL: https://midaz-console.yourdomain.io
    NGINX_PORT: 8080
    NGINX_HOST: midaz-nginx.midaz.svc.cluster.local
    NGINX_BASE_PATH: http://midaz-nginx.midaz.svc.cluster.local:8080
Consulta la plantilla de console configmap para más detalles.

​
Parámetros de Helm

También se introdujeron nuevos parámetros de Helm: 
# UIs de Plugins
  pluginsUi:
    enabled: false
    plugins:
      plugin-smart-templates-ui:
        enabled: false
        port: 8083
      plugin-crm-ui:
        enabled: false
        port: 8084
      plugin-fees-ui:
        enabled: false
        port: 8082
  ...
Consulta la sección de Plugin UIs en values.yaml para más detalles.

​
Variables de NGINX

nginx:
  enabled: false

  service:
    type: ClusterIP
    ports:
      http: 8080

  existingServerBlockConfigmap: "midaz-console-nginx-config"

  # Montar el configmap de plugins como volumen
  extraVolumes:
    - name: nginx-plugins-config
      configMap:
        name: midaz-console-nginx-config-plugins

  # Montar el volumen en el contenedor nginx
  extraVolumeMounts:
    - name: nginx-plugins-config
      mountPath: /opt/bitnami/nginx/conf/plugins_blocks

  ingress:
    enabled: false
    pathType: Prefix
    hostname: ""
    path: /
    annotations: {}
    ingressClassName: ""
Consulta la sección de nginx en values.yaml para más detalles.

​
Enterprise: OTEL Collector

Se ha introducido un nuevo componente OTEL Collector opcional para clientes empresariales que deseen enviar métricas al stack de telemetría de Lerian. Este recolector está deshabilitado por defecto y puede habilitarse en valores: 
otel-collector-lerian:
  enabled: true
Para redirigir métricas a un adaptador Prometheus personalizado del lado del cliente, modifica: 
otel-collector-lerian:
  exporters:
    prometheus/local:
      endpoint: "http://<customer-prometheus-endpoint>:9090"
Consulta la sección de otel-collector-lerian en values.yaml para más detalles.

​
Soporte de secretos externos

Ahora puedes usar secretos externos para datos sensibles en console, onboarding y transaction.

​
Para console

Configura: 
console:
    useExistingSecrets: true
    existingSecretName: <existing-secret-name>
Consulta la plantilla de secretos de console para obtener las claves de secretos.

​
Para onboarding

Configura: 
onboarding:
    useExistingSecrets: true
    existingSecretName: <existing-secret-name>
Consulta la plantilla de secretos de onboarding para obtener las claves de secretos.

​
Para transaction

Configura: 
transaction:
    useExistingSecrets: true
    existingSecretName: <existing-secret-name>
Consulta la plantilla de secretos de transaction para obtener las claves de secretos.

​
Verificación posterior a la actualización

​
1. Verifica el estado de los pods

kubectl get pods -n midaz
Todos los pods deben estar en estado Running y READY.

​
2. Verifica los servicios

kubectl get svc -n midaz

​
3. Verifica los logs

# Verificar logs de console
kubectl logs -n midaz deployment/midaz-console

# Verificar logs del servicio onboarding
kubectl logs -n midaz deployment/midaz-onboarding

# Verificar logs del servicio transaction
kubectl logs -n midaz deployment/midaz-transaction

​
Procedimiento de rollback

Si encuentras problemas después de la actualización, puedes revertir a la versión anterior: 
# Listar historial de versiones
helm history midaz -n midaz

# Revertir a versión anterior
helm rollback midaz <REVISION> -n midaz

# Verificar rollback
helm list -n midaz
kubectl get pods -n midaz

​
Problemas comunes y soluciones

​
Problemas de conexión a Redis

  • Síntoma: Los servicios fallan al iniciar con errores de conexión a Redis.
  • Solución: Verifica tu configuración de Redis en values.yaml:
redis:
  host: your-redis-host:6379  # Incluir puerto en host
  # Eliminar redis.port si está presente

​
Secretos faltantes

  • Síntoma: Los pods fallan con errores de secretos faltantes.
  • Solución: Asegúrate de que todos los secretos requeridos estén configurados correctamente:
    • Verifica los nombres de secretos en tu values.yaml.
    • Verifica que los secretos externos existan si usas useExistingSecrets: true.

​
Problemas con el Gateway NGINX

  • Síntoma: Las UIs de plugins no son accesibles.
  • Solución:
    • Verifica que NGINX esté habilitado en values.yaml.
    • Verifica los logs de NGINX:
kubectl logs -n midaz deployment/midaz-nginx

​
Cambios de arquitectura

​
Arquitectura V2

Figura 1. Flujo de datos de arquitectura V2.

  • Componentes clave
  • Flujo de datos
  • Console: La interfaz de usuario principal y gateway de API.
  • Servicio de Onboarding: Maneja la creación y gestión de cuentas.
  • Servicio de Transacción: Procesa transacciones financieras.
  • Redis: Usado para caché y almacenamiento temporal de datos.
  • PostgreSQL: Base de datos principal para almacenamiento persistente

​
Arquitectura V3

Figura 2. Flujo de datos de arquitectura V3

  • Mejoras clave en v3
  • Cambios en el flujo de datos
  • Impacto de la migración
  1. Gateway NGINX
  • Nuevo componente para gestionar UIs de plugins.
  • Permite carga y enrutamiento dinámico de plugins.
  • Proporciona mejor aislamiento de seguridad para plugins.
  1. Arquitectura de plugins
  • Soporte para UIs de plugins modulares.
  • Cada plugin puede habilitarse/deshabilitarse independientemente.
  • Los plugins pueden desarrollarse y desplegarse por separado.
  1. Observabilidad
  • Nuevo OTEL Collector para métricas centralizadas.
  • Capacidades de monitoreo mejoradas.
  • Mejor integración con herramientas de monitoreo externas.
  1. Seguridad mejorada
  • Soporte de secretos externos.
  • Configuración TLS mejorada.
  • Mejor aislamiento entre componentes.

​
Comando para actualizar

helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm --version 3.0.0 -n midaz