Esta guía cubre el chart de Helm de Midaz v5.x. Para actualizar desde versiones anteriores, consulta Actualización de Helm.
Desplegar Midaz con Helm
Requisitos previos
Antes de desplegar Midaz con Helm, asegúrate de tener:- Kubernetes (v1.30+) – Clúster en ejecución.
- Helm 3+ – Instalado y disponible (
helm version). - Acceso a un registro de contenedores con imágenes de Midaz.
- Certificados DNS y TLS para ingress (o cert-manager instalado).
El código fuente de este chart de Helm está disponible en:La instalación predeterminada coincide con la proporcionada en la guía de instalación rápida de Midaz.
Instalar Midaz a través del chart de Helm
Para instalar Midaz usando Helm, ejecuta el siguiente comando:<version> con la versión deseada del chart de Helm. Puedes verificar las versiones disponibles ejecutando:
midaz (si no existe ya) y despliega el chart. Para confirmar que el despliegue se realizó correctamente, ejecuta:
Configurar ingress
Ingress te permite exponer servicios de Midaz fuera del clúster de Kubernetes, vinculándolos a dominios específicos y certificados TLS. Puedes habilitar ingress individualmente para cada servicio de Midaz. Para usar ingress, necesitarás un controlador ingress ejecutándose en tu clúster (por ejemplo, NGINX, AWS ALB o Traefik) y entradas DNS apuntando a él. Las siguientes secciones proporcionan ejemplos de configuración para los controladores ingress más comunes.
Controlador ingress NGINX
Para usar el Controlador Ingress NGINX, configura elvalues.yaml de la siguiente manera:
AWS ALB (Application Load Balancer)
Para el Controlador Ingress AWS ALB, configura elvalues.yaml de la siguiente manera:
Controlador Ingress Traefik
Para Traefik, configura elvalues.yaml de la siguiente manera:
Configurar observabilidad
Midaz usa Grafana Docker OpenTelemetry LGTM para recopilar y visualizar datos de telemetría como trazas y métricas. Puedes acceder al panel de Grafana usando una de dos opciones:
Opción 1: Acceso local
Para acceder al panel localmente, ejecuta:Opción 2: Acceso mediante Ingress
Para exponer Grafana dentro de tu clúster o red privada a través de DNS, habilita y configura Ingress de esta manera:Deshabilitar observabilidad
Puedes deshabilitar completamente el stack de observabilidad configurando:OpenTelemetry Collector (Lerian)
El OpenTelemetry Collector se usa para recopilar y exportar datos de telemetría de los componentes de Midaz. Por defecto, está deshabilitado. Para habilitarlo:Configurar dependencias
El Chart de Helm de Midaz tiene las siguientes dependencias para la instalación predeterminada del proyecto. Todas las dependencias están habilitadas por defecto.
Los ejemplos a continuación muestran configuraciones tanto para el servicio Ledger (recomendado) como para los servicios Onboarding/Transaction (legacy). Elige la configuración que corresponda a tu despliegue.
Valkey
- Versión: 2.4.7
- Repositorio: Bitnami
- Deshabilitar:
valkey.enabled = false
- Ledger (recomendado)
- Onboarding/Transaction (legacy)
PostgreSQL
- Versión: 16.3.0
- Repositorio: Bitnami
- Deshabilitar:
postgresql.enabled = false
- Ledger (recomendado)
- Onboarding/Transaction (legacy)
Job de Bootstrap para PostgreSQL Externo
Cuando usas un PostgreSQL externo (postgresql.enabled: false), este chart proporciona un Job de bootstrap único que:
- Crea las bases de datos
onboardingytransactionsi no existen. - Crea el rol/usuario
midazsi no existe y establece su contraseña. - Otorga privilegios de base de datos y permisos del esquema
publicpara quemidazpueda crear tablas. - Espera conectividad con un timeout de 300s.
- Es idempotente: si todo ya existe, imprime y sale.
values.yaml:
Todos los secrets deben estar en el mismo namespace que el release. El Job tiene un TTL de 300 segundos después de completarse.
MongoDB
- Versión: 15.4.5
- Repositorio: Bitnami
- Deshabilitar:
mongodb.enabled = false
- Ledger (recomendado)
- Onboarding/Transaction (legacy)
RabbitMQ
- Versión: 16.0.0
- Repositorio: Groundhog2k
- Deshabilitar:
rabbitmq.enabled = false
values.yaml para aplicar automáticamente las definiciones de RabbitMQ a tu instancia externa:
load_definitions.json se encuentra en: charts/midaz/files/rabbitmq/load_definitions.json.
Job de Bootstrap para RabbitMQ Externo
Para simplificar la configuración de RabbitMQ externo, este chart proporciona un Job único que:- Aplica el archivo de definiciones estándar mediante la API HTTP.
- Crea/actualiza los usuarios
transactionyconsumercon contraseñas personalizadas. - Espera conectividad AMQP con un timeout de 300s.
- Es idempotente: si los usuarios ya existen, omite y sale.
values.yaml:
Todos los secrets deben estar en el mismo namespace que el release. El Job tiene un TTL de 300 segundos después de completarse. Usuarios creados:
midaz (admin), transaction, consumer.RabbitMQ sobre TLS/SSL
Si tu servidor RabbitMQ requiere TLS/SSL, actualiza las variables de entorno del cliente para usar protocolos seguros:- Ledger (recomendado)
- Onboarding/Transaction (legacy)
Usar tu propio RabbitMQ
Si ya tienes una instancia de RabbitMQ ejecutándose, puedes deshabilitar la dependencia integrada y apuntar los componentes de Midaz a tu configuración externa.- Ledger (recomendado)
- Onboarding/Transaction (legacy)
Componentes de Midaz
El chart de Helm de Midaz despliega servicios principales que manejan operaciones de ledger, gestión de cuentas y procesamiento de transacciones.
Ledger (recomendado)
El servicioledger es un servicio unificado que combina la funcionalidad de los módulos onboarding y transaction en un solo despliegue. Este servicio es recomendado para nuevas instalaciones y será obligatorio en futuras versiones.
Cuando
ledger.enabled está configurado como true, los servicios onboarding y transaction se deshabilitan automáticamente (a menos que migration.allowAllServices esté configurado como true para propósitos de prueba).| Parámetro | Descripción | Valor predeterminado |
|---|---|---|
ledger.enabled | Habilitar o deshabilitar el servicio ledger. | false |
ledger.name | Nombre del servicio. | "ledger" |
ledger.replicaCount | Número de réplicas para el servicio ledger. | 1 |
ledger.image.repository | Repositorio para la imagen del contenedor del servicio ledger. | "lerianstudio/midaz-ledger" |
ledger.image.pullPolicy | Política de extracción de imagen. | "IfNotPresent" |
ledger.image.tag | Etiqueta de imagen usada para el despliegue. | "" (por defecto Chart.AppVersion) |
ledger.imagePullSecrets | Secretos para extraer imágenes de un registro privado. | [] |
ledger.nameOverride | Anula el nombre predeterminado generado por Helm. | "" |
ledger.fullnameOverride | Anula el nombre completo generado por Helm. | "" |
ledger.podAnnotations | Anotaciones de pod para metadatos adicionales. | {} |
ledger.podSecurityContext | Contexto de seguridad aplicado a nivel de pod. | {} |
ledger.securityContext.* | Define ajustes de contexto de seguridad para el contenedor. | Ver values.yaml |
ledger.pdb.enabled | Especifica si PodDisruptionBudget está habilitado. | true |
ledger.pdb.minAvailable | Número mínimo de pods disponibles. | 1 |
ledger.pdb.maxUnavailable | Número máximo de pods no disponibles. | 1 |
ledger.pdb.annotations | Anotaciones para el PodDisruptionBudget. | {} |
ledger.deploymentUpdate.* | Estrategia de actualización del despliegue. | Ver values.yaml |
ledger.service.type | Tipo de servicio de Kubernetes. | "ClusterIP" |
ledger.service.port | Puerto para la API HTTP. | 3000 |
ledger.service.annotations | Anotaciones para el servicio. | {} |
ledger.ingress.enabled | Especifica si Ingress está habilitado. | false |
ledger.ingress.className | Nombre de clase de Ingress. | "" |
ledger.ingress.annotations | Anotaciones adicionales de ingress. | {} |
ledger.ingress.hosts | Hosts configurados para Ingress y rutas asociadas. | [] |
ledger.ingress.tls | Configuraciones TLS para Ingress. | [] |
ledger.resources.* | Solicitudes/límites de recursos de CPU/Memoria. | Ver values.yaml |
ledger.autoscaling.enabled | Especifica si el autoescalado está habilitado. | true |
ledger.autoscaling.minReplicas | Número mínimo de réplicas para autoescalado. | 2 |
ledger.autoscaling.maxReplicas | Número máximo de réplicas para autoescalado. | 5 |
ledger.autoscaling.targetCPUUtilizationPercentage | Porcentaje objetivo de utilización de CPU para autoescalado. | 80 |
ledger.autoscaling.targetMemoryUtilizationPercentage | Porcentaje objetivo de utilización de memoria para autoescalado. | 80 |
ledger.nodeSelector | Selectores de nodo para programación de pods. | {} |
ledger.tolerations | Tolerancias para programación de pods. | {} |
ledger.affinity | Reglas de afinidad para programación de pods. | {} |
ledger.configmap.* | Variables de entorno para el servicio. | Ver values.yaml |
ledger.secrets.* | Secretos para el servicio. | Ver values.yaml |
ledger.useExistingSecret | Usar un secreto existente en lugar de crear uno nuevo. | false |
ledger.existingSecretName | El nombre del secreto existente a usar. | "" |
ledger.extraEnvVars | Una lista de variables de entorno adicionales. | [] |
ledger.serviceAccount.create | Especifica si se debe crear la cuenta de servicio. | true |
ledger.serviceAccount.annotations | Anotaciones para la cuenta de servicio. | {} |
ledger.serviceAccount.name | Nombre de cuenta de servicio. Si no se define, se generará automáticamente. | "" |
Crear secreto de Ledger manualmente
Si deseas usar un Secret de Kubernetes existente para el servicio ledger, puedes crearlo manualmente:El servicio Ledger usa credenciales de base de datos específicas por módulo (onboarding y transaction) ya que combina ambos módulos.
Onboarding (legacy)
| Parámetro | Descripción | Valor predeterminado |
|---|---|---|
onboarding.name | Nombre del servicio. | "onboarding" |
onboarding.replicaCount | Número de réplicas para el servicio onboarding. | 2 |
onboarding.image.repository | Repositorio para la imagen del contenedor del servicio onboarding. | "lerianstudio/midaz-onboarding" |
onboarding.image.pullPolicy | Política de extracción de imagen. | "IfNotPresent" |
onboarding.image.tag | Etiqueta de imagen usada para el despliegue. | "3.3.4" |
onboarding.imagePullSecrets | Secretos para extraer imágenes de un registro privado. | [] |
onboarding.nameOverride | Anula el nombre predeterminado generado por Helm. | "" |
onboarding.fullnameOverride | Anula el nombre completo generado por Helm. | "" |
onboarding.podAnnotations | Anotaciones de pod para metadatos adicionales. | {} |
onboarding.podSecurityContext | Contexto de seguridad aplicado a nivel de pod. | {} |
onboarding.securityContext.* | Define ajustes de contexto de seguridad para el contenedor. | Ver values.yaml |
onboarding.pdb.enabled | Especifica si PodDisruptionBudget está habilitado. | true |
onboarding.pdb.minAvailable | Número mínimo de pods disponibles. | 1 |
onboarding.pdb.maxUnavailable | Número máximo de pods no disponibles. | 1 |
onboarding.pdb.annotations | Anotaciones para el PodDisruptionBudget. | {} |
onboarding.deploymentUpdate.* | Estrategia de actualización del despliegue. | Ver values.yaml |
onboarding.service.type | Tipo de servicio de Kubernetes. | "ClusterIP" |
onboarding.service.port | Puerto para la API HTTP. | 3000 |
onboarding.service.annotations | Anotaciones para el servicio. | {} |
onboarding.ingress.enabled | Especifica si Ingress está habilitado. | false |
onboarding.ingress.className | Nombre de clase de Ingress. | "" |
onboarding.ingress.annotations | Anotaciones adicionales de ingress. | {} |
onboarding.ingress.hosts | Hosts configurados para Ingress y rutas asociadas. | "" |
onboarding.ingress.tls | Configuraciones TLS para Ingress. | [] |
onboarding.resources.* | Solicitudes/límites de recursos de CPU/Memoria. | Ver values.yaml |
onboarding.autoscaling.enabled | Especifica si el autoescalado está habilitado. | true |
onboarding.autoscaling.minReplicas | Número mínimo de réplicas para autoescalado. | 2 |
onboarding.autoscaling.maxReplicas | Número máximo de réplicas para autoescalado. | 5 |
onboarding.autoscaling.targetCPUUtilizationPercentage | Porcentaje objetivo de utilización de CPU para autoescalado. | 80 |
onboarding.autoscaling.targetMemoryUtilizationPercentage | Porcentaje objetivo de utilización de memoria para autoescalado. | 80 |
onboarding.nodeSelector | Selectores de nodo para programación de pods. | {} |
onboarding.tolerations | Tolerancias para programación de pods. | {} |
onboarding.affinity | Reglas de afinidad para programación de pods. | {} |
onboarding.configmap.* | Variables de entorno para el servicio. | Ver values.yaml |
onboarding.secrets.* | Secretos para el servicio. | Ver values.yaml |
onboarding.useExistingSecret | Usar un secreto existente en lugar de crear uno nuevo. | false |
onboarding.existingSecretName | El nombre del secreto existente a usar. | "" |
onboarding.extraEnvVars | Una lista de variables de entorno adicionales. | [] |
onboarding.serviceAccount.create | Especifica si se debe crear la cuenta de servicio. | true |
onboarding.serviceAccount.annotations | Anotaciones para la cuenta de servicio. | {} |
onboarding.serviceAccount.name | Nombre de cuenta de servicio. Si no se define, se generará automáticamente. | "" |
Crear secreto de Onboarding manualmente
Si deseas usar un Secret de Kubernetes existente para el servicio onboarding:Transaction (legacy)
| Parámetro | Descripción | Valor predeterminado |
|---|---|---|
transaction.name | Nombre del servicio. | "transaction" |
transaction.replicaCount | Número de réplicas para el servicio transaction. | 1 |
transaction.image.repository | Repositorio para la imagen del contenedor del servicio transaction. | "lerianstudio/midaz-transaction" |
transaction.image.pullPolicy | Política de extracción de imagen. | "IfNotPresent" |
transaction.image.tag | Etiqueta de imagen usada para el despliegue. | "3.3.4" |
transaction.imagePullSecrets | Secretos para extraer imágenes de un registro privado. | [] |
transaction.nameOverride | Anula el nombre predeterminado generado por Helm. | "" |
transaction.fullnameOverride | Anula el nombre completo generado por Helm. | "" |
transaction.podAnnotations | Anotaciones de pod para metadatos adicionales. | {} |
transaction.podSecurityContext | Contexto de seguridad para el pod. | {} |
transaction.securityContext.* | Define ajustes de contexto de seguridad para el contenedor. | Ver values.yaml |
transaction.pdb.enabled | Habilitar o deshabilitar PodDisruptionBudget. | true |
transaction.pdb.minAvailable | Número mínimo de pods disponibles. | 2 |
transaction.pdb.maxUnavailable | Número máximo de pods no disponibles. | 1 |
transaction.pdb.annotations | Anotaciones para el PodDisruptionBudget. | {} |
transaction.deploymentUpdate.* | Estrategia de actualización del despliegue. | Ver values.yaml |
transaction.service.type | Tipo de servicio de Kubernetes. | "ClusterIP" |
transaction.service.port | Puerto para la API HTTP. | 3001 |
transaction.service.annotations | Anotaciones para el servicio. | {} |
transaction.ingress.enabled | Habilitar o deshabilitar ingress. | false |
transaction.ingress.className | Nombre de clase de Ingress. | "" |
transaction.ingress.annotations | Anotaciones adicionales de ingress. | {} |
transaction.ingress.hosts | Hosts configurados para ingress y rutas asociadas. | [] |
transaction.ingress.tls | Configuración TLS para ingress. | [] |
transaction.resources.* | Solicitudes/límites de recursos de CPU/Memoria. | Ver values.yaml |
transaction.autoscaling.enabled | Habilitar o deshabilitar autoescalado horizontal de pods. | true |
transaction.autoscaling.minReplicas | Número mínimo de réplicas para autoescalado. | 1 |
transaction.autoscaling.maxReplicas | Número máximo de réplicas para autoescalado. | 5 |
transaction.autoscaling.targetCPUUtilizationPercentage | Porcentaje objetivo de utilización de CPU para autoescalado. | 80 |
transaction.autoscaling.targetMemoryUtilizationPercentage | Porcentaje objetivo de utilización de memoria para autoescalado. | 80 |
transaction.nodeSelector | Selector de nodo para programar pods en nodos específicos. | {} |
transaction.tolerations | Tolerancias para programación en nodos con taints. | {} |
transaction.affinity | Reglas de afinidad para programación de pods. | {} |
transaction.configmap.* | Variables de entorno para el servicio. | Ver values.yaml |
transaction.secrets.* | Secretos para el servicio. | Ver values.yaml |
transaction.useExistingSecret | Usar un secreto existente en lugar de crear uno nuevo. | false |
transaction.existingSecretName | El nombre del secreto existente a usar. | "" |
transaction.extraEnvVars | Una lista de variables de entorno adicionales. | [] |
transaction.serviceAccount.create | Especifica si se debe crear una ServiceAccount. | true |
transaction.serviceAccount.annotations | Anotaciones para la ServiceAccount. | {} |
transaction.serviceAccount.name | Nombre de la cuenta de servicio. | "" |
Crear secreto de Transaction manualmente
Si deseas usar un Secret de Kubernetes existente para el servicio transaction:El servicio transaction requiere una clave de secreto adicional
RABBITMQ_CONSUMER_PASS comparado con onboarding.CRM (Customer Relationship Management)
El serviciocrm proporciona APIs para gestionar datos de holders y sus relaciones con las cuentas del ledger. Anteriormente disponible como un chart separado (plugin-crm) desplegado en el namespace midaz-plugins, el CRM ahora está integrado en el chart principal de Helm de Midaz y se despliega en el namespace midaz.
Si actualmente estás usando
plugin-crm en el namespace midaz-plugins, recomendamos migrar a este nuevo workload de CRM integrado. Consulta la guía de Actualización de Helm para los pasos de migración.| Parámetro | Descripción | Valor predeterminado |
|---|---|---|
crm.enabled | Habilitar o deshabilitar el servicio CRM. | false |
crm.name | Nombre del servicio. | "crm" |
crm.replicaCount | Número de réplicas para el servicio CRM. | 1 |
crm.image.repository | Repositorio para la imagen del contenedor del servicio CRM. | "ghcr.io/lerianstudio/midaz-crm" |
crm.image.pullPolicy | Política de extracción de imagen. | "Always" |
crm.image.tag | Etiqueta de imagen usada para el despliegue. | "3.5.0" |
crm.imagePullSecrets | Secretos para extraer imágenes de un registro privado. | [] |
crm.nameOverride | Anula el nombre predeterminado generado por Helm. | "" |
crm.fullnameOverride | Anula el nombre completo generado por Helm. | "" |
crm.podAnnotations | Anotaciones de pod para metadatos adicionales. | {} |
crm.podSecurityContext | Contexto de seguridad aplicado a nivel de pod. | {} |
crm.securityContext.* | Define ajustes de contexto de seguridad para el contenedor. | Ver values.yaml |
crm.pdb.enabled | Especifica si PodDisruptionBudget está habilitado. | true |
crm.pdb.minAvailable | Número mínimo de pods disponibles. | 1 |
crm.pdb.maxUnavailable | Número máximo de pods no disponibles. | 1 |
crm.pdb.annotations | Anotaciones para el PodDisruptionBudget. | {} |
crm.deploymentUpdate.type | Tipo de estrategia de despliegue. | "RollingUpdate" |
crm.deploymentUpdate.maxSurge | Número máximo de pods que pueden crearse sobre el número deseado de pods. | 1 |
crm.deploymentUpdate.maxUnavailable | Número máximo de pods que pueden estar no disponibles durante la actualización. | 1 |
crm.service.type | Tipo de servicio de Kubernetes. | "ClusterIP" |
crm.service.port | Puerto del servicio. | 4003 |
crm.ingress.enabled | Especifica si Ingress está habilitado. | false |
crm.ingress.className | Nombre de clase de Ingress. | "" |
crm.ingress.annotations | Anotaciones adicionales de ingress. | {} |
crm.ingress.hosts | Hosts configurados para Ingress y rutas asociadas. | [] |
crm.ingress.tls | Configuraciones TLS para Ingress. | [] |
crm.resources.* | Solicitudes/límites de recursos de CPU/Memoria. | Ver values.yaml |
crm.autoscaling.enabled | Especifica si el autoescalado está habilitado. | true |
crm.autoscaling.minReplicas | Número mínimo de réplicas para autoescalado. | 1 |
crm.autoscaling.maxReplicas | Número máximo de réplicas para autoescalado. | 3 |
crm.autoscaling.targetCPUUtilizationPercentage | Porcentaje objetivo de utilización de CPU para autoescalado. | 80 |
crm.autoscaling.targetMemoryUtilizationPercentage | Porcentaje objetivo de utilización de memoria para autoescalado. | 80 |
crm.nodeSelector | Selectores de nodo para programación de pods. | {} |
crm.tolerations | Tolerancias para programación de pods. | {} |
crm.affinity | Reglas de afinidad para programación de pods. | {} |
crm.configmap.* | Variables de entorno para el servicio. | Ver values.yaml |
crm.secrets.* | Secretos para el servicio. | Ver values.yaml |
crm.useExistingSecret | Usar un secreto existente en lugar de crear uno nuevo. | false |
crm.existingSecretName | El nombre del secreto existente a usar. | "" |
crm.extraEnvVars | Una lista de variables de entorno adicionales. | {} |

