Referencia de valores para producción

Consulta la referencia anotada de values.yaml listo para producción para desplegar Midaz en Kubernetes con Helm y ajustar parámetros con seguridad.

Esta página proporciona una referencia completa y anotada de values.yaml optimizada para despliegues en producción. Cópiala, adapta los marcadores de posición a tu entorno y despliega.

Esta es una configuración de referencia. Debes reemplazar todos los valores de marcador de posición (marcados con {...}) con los datos reales de tu infraestructura antes de desplegar.

​

Cómo usar

---

1. Copia la configuración completa a continuación en un archivo llamado values-production.yaml
2. Reemplaza todos los marcadores {...} con tus valores reales
3. Revisa cada sección y ajusta los límites de recursos para tu carga de trabajo esperada
4. Despliega:

helm install midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
  --version <version> \
  -n midaz \
  --create-namespace \
  -f values-production.yaml

​

Valores completos de producción

---

Las variables de entorno ACCOUNT_TYPE_VALIDATION y TRANSACTION_ROUTE_VALIDATION han sido deprecadas y reemplazadas por la API de Configuración de Ledger. Usa PATCH /v1/organizations/{org_id}/ledgers/{ledger_id}/settings para configurar la validación contable por ledger.

# =============================================================================
# Midaz Production Values Reference
# =============================================================================
# Este archivo configura Midaz para un entorno Kubernetes de producción con:
# - Servicio Ledger unificado
# - Bases de datos externas (PostgreSQL, MongoDB, RabbitMQ, Valkey/Redis)
# - Ingress con TLS
# - Observabilidad habilitada
# - CRM habilitado
# - Alta disponibilidad con autoscaling
# =============================================================================

# -- Sobrecargas de nombre globales
nameOverride: "midaz"
fullnameOverride: ""
namespaceOverride: "midaz"

# =============================================================================
# GLOBAL: Jobs de arranque para bases de datos externas
# =============================================================================

global:
  # -- Job de arranque para PostgreSQL externo
  externalPostgresDefinitions:
    enabled: true
    connection:
      host: "{tu-host-postgres}"          # ej: "prod-postgres.example.com"
      port: "5432"
    postgresAdminLogin:
      useExistingSecret:
        name: "{tu-secret-admin-postgres}" # Debe contener DB_USER_ADMIN y DB_ADMIN_PASSWORD
    midazCredentials:
      useExistingSecret:
        name: "{tu-secret-credenciales-midaz}" # Debe contener DB_PASSWORD_MIDAZ

  # -- Job de arranque para RabbitMQ externo
  externalRabbitmqDefinitions:
    enabled: true
    connection:
      protocol: "https"
      host: "{tu-host-rabbitmq}"
      port: "15672"
      portAmqp: "5672"
    rabbitmqAdminLogin:
      useExistingSecret:
        name: "{tu-secret-admin-rabbitmq}"
    appCredentials:
      useExistingSecret:
        name: "{tu-secret-app-rabbitmq}"

# =============================================================================
# LEDGER: Servicio unificado (recomendado para nuevas instalaciones)
# =============================================================================

