Usando Helm

Antes de comenzar

Antes de desplegar Midaz con Helm, asegúrese de tener lo siguiente en su lugar:

Kubernetes (v1.30+) – Necesitará un clúster en ejecución para desplegar.
Helm 3+ – Helm debe estar instalado y disponible. Ejecute helm version para confirmar.

Cómo desplegar Midaz

Para poner en funcionamiento Midaz con Helm, ejecute:

helm install midaz oci://registry-1.docker.io/lerianstudio/midaz-helm --version <version> -n midaz --create-namespace

Esto crea un namespace llamado midaz (si aún no existe) y despliega el chart. Para confirmar que el despliegue se realizó correctamente:

helm list -n midaz

ConsejoEncontrará el Helm chart usado en esta guía en nuestro repositorio de GitHub. Siéntase libre de hacer fork, ajustar valores o extender según sea necesario.

Configuración de ingress para diferentes controladores

Midaz soporta diferentes controladores ingress para exponer servicios como Transacción, Ledger y Console. Necesitará tener un controlador configurado en su clúster y configurarlo en el archivo values.yaml. A continuación se muestran ejemplos para las opciones más comunes:

Controlador ingress NGINX

ingress:
  enabled: true
  className: "nginx"
  annotations: {}
  hosts:
    - host: midaz.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: midaz-tls
      hosts:
        - midaz.example.com

ConsejoConsulte la documentación oficial de ingress-nginx para una referencia completa sobre anotaciones de Nginx.

AWS ALB (Application Load Balancer)

ingress:
  enabled: true
  className: "alb"
  annotations:
    alb.ingress.kubernetes.io/scheme: internal
    alb.ingress.kubernetes.io/target-type: ip
    alb.ingress.kubernetes.io/group.name: "midaz"
    alb.ingress.kubernetes.io/healthcheck-path: "/healthz"
    alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80}, {"HTTPS": 443}]'
  hosts:
    - host: midaz.example.com
      paths:
        - path: /
          pathType: Prefix
  tls: []

Controlador Ingress Traefik

ingress:
  enabled: true
  className: "traefik"
  annotations:
    traefik.ingress.kubernetes.io/router.entrypoints: "web, websecure"
    traefik.ingress.kubernetes.io/router.tls: "true"
  hosts:
    - host: midaz.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: midaz-tls
      hosts:
        - midaz.example.com

Configuración de observabilidad

Midaz usa Grafana Docker OpenTelemetry LGTM para impulsar su stack de observabilidad; esta configuración recopila y exporta datos de telemetría como trazas y métricas.

Acceso al dashboard de Grafana

Para acceder al dashboard localmente:

kubectl port-forward svc/midaz-grafana 3000:3000 -n midaz

Luego diríjase a: http://localhost:3000.

Acceso DNS interno para Grafana

Para exponer Grafana dentro de su clúster o red privada a través de DNS, habilite y configure Ingress de esta manera:

grafana:
  enabled: true
  name: grafana

  ingress:
    enabled: true
    className: "nginx"
    annotations:
      nginx.ingress.kubernetes.io/rewrite-target: /
      nginx.ingress.kubernetes.io/whitelist-source-range: ""
    hosts:
      - host: "midaz-ote.example.com"
        paths:
          - path: /
            pathType: Prefix
    tls: []

Deshabilitación de observabilidad

Puede deshabilitar el stack de observabilidad completamente configurando:

grafana:
  enabled: false

Configuración de dependencias

Midaz viene con dependencias predeterminadas que están habilitadas de fábrica. Puede desactivarlas si está usando infraestructura existente.

Valkey

Versión: 2.4.7.
Repositorio: Bitnami.
Deshabilitar: valkey.enabled = false.

Para usar su propia instancia de Redis/Valkey:

onboarding:
  configmap:
    REDIS_HOST: { your-host }
    REDIS_PORT: { your-port }
    REDIS_USER: { your-user }
  secrets:
    REDIS_PASSWORD: { your-password }

transaction:
  configmap:
    REDIS_HOST: { your-host }
    REDIS_PORT: { your-port }
    REDIS_USER: { your-user }
  secrets:
    REDIS_PASSWORD: { your-password }

PostgreSQL

