Saltar al contenido principal
Esta guía te acompaña durante la instalación y configuración de un entorno Midaz en Kubernetes usando Helm. Encontrarás instrucciones para configurar controladores Ingress, habilitar observabilidad y gestionar dependencias.

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.
¿Quieres una comprensión más profunda de la arquitectura? Consulta la descripción general de la arquitectura de Midaz.

Instalar Midaz a través del chart de Helm

Para instalar Midaz usando Helm, ejecuta el siguiente comando:
helm install midaz oci://registry-1.docker.io/lerianstudio/midaz-helm --version <version> -n midaz --create-namespace
  • Reemplaza <version> con la versión deseada del chart de Helm. Puedes verificar las versiones disponibles ejecutando:
helm search repo oci://registry-1.docker.io/lerianstudio/midaz-helm --versions
Esto crea un namespace llamado midaz (si no existe ya) y despliega el chart. Para confirmar que el despliegue se realizó correctamente, ejecuta:
helm list -n midaz
El chart de Helm está en nuestro repositorio de GitHub. Puedes hacer un fork, personalizar los valores o extenderlo según sea necesario.

Configurar ingress


Ingress te permite exponer servicios de Midaz fuera del clúster de Kubernetes, vinculándolos a dominios específicos y certificados TLS. En este chart, puedes habilitar Ingress individualmente para los servicios Transaction, Onboarding y Console. Para usar Ingress, necesitarás un controlador Ingress ejecutándose en tu clúster (por ejemplo, NGINXAWS ALB o Traefik) y entradas DNS apuntando a él.
Puedes habilitar ingress por servicio en tu archivo values.yaml y configurar nombres de host, secretos TLS y cualquier anotación específica del controlador.
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 el values.yaml de la siguiente manera:
ingress:
  enabled: true
  className: "nginx"
  // El campo `annotations` se usa para agregar metadatos personalizados al recurso Nginx.
  // Las anotaciones son pares clave-valor que se pueden usar para adjuntar metadatos arbitrarios no identificativos a objetos.
  // Estas anotaciones pueden ser utilizadas por varias herramientas y bibliotecas para aumentar el comportamiento del recurso Nginx.
  // Ver más https://github.com/kubernetes/ingress-nginx/blob/main/docs/user-guide/nginx-configuration/annotations.md
  annotations: {}
  hosts:
    - host: midaz.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: midaz-tls  # Asegúrate de que este secreto exista o sea gestionado por cert-manager
      hosts:
        - midaz.example.com
Consulta la documentación oficial de Ingress-nginx para una referencia completa sobre las anotaciones de Nginx.

AWS ALB (Application Load Balancer)

Para el Controlador Ingress AWS ALB, configura el values.yaml de la siguiente manera:
ingress:
  enabled: true
  className: "alb"
  annotations:
    alb.ingress.kubernetes.io/scheme: internal  # Usa "internet-facing" para ALB público
    alb.ingress.kubernetes.io/target-type: ip   # Usa "instance" si apuntas a instancias EC2
    alb.ingress.kubernetes.io/group.name: "midaz"  # Agrupa recursos ALB bajo este nombre
    alb.ingress.kubernetes.io/healthcheck-path: "/healthz"  # Ruta de verificación de salud
    alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80}, {"HTTPS": 443}]'  # Escucha en HTTP y HTTPS
  hosts:
    - host: midaz.example.com
      paths:
        - path: /
          pathType: Prefix
  tls: []  # TLS es gestionado por el ALB usando certificados ACM

Controlador Ingress Traefik

Para Traefik, configura el values.yaml de la siguiente manera:
ingress:
  enabled: true
  className: "traefik"
  annotations:
    traefik.ingress.kubernetes.io/router.entrypoints: "web, websecure"  # Puntos de entrada definidos en Traefik
    traefik.ingress.kubernetes.io/router.tls: "true"  # Habilita TLS para esta ruta
  hosts:
    - host: midaz.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: midaz-tls  # Asegúrate de que este secreto exista y contenga el certificado TLS
      hosts:
        - midaz.example.com

Configurar observabilidad