ledger:
  enabled: true
  replicaCount: 3

  image:
    repository: lerianstudio/midaz-ledger
    pullPolicy: IfNotPresent
    tag: ""

  securityContext:
    runAsGroup: 1000
    runAsUser: 1000
    runAsNonRoot: true
    capabilities:
      drop:
        - ALL
    readOnlyRootFilesystem: true

  pdb:
    enabled: true
    minAvailable: 2
    maxUnavailable: 1

  deploymentUpdate:
    type: RollingUpdate
    maxSurge: 1
    maxUnavailable: 0

  service:
    type: ClusterIP
    port: 3002

  ingress:
    enabled: true
    className: "{tu-clase-ingress}"
    annotations:
      nginx.ingress.kubernetes.io/proxy-body-size: "10m"
      nginx.ingress.kubernetes.io/proxy-read-timeout: "60"
    hosts:
      - host: "{tu-dominio-api-midaz}"
        paths:
          - path: /
            pathType: Prefix
    tls:
      - secretName: "{tu-secret-tls}"
        hosts:
          - "{tu-dominio-api-midaz}"

  resources:
    requests:
      cpu: "1000m"
      memory: "512Mi"
    limits:
      cpu: "2000m"
      memory: "2Gi"

  autoscaling:
    enabled: true
    minReplicas: 3
    maxReplicas: 10
    targetCPUUtilizationPercentage: 70
    targetMemoryUtilizationPercentage: 80

  affinity:
    podAntiAffinity:
      preferredDuringSchedulingIgnoredDuringExecution:
        - weight: 100
          podAffinityTerm:
            labelSelector:
              matchExpressions:
                - key: app.kubernetes.io/name
                  operator: In
                  values:
                    - ledger
            topologyKey: kubernetes.io/hostname

  configmap:
    ENABLE_TELEMETRY: "true"
    PLUGIN_AUTH_ENABLED: "false"
    PLUGIN_AUTH_HOST: ""
    # Accounting Configuration
    # Managed via Ledger Settings API — see PATCH /v1/organizations/{org_id}/ledgers/{ledger_id}/settings
    # Request body: {"accounting": {"validateRoutes": true, "validateAccountType": true}}
    DB_ONBOARDING_HOST: "{tu-host-postgres}"
    DB_ONBOARDING_USER: "midaz"
    DB_ONBOARDING_NAME: "onboarding"
    DB_ONBOARDING_PORT: "5432"
    DB_ONBOARDING_REPLICA_HOST: "{tu-host-replica-postgres}"
    DB_ONBOARDING_REPLICA_USER: "midaz"
    DB_ONBOARDING_REPLICA_NAME: "onboarding"
    DB_ONBOARDING_REPLICA_PORT: "5432"
    MONGO_ONBOARDING_URI: "mongodb"
    MONGO_ONBOARDING_HOST: "{tu-host-mongodb}"
    MONGO_ONBOARDING_NAME: "onboarding"
    MONGO_ONBOARDING_USER: "midaz"
    MONGO_ONBOARDING_PORT: "27017"
    DB_TRANSACTION_HOST: "{tu-host-postgres}"
    DB_TRANSACTION_USER: "midaz"
    DB_TRANSACTION_NAME: "transaction"
    DB_TRANSACTION_PORT: "5432"
    DB_TRANSACTION_REPLICA_HOST: "{tu-host-replica-postgres}"
    DB_TRANSACTION_REPLICA_USER: "midaz"
    DB_TRANSACTION_REPLICA_NAME: "transaction"
    DB_TRANSACTION_REPLICA_PORT: "5432"
    MONGO_TRANSACTION_URI: "mongodb"
    MONGO_TRANSACTION_HOST: "{tu-host-mongodb}"
    MONGO_TRANSACTION_NAME: "transaction"
    MONGO_TRANSACTION_USER: "midaz"
    MONGO_TRANSACTION_PORT: "27017"
    REDIS_HOST: "{tu-host-redis}:6379"
    RABBITMQ_URI: "amqps"
    RABBITMQ_HOST: "{tu-host-rabbitmq}"
    RABBITMQ_PORT_HOST: "5672"
    RABBITMQ_PORT_AMQP: "15672"
    RABBITMQ_DEFAULT_USER: "transaction"
    RABBITMQ_CONSUMER_USER: "consumer"
    RABBITMQ_TRANSACTION_ASYNC: "false"
    AUDIT_LOG_ENABLED: "true"
    # -- Balance Sync Worker
    BALANCE_SYNC_BATCH_SIZE: "100"
    BALANCE_SYNC_FLUSH_TIMEOUT_MS: "1000"
    BALANCE_SYNC_POLL_INTERVAL_MS: "500"

  useExistingSecret: true
  existingSecretName: "midaz-ledger"

  serviceAccount:
    create: true
    annotations: {}

# =============================================================================
# CRM
# =============================================================================

crm:
  enabled: true
  replicaCount: 2

  image:
    repository: lerianstudio/midaz-crm
    pullPolicy: IfNotPresent
    tag: ""

  securityContext:
    runAsGroup: 1000
    runAsUser: 1000
    runAsNonRoot: true
    capabilities:
      drop:
        - ALL
    readOnlyRootFilesystem: true

  pdb:
    enabled: true
    minAvailable: 1
    maxUnavailable: 1

  service:
    type: ClusterIP
    port: 4003

  ingress:
    enabled: true
    className: "{tu-clase-ingress}"
    hosts:
      - host: "{tu-dominio-api-crm}"
        paths:
          - path: /
            pathType: Prefix
    tls:
      - secretName: "{tu-secret-tls-crm}"
        hosts:
          - "{tu-dominio-api-crm}"

  resources:
    requests:
      cpu: "200m"
      memory: "256Mi"
    limits:
      cpu: "500m"
      memory: "512Mi"

  autoscaling:
    enabled: true
    minReplicas: 2
    maxReplicas: 5
    targetCPUUtilizationPercentage: 80
    targetMemoryUtilizationPercentage: 80

  configmap:
    ENV_NAME: "production"
    PLUGIN_AUTH_ENABLED: "false"
    PLUGIN_AUTH_ADDRESS: ""
    MONGO_HOST: "{tu-host-mongodb}"
    MONGO_NAME: "crm"
    MONGO_PORT: "27017"
    MONGO_USER: "midaz"

  useExistingSecret: true
  existingSecretName: "midaz-crm"

# =============================================================================
# DEPENDENCIAS INCLUIDAS: Todas deshabilitadas (usando bases de datos externas)
# =============================================================================

postgresql:
  enabled: false

mongodb:
  enabled: false

rabbitmq:
  enabled: false

valkey:
  enabled: false

# =============================================================================
# OBSERVABILIDAD
# =============================================================================