Versión: 16.3.0.
Repositorio: Bitnami.
Deshabilitar: postgresql.enabled = false.

Ejemplo de configuración de PostgreSQL externo:

onboarding:
  configmap:
    DB_HOST: { your-host }
    DB_USER: { your-user }
    DB_PORT: { your-port }
    DB_REPLICA_HOST: { your-replica-host }
    DB_REPLICA_USER: { your-replica-user }
    DB_REPLICA_PORT: { your-replica-port }
  secrets:
    DB_PASSWORD: { your-password }
    DB_REPLICA_PASSWORD: { your-replica-password }

transaction:
  configmap:
    DB_HOST: { your-host }
    DB_USER: { your-user }
    DB_PORT: { your-port }
    DB_REPLICA_HOST: { your-replica-host }
    DB_REPLICA_USER: { your-replica-user }
    DB_REPLICA_PORT: { your-replica-port }
  secrets:
    DB_PASSWORD: { your-password }
    DB_REPLICA_PASSWORD: { your-replica-password }

MongoDB

Versión: 15.4.5.
Repositorio: Bitnami.
Deshabilitar: mongodb.enabled = false.

Para conectarse a un MongoDB externo:

onboarding:
  configmap:
    MONGO_HOST: { your-host }
    MONGO_NAME: { your-db-name }
    MONGO_USER: { your-user }
    MONGO_PORT: { your-port }
  secrets:
    MONGO_PASSWORD: { your-password }

transaction:
  configmap:
    MONGO_HOST: { your-host }
    MONGO_NAME: { your-db-name }
    MONGO_USER: { your-user }
    MONGO_PORT: { your-port }
  secrets:
    MONGO_PASSWORD: { your-password }

RabbitMQ

Versión: 16.0.0.
Repositorio: Bitnami.
Deshabilitar: rabbitmq.enabled = false.

Si está usando una instancia externa de RabbitMQ, necesita cargar el archivo de definiciones requerido. Sin estas colas, intercambios y enlaces en su lugar, Midaz no funcionará como se espera. Puede cargar las definiciones de dos maneras:

Automáticamente

Habilite la bandera externalRabbitmqDefinitions en su archivo values.yaml para aplicar las definiciones predeterminadas automáticamente:

   global:
     ## -- Enable or disable loading of default RabbitMQ definitions to external host
     externalRabbitmqDefinitions:
       enabled: true

Esto crea un Job de Kubernetes que carga las definiciones de RabbitMQ en su instancia externa.

AtenciónEste 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 necesita ejecutarlo nuevamente, elimine el release e instálelo de nuevo.

Manualmente

Si prefiere aplicar las definiciones usted mismo, use la API HTTP de RabbitMQ:

 curl -u { your-host-user }: { your-host-pass } -X POST -H "Content-Type: application/json" -d @load_definitions.json http://{ your-host }: { your-host-port }/api/definitions

Encontrará el archivo load_definitions.json en: charts/midaz/files/rabbitmq/load_definitions.json.

Use su propio RabbitMQ

Si ya tiene una instancia de RabbitMQ en ejecución, puede deshabilitar la dependencia integrada y apuntar los componentes de Midaz a su configuración externa:

onboarding:
  configmap:
    RABBITMQ_HOST: { your-host }
    RABBITMQ_DEFAULT_USER: { your-host-user }
    RABBITMQ_PORT_HOST: { your-host-port }
    RABBITMQ_PORT_AMQP: { your-host-amqp-port }

  secrets:
    RABBITMQ_DEFAULT_PASS: { your-host-pass }

transaction:
  configmap:
    RABBITMQ_HOST: { your-host }
    RABBITMQ_DEFAULT_USER: { your-host-user }
    RABBITMQ_PORT_HOST: { your-host-port }
    RABBITMQ_PORT_AMQP: { your-host-amqp-port }

  secrets:
    RABBITMQ_DEFAULT_PASS: { your-host-pass }

Componentes de Midaz

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