Midaz usa Grafana, Docker y 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:
kubectl port-forward svc/midaz-grafana 3000:3000 -n midaz
Luego usa http://localhost:3000 para abrir el panel.

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:
grafana:
  enabled: true
  name: grafana
  ingress:
    enabled: true
    className: "nginx"
    annotations:
      nginx.ingress.kubernetes.io/rewrite-target: /
    hosts:
      - host: "midaz-ote.example.com"
        paths:
          - path: /
            pathType: Prefix
    tls: []

Deshabilitar observabilidad

Puedes deshabilitar completamente el stack de observabilidad configurando:
grafana:
  enabled: false

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.

Valkey

  • Versión: 2.4.7
  • Repositorio: Bitnami
  • Deshabilitar: valkey.enabled = false
Si tienes una instancia existente de Valkey o Redis, puedes deshabilitar esta dependencia y configurar los Componentes de Midaz para usar tu instancia externa, de esta manera:
onboarding:
  configmap:
    REDIS_HOST: { tu-host }:{ tu-puerto-host }
  secrets:
    REDIS_PASSWORD: { tu-contraseña-host }
transaction:
  configmap:
    REDIS_HOST: { tu-host }:{ tu-puerto-host }
  secrets:
    REDIS_PASSWORD: { tu-contraseña-host }

PostgreSQL

  • Versión: 16.3.0
  • Repositorio: Bitnami
  • Deshabilitar: postgresql.enabled = false
Si tienes una instancia existente de PostgreSQL, puedes deshabilitar esta dependencia y configurar los Componentes de Midaz para usar tu PostgreSQL externo, de esta manera:
onboarding:
  configmap:
    DB_HOST: { tu-host }
    DB_USER: { tu-usuario-host }
    DB_PORT: { tu-puerto-host }
    ## Replicación de DB
    DB_REPLICA_HOST: { tu-host-replicacion }
    DB_REPLICA_USER: { tu-usuario-host-replicacion }
    DB_REPLICA_PORT: { tu-puerto-host-replicacion }
  secrets:
    DB_PASSWORD: { tu-contraseña-host }
    DB_REPLICA_PASSWORD: { tu-contraseña-host-replicacion }
transaction:
  configmap:
    DB_HOST: { tu-host }
    DB_USER: { tu-usuario-host }
    DB_PORT: { tu-puerto-host }
    ## Replicación de DB
    DB_REPLICA_HOST: { tu-host-replicacion }
    DB_REPLICA_USER: { tu-usuario-host-replicacion }
    DB_REPLICA_PORT: { tu-puerto-host-replicacion }
  secrets:
    DB_PASSWORD: { tu-contraseña-host }
    DB_REPLICA_PASSWORD: { tu-contraseña-host-replicacion }

MongoDB

  • Versión: 15.4.5
  • Repositorio: Bitnami
  • Deshabilitar: mongodb.enabled = false
Si tienes una instancia existente de MongoDB, puedes deshabilitar esta dependencia y configurar los Componentes de Midaz para usar tu MongoDB externo, de esta manera:
onboarding:
  configmap:
    MONGO_HOST: { tu-host }
    MONGO_NAME: { tu-nombre-host }
    MONGO_USER: { tu-usuario-host }
    MONGO_PORT: { tu-puerto-host }
  secrets:
    MONGO_PASSWORD: { tu-contraseña-host }
transaction:
  configmap:
    MONGO_HOST: { tu-host }
    MONGO_NAME: { tu-nombre-host }
    MONGO_USER: { tu-usuario-host }
    MONGO_PORT: { tu-puerto-host }
  secrets:
    MONGO_PASSWORD: { tu-contraseña-host }

RabbitMQ

  • Versión: 16.0.0
  • Repositorio: Bitnami
  • Deshabilitar: rabbitmq.enabled = false
Si estás usando una instancia externa de RabbitMQ, necesitas cargar el archivo requerido load_definitions.json. Sin estas colas, intercambios y enlaces en su lugar, Midaz no funcionará como se espera. Puedes cargar las definiciones de una de dos maneras: Automáticamente Habilita el flag externalRabbitmqDefinitions en tu archivo values.yaml para aplicar las definiciones predeterminadas automáticamente:
global:
  # -- Habilitar o deshabilitar la carga de definiciones predeterminadas de RabbitMQ al host externo
  externalRabbitmqDefinitions:
    enabled: true