# -- Inyecta las variables de entorno de OTEL en los deployments ledger y crm.
# El esquema acepta SOLO `enabled`. El endpoint del exportador es fijo en
# $(HOST_IP):4317, por lo que requiere un colector OTLP en cada nodo.
# Para exportar a otro destino, define enabled: false y coloca
# OTEL_EXPORTER_OTLP_ENDPOINT en ledger.configmap / crm.configmap.
otel-collector-lerian:
  enabled: true

No agregues external, extraEnvs, exporters ni opentelemetry-collector bajo otel-collector-lerian. El esquema del chart es estricto y helm install/helm upgrade falla con additional properties … not allowed. El enrutamiento del colector (processors, exporters, API keys) se configura en el chart del propio colector, no aquí — consulta Configuración de la observabilidad.

El chart ya no incluye un stack de Grafana — esos templates se eliminaron en la versión v5.0.0 del chart. Un bloque grafana: en tu archivo de values no renderiza nada.

​

Decisiones clave explicadas

---

​

¿Por qué Ledger en lugar de Onboarding + Transaction?

El servicio unificado ledger es el enfoque recomendado para todas las nuevas instalaciones. Combina ambos módulos en un solo despliegue, reduciendo la carga operativa:

• Menos pods para gestionar y monitorear
• Configuración simplificada (un solo configmap/secret)
• Un solo endpoint de ingress
• Mejor utilización de recursos
• Será la única opción en futuras versiones

​

¿Por qué bases de datos externas?

Los despliegues de producción deben usar servicios de bases de datos administrados para:

• Copias de seguridad automáticas y recuperación en un punto en el tiempo
• Alta disponibilidad con failover automático
• Monitoreo y alertas integrados
• Escalamiento sin tiempo de inactividad
• Parches de seguridad administrados por el proveedor

Servicios administrados recomendados:

Dependencia	AWS	GCP	Azure
PostgreSQL	Amazon RDS	Cloud SQL	Azure Database for PostgreSQL
MongoDB	Amazon DocumentDB o MongoDB Atlas	MongoDB Atlas	Azure Cosmos DB (MongoDB API)
RabbitMQ	Amazon MQ	Auto-administrado en GKE	Auto-administrado en AKS
Redis/Valkey	Amazon ElastiCache	Memorystore	Azure Cache for Redis

​

¿Por qué usar Kubernetes Secrets en lugar de contraseñas en línea?

Las contraseñas en línea en values.yaml son visibles en el historial de versiones de Helm y pueden ser comprometidas en control de versiones. Usar useExistingSecret: true con Secrets de Kubernetes pre-creados:

• Mantiene las credenciales fuera de los valores de Helm
• Permite rotación sin necesidad de upgrade de Helm
• Se integra con herramientas de gestión de secretos (Vault, External Secrets Operator, Sealed Secrets)

​

Anti-afinidad de pods

La regla podAntiAffinity distribuye los pods de Ledger en diferentes nodos, de modo que la falla de un solo nodo no afecte todo el servicio.

​

Checklist antes de desplegar

---

1. Crear Kubernetes Secrets

   Crea todos los secrets requeridos en el namespace midaz antes de ejecutar helm install:

   • midaz-ledger (credenciales de bases de datos y broker de mensajes)
   • midaz-crm (claves de encriptación y contraseña de MongoDB)
   • otel-api-key (si usas telemetría de Lerian)
2. Configurar DNS

   Apunta tus dominios a la IP externa del controlador de ingress:

   • {your-midaz-api-domain} → IP del ingress
   • {your-crm-api-domain} → IP del ingress
   • {your-grafana-domain} → IP del ingress (solo si ejecutas Grafana por separado — este chart no renderiza ninguno)
3. Provisionar certificados TLS

   Usa cert-manager para el aprovisionamiento automático de certificados o crea manualmente los secrets TLS para cada dominio.

4. Verificar conectividad a bases de datos

   Asegúrate de que tu cluster Kubernetes pueda alcanzar todas las bases de datos externas. Pruébalo con:

   kubectl run test-pg --rm -it --image=postgres:17 -- \
     psql -h {your-postgres-host} -U midaz -d onboarding -c "SELECT 1"
   
5. Revisar límites de recursos

   Ajusta los límites de CPU y memoria según tu volumen de transacciones esperado. Los valores de esta referencia son puntos de partida para cargas de trabajo moderadas.

6. Desplegar

   helm install midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
     --version <version> \
     -n midaz \
     --create-namespace \
     -f values-production.yaml
   
7. Verificar despliegue

   kubectl get pods -n midaz -o wide
   kubectl get ingress -n midaz
   helm list -n midaz
   

​

Recursos relacionados

---

• Usando Helm - Guía completa de instalación
• Actualizando Midaz - Procedimientos de actualización
• Solución de problemas - Diagnóstico de problemas
• Desinstalación - Procedimientos de limpieza
• Código fuente del chart - values.yaml completo con todos los parámetros