Onboarding

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 utilizada para el despliegue.	`"2.1.0"`
`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 del pod para metadatos adicionales.	`{}`
`onboarding.podSecurityContext`	Contexto de seguridad aplicado a nivel del pod.	`{}`
`onboarding.securityContext.runAsGroup`	Define el ID de grupo para el usuario que ejecuta el proceso dentro del contenedor.	`1000`
`onboarding.securityContext.runAsUser`	Define el ID de usuario para el proceso que se ejecuta dentro del contenedor.	`1000`
`onboarding.securityContext.runAsNonRoot`	Asegura que el proceso no se ejecute como root.	`true`
`onboarding.securityContext.capabilities.drop`	Lista de capacidades a eliminar.	`["ALL"]`
`onboarding.securityContext.readOnlyRootFilesystem`	Define el sistema de archivos raíz como de solo lectura.	`true`
`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.type`	Tipo de estrategia de despliegue.	`"RollingUpdate"`
`onboarding.deploymentUpdate.maxSurge`	Número máximo de pods que se pueden crear sobre el número deseado de pods.	`"100%"`
`onboarding.deploymentUpdate.maxUnavailable`	Número máximo de pods que pueden no estar disponibles durante la actualización.	`0`
`onboarding.service.type`	Tipo de servicio Kubernetes.	`"ClusterIP"`
`onboarding.service.port`	Puerto para la API HTTP.	`3000`
`onboarding.ingress.enabled`	Especifica si Ingress está habilitado.	`false`
`onboarding.ingress.className`	Nombre de la clase 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.limits.cpu`	Límite de CPU asignado para los pods.	`"1500m"`
`onboarding.resources.limits.memory`	Límite de memoria asignado para los pods.	`"512Gi"`
`onboarding.resources.requests.cpu`	Solicitud mínima de CPU para los pods.	`"768m"`
`onboarding.resources.requests.memory`	Solicitud mínima de memoria para los pods.	`"256Mi"`
`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 de utilización de CPU objetivo para autoescalado.	`80`
`onboarding.autoscaling.targetMemoryUtilizationPercentage`	Porcentaje de utilización de memoria objetivo para autoescalado.	`80`
`onboarding.nodeSelector`	Selectores de nodo para programación de pods.	`{}`
`onboarding.tolerations`	Toleraciones para programación de pods.	`{}`
`onboarding.affinity`	Reglas de afinidad para programación de pods.	`{}`
`onboarding.configmap`	Configuraciones adicionales en ConfigMap.	Encuentre los valores predeterminados en la configuración.
`onboarding.secrets`	Secretos adicionales para el servicio.	Encuentre los valores predeterminados en la configuración.
`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 la cuenta de servicio. Si no se define, se generará automáticamente.	`""`

Transacción

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 utilizada para el despliegue.	`"2.1.0"`
`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 del pod para metadatos adicionales.	`{}`
`transaction.podSecurityContext`	Contexto de seguridad para el pod.	`{}`
`transaction.securityContext.runAsGroup`	Define el ID de grupo para el usuario que ejecuta el proceso dentro del contenedor.	`1000`
`transaction.securityContext.runAsUser`	Define el ID de usuario para el proceso que se ejecuta dentro del contenedor.	`1000`
`transaction.securityContext.runAsNonRoot`	Asegura que el proceso no se ejecute como root.	`true`
`transaction.securityContext.capabilities.drop`	Lista de capacidades de Linux a eliminar.	`["ALL"]`
`transaction.securityContext.readOnlyRootFilesystem`	Define el sistema de archivos raíz como de solo lectura.	`true`
`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.type`	Tipo de estrategia de despliegue.	`"RollingUpdate"`
`transaction.deploymentUpdate.maxSurge`	Número máximo de pods que se pueden crear sobre el número deseado de pods.	`"100%"`
`transaction.deploymentUpdate.maxUnavailable`	Número máximo de pods que pueden no estar disponibles durante la actualización.	`0`
`transaction.service.type`	Tipo de servicio Kubernetes.	`"ClusterIP"`
`transaction.service.port`	Puerto para la API HTTP.	`3001`
`transaction.ingress.enabled`	Habilitar o deshabilitar ingress.	`false`
`transaction.ingress.className`	Nombre de la clase Ingress.	`""`
`transaction.ingress.annotations`	Anotaciones adicionales de ingress.	`{}`
`transaction.ingress.hosts`	Hosts configurados para ingress y rutas asociadas.	`[{host: "", paths: [{path: "/", pathType: "Prefix"}]}]`
`transaction.ingress.tls`	Configuración TLS para ingress.	`[]`
`transaction.resources.limits.cpu`	Límite de CPU asignado para los pods.	`"2000m"`
`transaction.resources.limits.memory`	Límite de memoria asignado para los pods.	`"512Gi"`
`transaction.resources.requests.cpu`	Solicitud mínima de CPU para los pods.	`"768m"`
`transaction.resources.requests.memory`	Solicitud mínima de memoria para los pods.	`"256Mi"`
`transaction.autoscaling.enabled`	Habilitar o deshabilitar autoescalado horizontal de pods.	`true`
`transaction.autoscaling.minReplicas`	Número mínimo de réplicas para autoescalado.	`3`
`transaction.autoscaling.maxReplicas`	Número máximo de réplicas para autoescalado.	`9`
`transaction.autoscaling.targetCPUUtilizationPercentage`	Porcentaje de utilización de CPU objetivo para autoescalado.	`70`
`transaction.autoscaling.targetMemoryUtilizationPercentage`	Porcentaje de utilización de memoria objetivo para autoescalado.	`80`
`transaction.nodeSelector`	Selector de nodo para programar pods en nodos específicos.	`{}`
`transaction.tolerations`	Toleraciones para programación en nodos con taints.	`{}`
`transaction.affinity`	Reglas de afinidad para programación de pods.	`{}`
`transaction.configmap`	ConfigMap para variables de entorno y configuraciones.	Encuentre los valores predeterminados en la configuración.
`transaction.secrets`	Secretos para almacenar datos sensibles.	Encuentre los valores predeterminados en la configuración.
`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.	`""`