Esto crea un Job de Kubernetes que carga las definiciones de RabbitMQ en tu instancia externa.
Este Job solo se ejecuta durante la primera instalación del chart. Se activa mediante un hook post-install de Helm y no se ejecutará nuevamente durante actualizaciones o reinstalaciones.Si necesitas volver a ejecutarlo, elimina el release e instálalo nuevamente.
Manualmente Si prefieres aplicar las definiciones tú mismo, usa la API HTTP de RabbitMQ:
curl -u { tu-usuario-host }: { tu-contraseña-host } -X POST -H "Content-Type: application/json" -d @load_definitions.json http://{ tu-host }: { tu-puerto-host }/api/definitions
Encontrarás el archivo load_definitions.json en: charts/midaz/files/rabbitmq/load_definitions.json.

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:
onboarding:
configmap:
  RABBITMQ_HOST: { tu-host }
  RABBITMQ_DEFAULT_USER: { tu-usuario-host }
  RABBITMQ_PORT_HOST: { tu-puerto-host }
  RABBITMQ_PORT_AMQP: { tu-puerto-amqp-host }
secrets:
  RABBITMQ_DEFAULT_PASS: { tu-contraseña-host }
transaction:
configmap:
  RABBITMQ_HOST: { tu-host }
  RABBITMQ_DEFAULT_USER: { tu-usuario-host }
  RABBITMQ_PORT_HOST: { tu-puerto-host }
  RABBITMQ_PORT_AMQP: { tu-puerto-amqp-host }
secrets:
  RABBITMQ_DEFAULT_PASS: { tu-contraseña-host }

Nginx Proxy Manager (UIs de Plugins)

El NGINX Proxy Manager en este chart enruta el tráfico a las UIs de plugins. Por defecto, está deshabilitado, y todas las UIs de plugins solo son accesibles a través de este proxy cuando se habilita. Para activarlo, establece nginx.enabled: true en tu values.yaml.
  • También puedes configurar ingress para él estableciendo nginx.ingress.enabled: true.
Para habilitar la UI para un plugin específico, establece pluginsUi.enabled: true en la configuración del servicio Console y define los ajustes del plugin, por ejemplo:
console:
  pluginsUi:
    enabled: true
    plugins:
      plugin-crm-ui:
        enabled: true
        port: 8082
Para permitir que NGINX sirva las UIs de plugins, los charts de Helm correspondientes deben estar instalados con la UI habilitada en el namespace midaz-plugins.

Otell Collector

El Otell Collector recopila métricas de los componentes de Midaz. Está deshabilitado por defecto. Para habilitarlo, establece:
otell:
  enabled: true
Cuando está habilitado, automáticamente recopila y reenvía datos de telemetría de todos los servicios de Midaz en ejecución.

Componentes de Midaz


El sistema Midaz se ejecuta en cuatro capas distintas que trabajan juntas, distribuidas en cargas de trabajo segregadas:

Onboarding

