Referencia de componentes de Midaz

El chart de Helm de Midaz despliega cuatro posibles componentes de servicio: Ledger (unificado, recomendado), Onboarding (legacy), Transaction (legacy) y CRM (opcional). Cada componente tiene su propio deployment, servicio, ingress y configuración de autoescalado.

Decisión rápida: Nuevas instalaciones → habilita Ledger, deshabilita Onboarding y Transaction. Migrando desde v4.x → consulta la Guía de migración. ¿Necesitas CRM? → configura crm.enabled: true.

Recomendado para nuevas instalaciones: Usa el servicio unificado Ledger. Los servicios separados de Onboarding y Transaction aún están soportados pero se convertirán en legacy en una futura versión.

Ledger (recomendado)

El servicio ledger 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).

Habilitar el servicio Ledger:

ledger:
  enabled: true

onboarding:
  enabled: false

transaction:
  enabled: false

Cuando Ledger está habilitado, los ingresses de onboarding y transaction redirigirán automáticamente el tráfico al servicio ledger, manteniendo compatibilidad con configuraciones DNS existentes.

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.	`3002`
`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:

kubectl create secret generic midaz-ledger \
  --from-literal=DB_ONBOARDING_PASSWORD='<tu-contraseña-db-onboarding>' \
  --from-literal=DB_ONBOARDING_REPLICA_PASSWORD='<tu-contraseña-db-onboarding-replica>' \
  --from-literal=MONGO_ONBOARDING_PASSWORD='<tu-contraseña-mongo-onboarding>' \
  --from-literal=DB_TRANSACTION_PASSWORD='<tu-contraseña-db-transaction>' \
  --from-literal=DB_TRANSACTION_REPLICA_PASSWORD='<tu-contraseña-db-transaction-replica>' \
  --from-literal=MONGO_TRANSACTION_PASSWORD='<tu-contraseña-mongo-transaction>' \
  --from-literal=REDIS_PASSWORD='<tu-contraseña-redis>' \
  --from-literal=RABBITMQ_DEFAULT_PASS='<tu-contraseña-rabbitmq>' \
  --from-literal=RABBITMQ_CONSUMER_PASS='<tu-contraseña-consumer-rabbitmq>' \
  -n midaz

El servicio Ledger usa credenciales de base de datos específicas por módulo (onboarding y transaction) ya que combina ambos módulos.

Luego configura el servicio Ledger para usar este secreto existente:

ledger:
  enabled: true
  useExistingSecret: true
  existingSecretName: "midaz-ledger"

Onboarding (legacy)

El servicio Onboarding aún está soportado pero se convertirá en legacy en una futura versión. Recomendamos usar el servicio unificado Ledger para nuevas instalaciones.

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.5.3"`
`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:

kubectl create secret generic midaz-onboarding \
  --from-literal=MONGO_PASSWORD='<tu-contraseña-mongo>' \
  --from-literal=DB_PASSWORD='<tu-contraseña-db>' \
  --from-literal=DB_REPLICA_PASSWORD='<tu-contraseña-db-replica>' \
  --from-literal=RABBITMQ_DEFAULT_PASS='<tu-contraseña-rabbitmq>' \
  --from-literal=REDIS_PASSWORD='<tu-contraseña-redis>' \
  -n midaz

Luego configura el servicio onboarding para usar este secreto existente:

onboarding:
  useExistingSecret: true
  existingSecretName: "midaz-onboarding"

Transaction (legacy)

El servicio Transaction aún está soportado pero se convertirá en legacy en una futura versión. Recomendamos usar el servicio unificado Ledger para nuevas instalaciones.

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.5.3"`
`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:

kubectl create secret generic midaz-transaction \
  --from-literal=MONGO_PASSWORD='<tu-contraseña-mongo>' \
  --from-literal=DB_PASSWORD='<tu-contraseña-db>' \
  --from-literal=DB_REPLICA_PASSWORD='<tu-contraseña-db-replica>' \
  --from-literal=RABBITMQ_DEFAULT_PASS='<tu-contraseña-rabbitmq>' \
  --from-literal=RABBITMQ_CONSUMER_PASS='<tu-contraseña-consumer-rabbitmq>' \
  --from-literal=REDIS_PASSWORD='<tu-contraseña-redis>' \
  -n midaz

El servicio transaction requiere una clave de secreto adicional RABBITMQ_CONSUMER_PASS comparado con onboarding.

Luego configura el servicio transaction para usar este secreto existente:

transaction:
  useExistingSecret: true
  existingSecretName: "midaz-transaction"

CRM (Customer relationship management)

El servicio crm 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.

Para más detalles sobre la funcionalidad de CRM, consulta la Documentación de CRM.

Habilitar el servicio CRM:

crm:
  enabled: true
  configmap:
    MONGO_HOST: "midaz-mongodb"  # Usa tu host de MongoDB
    MONGO_NAME: "crm"
    MONGO_USER: "midaz"
  secrets:
    MONGO_PASSWORD: "lerian"

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.	`"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.3"`
`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.	`{}`

Crear secreto de CRM manualmente

Si deseas usar un Secret de Kubernetes existente para el servicio CRM:

kubectl create secret generic midaz-crm \
  --from-literal=LCRYPTO_HASH_SECRET_KEY='<tu-clave-secreta-hash>' \
  --from-literal=LCRYPTO_ENCRYPT_SECRET_KEY='<tu-clave-secreta-cifrado>' \
  --from-literal=MONGO_PASSWORD='<tu-contraseña-mongo>' \
  -n midaz

Luego configura el servicio CRM para usar este secreto existente:

crm:
  enabled: true
  useExistingSecret: true
  existingSecretName: "midaz-crm"

​Ledger (recomendado)

​Crear secreto de Ledger manualmente

​Onboarding (legacy)

​Crear secreto de Onboarding manualmente

​Transaction (legacy)

​Crear secreto de Transaction manualmente

​CRM (Customer relationship management)

​Crear secreto de CRM manualmente

Ledger (recomendado)

Crear secreto de Ledger manualmente

Onboarding (legacy)

Crear secreto de Onboarding manualmente

Transaction (legacy)

Crear secreto de Transaction manualmente

CRM (Customer relationship management)

Crear secreto de CRM manualmente