Console

Parámetro	Descripción	Valor Predeterminado
`console.name`	Nombre del servicio.	`"console"`
`console.enabled`	Habilitar o deshabilitar el servicio console.	`true`
`console.replicaCount`	Número de réplicas para el despliegue.	`1`
`console.image.repository`	Repositorio de imagen Docker para Console.	`"lerianstudio/midaz-console"`
`console.image.pullPolicy`	Política de extracción de imagen Docker.	`"IfNotPresent"`
`console.image.tag`	Etiqueta de imagen Docker utilizada para el despliegue.	`"1.25.1"`
`console.imagePullSecrets`	Secretos para extraer imágenes Docker de un registro privado.	`[]`
`console.nameOverride`	Anula el nombre del recurso.	`""`
`console.fullnameOverride`	Anula el nombre completo del recurso.	`""`
`console.podAnnotations`	Anotaciones para los pods.	`{}`
`console.podSecurityContext`	Contexto de seguridad aplicado a nivel del pod.	`{}`
`console.securityContext.runAsGroup`	Define el ID de grupo para el usuario que ejecuta el proceso dentro del contenedor.	`1000`
`console.securityContext.runAsUser`	Define el ID de usuario para el proceso que se ejecuta dentro del contenedor.	`1000`
`console.securityContext.runAsNonRoot`	Asegura que el proceso no se ejecute como root.	`true`
`console.securityContext.capabilities.drop`	Lista de capacidades de Linux a eliminar.	`["ALL"]`
`console.securityContext.readOnlyRootFilesystem`	Define el sistema de archivos raíz como de solo lectura.	`true`
`console.pdb.enabled`	Especifica si PodDisruptionBudget está habilitado.	`false`
`console.pdb.minAvailable`	Número mínimo de pods disponibles para PodDisruptionBudget.	`1`
`console.pdb.maxUnavailable`	Número máximo de pods no disponibles para PodDisruptionBudget.	`1`
`console.pdb.annotations`	Anotaciones para el PodDisruptionBudget.	`{}`
`console.deploymentUpdate.type`	Tipo de estrategia de despliegue.	`"RollingUpdate"`
`console.deploymentUpdate.maxSurge`	Número máximo de pods que se pueden crear sobre el número deseado de pods.	`"100%"`
`console.deploymentUpdate.maxUnavailable`	Número máximo de pods que pueden no estar disponibles durante la actualización.	`0`
`console.service.type`	Tipo de servicio Kubernetes.	`"ClusterIP"`
`console.service.port`	Puerto del servicio.	`8081`
`console.ingress.enabled`	Especifica si Ingress está habilitado.	`false`
`console.ingress.className`	Nombre de la clase Ingress.	`""`
`console.ingress.annotations`	Anotaciones adicionales para Ingress.	`{}`
`console.ingress.hosts`	Hosts configurados para Ingress y rutas asociadas.	`[{ "host": "", "paths": [{ "path": "/", "pathType": "Prefix" }] }]`
`console.ingress.tls`	Configuraciones TLS para Ingress.	`[]`
`console.resources.limits.cpu`	Límite de CPU asignado para los pods.	`"200m"`
`console.resources.limits.memory`	Límite de memoria asignado para los pods.	`"256Mi"`
`console.resources.requests.cpu`	Solicitud mínima de CPU para los pods.	`"100m"`
`console.resources.requests.memory`	Solicitud mínima de memoria para los pods.	`"128Mi"`
`console.autoscaling.enabled`	Especifica si el autoescalado horizontal de pods está habilitado.	`true`
`console.autoscaling.minReplicas`	Número mínimo de réplicas para autoescalado.	`1`
`console.autoscaling.maxReplicas`	Número máximo de réplicas para autoescalado.	`3`
`console.autoscaling.targetCPUUtilizationPercentage`	Porcentaje de utilización de CPU objetivo para autoescalado.	`80`
`console.autoscaling.targetMemoryUtilizationPercentage`	Porcentaje de utilización de memoria objetivo para autoescalado.	`80`
`console.nodeSelector`	Selectores de nodo para programación de pods.	`{}`
`console.tolerations`	Toleraciones para programación de pods.	`{}`
`console.affinity`	Reglas de afinidad para programación de pods.	`{}`
`console.configmap`	Configuraciones adicionales en el ConfigMap.	Encuentre los valores predeterminados en la configuración.
`console.secrets`	Secretos adicionales para el servicio.	`{}`
`console.serviceAccount.create`	Especifica si se debe crear la cuenta de servicio.	`true`
`console.serviceAccount.annotations`	Anotaciones para la cuenta de servicio.	`{}`
`console.serviceAccount.name`	Nombre de la cuenta de servicio. Si no se define, se generará automáticamente.	`""`