ParámetroDescripciónValor predeterminado
onboarding.nameNombre del servicio."onboarding"
onboarding.replicaCountNúmero de réplicas para el servicio onboarding.2
onboarding.image.repositoryRepositorio para la imagen del contenedor del servicio onboarding."lerianstudio/midaz-onboarding"
onboarding.image.pullPolicyPolítica de extracción de imagen."IfNotPresent"
onboarding.image.tagEtiqueta de imagen usada para el despliegue."2.2.2"
onboarding.imagePullSecretsSecretos para extraer imágenes de un registro privado.[]
onboarding.nameOverrideAnula el nombre predeterminado generado por Helm.""
onboarding.fullnameOverrideAnula el nombre completo generado por Helm.""
onboarding.podAnnotationsAnotaciones de pod para metadatos adicionales.{}
onboarding.podSecurityContextContexto de seguridad aplicado a nivel de pod.{}
onboarding.securityContext.*Define ajustes de contexto de seguridad para el contenedor.Ver values.yaml
onboarding.pdb.enabledEspecifica si PodDisruptionBudget está habilitado.true
onboarding.pdb.minAvailableNúmero mínimo de pods disponibles.1
onboarding.pdb.maxUnavailableNúmero máximo de pods no disponibles.1
onboarding.pdb.annotationsAnotaciones para el PodDisruptionBudget.{}
onboarding.deploymentUpdate.*Estrategia de actualización del despliegue.Ver values.yaml
onboarding.service.typeTipo de servicio de Kubernetes."ClusterIP"
onboarding.service.portPuerto para la API HTTP.3000
onboarding.service.annotationsAnotaciones para el servicio.{}
onboarding.ingress.enabledEspecifica si Ingress está habilitado.false
onboarding.ingress.classNameNombre de clase de Ingress.""
onboarding.ingress.annotationsAnotaciones adicionales de ingress.{}
onboarding.ingress.hostsHosts configurados para Ingress y rutas asociadas.""
onboarding.ingress.tlsConfiguraciones TLS para Ingress.[]
onboarding.resources.*Solicitudes/límites de recursos de CPU/Memoria.Ver values.yaml
onboarding.autoscaling.enabledEspecifica si el autoescalado está habilitado.true
onboarding.autoscaling.minReplicasNúmero mínimo de réplicas para autoescalado.2
onboarding.autoscaling.maxReplicasNúmero máximo de réplicas para autoescalado.5
onboarding.autoscaling.targetCPUUtilizationPercentagePorcentaje objetivo de utilización de CPU para autoescalado.80
onboarding.autoscaling.targetMemoryUtilizationPercentagePorcentaje objetivo de utilización de memoria para autoescalado.80
onboarding.nodeSelectorSelectores de nodo para programación de pods.{}
onboarding.tolerationsTolerancias para programación de pods.{}
onboarding.affinityReglas 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.useExistingSecretUsar un secreto existente en lugar de crear uno nuevo.false
onboarding.existingSecretNameEl nombre del secreto existente a usar.""
onboarding.extraEnvVarsUna lista de variables de entorno adicionales.[]
onboarding.serviceAccount.createEspecifica si se debe crear la cuenta de servicio.true
onboarding.serviceAccount.annotationsAnotaciones para la cuenta de servicio.{}
onboarding.serviceAccount.nameNombre de cuenta de servicio. Si no se define, se generará automáticamente.""

Transaction

ParámetroDescripciónValor predeterminado
transaction.nameNombre del servicio."transaction"
transaction.replicaCountNúmero de réplicas para el servicio transaction.1
transaction.image.repositoryRepositorio para la imagen del contenedor del servicio transaction."lerianstudio/midaz-transaction"
transaction.image.pullPolicyPolítica de extracción de imagen."IfNotPresent"
transaction.image.tagEtiqueta de imagen usada para el despliegue."2.2.2"
transaction.imagePullSecretsSecretos para extraer imágenes de un registro privado.[]
transaction.nameOverrideAnula el nombre predeterminado generado por Helm.""
transaction.fullnameOverrideAnula el nombre completo generado por Helm.""
transaction.podAnnotationsAnotaciones de pod para metadatos adicionales.{}
transaction.podSecurityContextContexto de seguridad para el pod.{}
transaction.securityContext.*Define ajustes de contexto de seguridad para el contenedor.Ver values.yaml
transaction.pdb.enabledHabilitar o deshabilitar PodDisruptionBudget.true
transaction.pdb.minAvailableNúmero mínimo de pods disponibles.2
transaction.pdb.maxUnavailableNúmero máximo de pods no disponibles.1
transaction.pdb.annotationsAnotaciones para el PodDisruptionBudget.{}
transaction.deploymentUpdate.*Estrategia de actualización del despliegue.Ver values.yaml
transaction.service.typeTipo de servicio de Kubernetes."ClusterIP"
transaction.service.portPuerto para la API HTTP.3001
transaction.service.annotationsAnotaciones para el servicio.{}
transaction.ingress.enabledHabilitar o deshabilitar ingress.false
transaction.ingress.classNameNombre de clase de Ingress.""
transaction.ingress.annotationsAnotaciones adicionales de ingress.{}
transaction.ingress.hostsHosts configurados para ingress y rutas asociadas.[]
transaction.ingress.tlsConfiguración TLS para ingress.[]
transaction.resources.*Solicitudes/límites de recursos de CPU/Memoria.Ver values.yaml
transaction.autoscaling.enabledHabilitar o deshabilitar autoescalado horizontal de pods.true
transaction.autoscaling.minReplicasNúmero mínimo de réplicas para autoescalado.1
transaction.autoscaling.maxReplicasNúmero máximo de réplicas para autoescalado.5
transaction.autoscaling.targetCPUUtilizationPercentagePorcentaje objetivo de utilización de CPU para autoescalado.80
transaction.autoscaling.targetMemoryUtilizationPercentagePorcentaje objetivo de utilización de memoria para autoescalado.80
transaction.nodeSelectorSelector de nodo para programar pods en nodos específicos.{}
transaction.tolerationsTolerancias para programación en nodos con taints.{}
transaction.affinityReglas 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.useExistingSecretUsar un secreto existente en lugar de crear uno nuevo.false
transaction.existingSecretNameEl nombre del secreto existente a usar.""
transaction.extraEnvVarsUna lista de variables de entorno adicionales.[]
transaction.serviceAccount.createEspecifica si se debe crear una ServiceAccount.true
transaction.serviceAccount.annotationsAnotaciones para la ServiceAccount.{}
transaction.serviceAccount.nameNombre de la cuenta de servicio.""

Console

ParámetroDescripciónValor predeterminado
console.nameNombre del servicio."console"
console.enabledHabilitar o deshabilitar el servicio console.true
console.replicaCountNúmero de réplicas para el despliegue.1
console.image.repositoryRepositorio de imagen Docker para Console."lerianstudio/midaz-console"
console.image.pullPolicyPolítica de extracción de imagen Docker."IfNotPresent"
console.image.tagEtiqueta de imagen Docker usada para el despliegue."2.2.1"
console.imagePullSecretsSecretos para extraer imágenes Docker de un registro privado.[]
console.nameOverrideAnula el nombre del recurso.""
console.fullnameOverrideAnula el nombre completo del recurso.""
console.podAnnotationsAnotaciones para los pods.{}
console.podSecurityContextContexto de seguridad aplicado a nivel de pod.{}
console.securityContext.*Define ajustes de contexto de seguridad para el contenedor.Ver values.yaml
console.pdb.enabledEspecifica si PodDisruptionBudget está habilitado.false
console.pdb.minAvailableNúmero mínimo de pods disponibles para PodDisruptionBudget.1
console.pdb.maxUnavailableNúmero máximo de pods no disponibles para PodDisruptionBudget.1
console.pdb.annotationsAnotaciones para el PodDisruptionBudget.{}
console.deploymentUpdate.*Estrategia de actualización del despliegue.Ver values.yaml
console.service.typeTipo de servicio de Kubernetes."ClusterIP"
console.service.portPuerto del servicio.8081
console.service.annotationsAnotaciones para el servicio.{}
console.ingress.enabledEspecifica si Ingress está habilitado.false
console.ingress.classNameNombre de clase de Ingress.""
console.ingress.annotationsAnotaciones adicionales para Ingress.{}
console.ingress.hostsHosts configurados para Ingress y rutas asociadas.[]
console.ingress.tlsConfiguraciones TLS para Ingress.[]
console.resources.*Solicitudes/límites de recursos de CPU/Memoria.Ver values.yaml
console.autoscaling.enabledEspecifica si el autoescalado horizontal de pods está habilitado.true
console.autoscaling.minReplicasNúmero mínimo de réplicas para autoescalado.1
console.autoscaling.maxReplicasNúmero máximo de réplicas para autoescalado.3
console.autoscaling.targetCPUUtilizationPercentagePorcentaje objetivo de utilización de CPU para autoescalado.80
console.autoscaling.targetMemoryUtilizationPercentagePorcentaje objetivo de utilización de memoria para autoescalado.80
console.nodeSelectorSelectores de nodo para programación de pods.{}
console.tolerationsTolerancias para programación de pods.{}
console.affinityReglas de afinidad para programación de pods.{}
console.configmap.*Variables de entorno para el servicio.Ver values.yaml
console.secrets.*Secretos para el servicio.Ver values.yaml
console.useExistingSecretUsar un secreto existente en lugar de crear uno nuevo.false
console.existingSecretNameEl nombre del secreto existente a usar.""
console.extraEnvVarsUna lista de variables de entorno adicionales.[]
console.pluginsUi.enabledHabilitar o deshabilitar el proxy de UI de plugins.false
console.pluginsUi.plugins.*Configuración para cada UI de plugin.Ver values.yaml
console.serviceAccount.createEspecifica si se debe crear la cuenta de servicio.true
console.serviceAccount.annotationsAnotaciones para la cuenta de servicio.{}
console.serviceAccount.nameNombre de cuenta de servicio. Si no se define, se generará automáticamente.""
I