Inicio

Empezando

Entidades centrales

SDKs de Midaz

Libs de Midaz

Midaz CLI

Antes de comenzar

Cómo desplegar Midaz

Configuración de ingress para diferentes controladores

Controlador ingress NGINX

AWS ALB (Application Load Balancer)

Controlador Ingress Traefik

Configuración de observabilidad

Acceso al dashboard de Grafana

Acceso DNS interno para Grafana

Deshabilitación de observabilidad

Configuración de dependencias

Valkey

PostgreSQL

MongoDB

RabbitMQ

Automáticamente

Manualmente

Use su propio RabbitMQ

Componentes de Midaz

Onboarding

Transacción

Console

Inicio

Empezando

Entidades centrales

SDKs de Midaz

Libs de Midaz

Midaz CLI

​Antes de comenzar

​Cómo desplegar Midaz

​Configuración de ingress para diferentes controladores

​Controlador ingress NGINX

​AWS ALB (Application Load Balancer)

​Controlador Ingress Traefik

​Configuración de observabilidad

​Acceso al dashboard de Grafana

​Acceso DNS interno para Grafana

​Deshabilitación de observabilidad

​Configuración de dependencias

​Valkey

​PostgreSQL

​MongoDB

​RabbitMQ

​Automáticamente

​Manualmente

​Use su propio RabbitMQ

​Componentes de Midaz

​Onboarding

​Transacción

​Console

Antes de comenzar

Cómo desplegar Midaz

Configuración de ingress para diferentes controladores

Controlador ingress NGINX

AWS ALB (Application Load Balancer)

Controlador Ingress Traefik

Configuración de observabilidad

Acceso al dashboard de Grafana

Acceso DNS interno para Grafana

Deshabilitación de observabilidad

Configuración de dependencias

Valkey

PostgreSQL

MongoDB

RabbitMQ

Automáticamente

Manualmente

Use su propio RabbitMQ

Componentes de Midaz

Onboarding

Transacción

Console