Production values reference

This is a complete, annotated values.yaml reference for production deployments. Copy it, adapt the placeholders to your environment, and deploy.

This is a reference configuration. You must replace all placeholder values (marked with {...}) with your actual infrastructure details before deploying.

How to use

Copy the full configuration below into a file called values-production.yaml
Replace all {...} placeholders with your actual values
Review each section and adjust resource limits for your expected workload
Deploy:

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

Full production values

The Ledger Settings API replaces the deprecated ACCOUNT_TYPE_VALIDATION and TRANSACTION_ROUTE_VALIDATION environment variables. Use PATCH /v1/organizations/{org_id}/ledgers/{ledger_id}/settings to configure accounting validation per ledger.

# =============================================================================
# Midaz Production Values Reference
# =============================================================================
# This file configures Midaz for a production Kubernetes environment with:
# - Unified Ledger service
# - External databases (PostgreSQL, MongoDB, RabbitMQ, Valkey/Redis)
# - Ingress with TLS
# - Observability enabled
# - High availability with autoscaling
# =============================================================================

# -- Global name overrides
nameOverride: "midaz"
fullnameOverride: ""
namespaceOverride: "midaz"

# =============================================================================
# GLOBAL: External database bootstrap jobs
# =============================================================================
# These jobs run after install and before every upgrade to create databases,
# users, and permissions.
# Enable them when using external (non-bundled) databases.

global:
  # -- Bootstrap job for external PostgreSQL
  externalPostgresDefinitions:
    enabled: true
    connection:
      host: "{your-postgres-host}"       # e.g., "prod-postgres.example.com"
      port: "5432"
    postgresAdminLogin:
      # Recommended: use an existing Kubernetes Secret
      useExistingSecret:
        name: "{your-postgres-admin-secret}"  # Must contain DB_USER_ADMIN and DB_ADMIN_PASSWORD keys
      # Alternative: inline credentials (NOT recommended for production)
      # username: "postgres"
      # password: "{your-admin-password}"
    midazCredentials:
      useExistingSecret:
        name: "{your-midaz-credentials-secret}"  # Must contain DB_PASSWORD_MIDAZ key
      # Alternative: inline
      # password: "{your-midaz-password}"

  # -- Bootstrap job for external RabbitMQ
  externalRabbitmqDefinitions:
    enabled: true
    connection:
      protocol: "https"                   # Use "https" for production
      host: "{your-rabbitmq-host}"        # e.g., "prod-rabbitmq.example.com"
      port: "15672"                       # HTTP management port
      portAmqp: "5672"                    # AMQP port
    rabbitmqAdminLogin:
      useExistingSecret:
        name: "{your-rabbitmq-admin-secret}"  # Must contain RABBITMQ_ADMIN_USER and RABBITMQ_ADMIN_PASS
    appCredentials:
      useExistingSecret:
        name: "{your-rabbitmq-app-credentials}"  # Must contain RABBITMQ_DEFAULT_PASS and RABBITMQ_CONSUMER_PASS

  # -- CRM and Fees run inside the Ledger, each with its own MongoDB database.
  # With the bundled MongoDB disabled, set their hosts or the install fails.
  datastores:
    mongoCrm:
      host: "{your-mongodb-host}"
    mongoFees:
      host: "{your-mongodb-host}"

# =============================================================================
# LEDGER: onboarding, transaction, CRM, and Fees in one service
# =============================================================================

ledger:
  enabled: true

  image:
    repository: lerianstudio/midaz-ledger
    pullPolicy: IfNotPresent
    tag: ""  # Defaults to Chart.AppVersion; pin a specific version for production

  # -- Security context (non-root, read-only filesystem)
  securityContext:
    runAsGroup: 1000
    runAsUser: 1000
    runAsNonRoot: true
    capabilities:
      drop:
        - ALL
    readOnlyRootFilesystem: true

  # -- PodDisruptionBudget: ensure at least 2 pods during disruptions
  pdb:
    enabled: true
    minAvailable: 2

  # -- Rolling update with zero downtime
  deploymentUpdate:
    type: RollingUpdate
    maxSurge: 1
    maxUnavailable: 0

  service:
    type: ClusterIP
    port: 3002

  # -- Ingress with TLS
  ingress:
    enabled: true
    className: "{your-ingress-class}"     # e.g., "nginx", "alb", "traefik"
    annotations:
      # NGINX example:
      nginx.ingress.kubernetes.io/proxy-body-size: "10m"
      nginx.ingress.kubernetes.io/proxy-read-timeout: "60"
      # AWS ALB example (uncomment if using ALB):
      # alb.ingress.kubernetes.io/scheme: internal
      # alb.ingress.kubernetes.io/target-type: ip
      # alb.ingress.kubernetes.io/group.name: "midaz"
    hosts:
      - host: "{your-midaz-api-domain}"   # e.g., "api.midaz.example.com"
        paths:
          - path: /
            pathType: Prefix
    tls:
      - secretName: "{your-tls-secret}"   # e.g., "midaz-api-tls"
        hosts:
          - "{your-midaz-api-domain}"

  # -- Resource limits for production
  # Adjust based on your workload. These are starting recommendations.
  resources:
    requests:
      cpu: "1000m"
      memory: "512Mi"
    limits:
      cpu: "2000m"
      memory: "2Gi"

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

  # -- Pod anti-affinity: spread across nodes for high availability
  affinity:
    podAntiAffinity:
      preferredDuringSchedulingIgnoredDuringExecution:
        - weight: 100
          podAffinityTerm:
            labelSelector:
              matchExpressions:
                - key: app.kubernetes.io/name
                  operator: In
                  values:
                    - midaz-ledger
            topologyKey: kubernetes.io/hostname

  # -- External database configuration
  configmap:
    ENABLE_TELEMETRY: "true"
    # The chart default "local" is for workstations
    DEPLOYMENT_MODE: "byoc"
    # Auth Plugin: with ENV_NAME "production" (the chart default), the Ledger does not start without it
    PLUGIN_AUTH_ENABLED: "true"
    PLUGIN_AUTH_HOST: "{your-access-manager-auth-url}"
    # Accounting Configuration
    # Managed via Ledger Settings API. See PATCH /v1/organizations/{org_id}/ledgers/{ledger_id}/settings
    # Request body: {"accounting": {"validateRoutes": true, "validateAccountType": true}}
    # -- PostgreSQL: Onboarding module
    DB_ONBOARDING_HOST: "{your-postgres-host}"
    DB_ONBOARDING_USER: "midaz"
    DB_ONBOARDING_NAME: "onboarding"
    DB_ONBOARDING_PORT: "5432"
    DB_ONBOARDING_REPLICA_HOST: "{your-postgres-replica-host}"
    DB_ONBOARDING_REPLICA_USER: "midaz"
    DB_ONBOARDING_REPLICA_NAME: "onboarding"
    DB_ONBOARDING_REPLICA_PORT: "5432"
    # -- MongoDB: Onboarding module
    MONGO_ONBOARDING_URI: "mongodb"
    MONGO_ONBOARDING_HOST: "{your-mongodb-host}"
    MONGO_ONBOARDING_NAME: "onboarding"
    MONGO_ONBOARDING_USER: "midaz"
    MONGO_ONBOARDING_PORT: "27017"
    # -- PostgreSQL: Transaction module
    DB_TRANSACTION_HOST: "{your-postgres-host}"
    DB_TRANSACTION_USER: "midaz"
    DB_TRANSACTION_NAME: "transaction"
    DB_TRANSACTION_PORT: "5432"
    DB_TRANSACTION_REPLICA_HOST: "{your-postgres-replica-host}"
    DB_TRANSACTION_REPLICA_USER: "midaz"
    DB_TRANSACTION_REPLICA_NAME: "transaction"
    DB_TRANSACTION_REPLICA_PORT: "5432"
    # -- MongoDB: Transaction module
    MONGO_TRANSACTION_URI: "mongodb"
    MONGO_TRANSACTION_HOST: "{your-mongodb-host}"
    MONGO_TRANSACTION_NAME: "transaction"
    MONGO_TRANSACTION_USER: "midaz"
    MONGO_TRANSACTION_PORT: "27017"
    # -- Redis/Valkey
    REDIS_HOST: "{your-redis-host}:6379"
    # -- RabbitMQ
    RABBITMQ_URI: "amqp"                  # "amqps" for TLS, with the broker's TLS port below
    RABBITMQ_HOST: "{your-rabbitmq-host}"
    RABBITMQ_PORT_HOST: "5672"
    RABBITMQ_PORT_AMQP: "15672"
    RABBITMQ_DEFAULT_USER: "transaction"
    RABBITMQ_CONSUMER_USER: "consumer"
    RABBITMQ_TRANSACTION_ASYNC: "false"
    # -- Balance Sync Worker
    BALANCE_SYNC_BATCH_SIZE: "100"
    BALANCE_SYNC_FLUSH_TIMEOUT_MS: "1000"
    BALANCE_SYNC_POLL_INTERVAL_MS: "500"

  # -- Use existing Kubernetes Secrets (recommended)
  useExistingSecret: true
  existingSecretName: "midaz-ledger"
  # Create this secret manually before deploying:
  # kubectl create secret generic midaz-ledger \
  #   --from-literal=DB_ONBOARDING_PASSWORD='{password}' \
  #   --from-literal=DB_ONBOARDING_REPLICA_PASSWORD='{password}' \
  #   --from-literal=MONGO_ONBOARDING_PASSWORD='{password}' \
  #   --from-literal=DB_TRANSACTION_PASSWORD='{password}' \
  #   --from-literal=DB_TRANSACTION_REPLICA_PASSWORD='{password}' \
  #   --from-literal=MONGO_TRANSACTION_PASSWORD='{password}' \
  #   --from-literal=REDIS_PASSWORD='{password}' \
  #   --from-literal=RABBITMQ_DEFAULT_PASS='{password}' \
  #   --from-literal=RABBITMQ_CONSUMER_PASS='{password}' \
  #   --from-literal=MONGO_CRM_PASSWORD='{password}' \
  #   --from-literal=MONGO_FEES_PASSWORD='{password}' \
  #   --from-literal=LCRYPTO_HASH_SECRET_KEY='{generate-a-random-64-hex-string}' \
  #   --from-literal=LCRYPTO_ENCRYPT_SECRET_KEY='{generate-a-random-64-hex-string}' \
  #   -n midaz

  # -- The injected collector endpoint is plaintext. In production, the Ledger
  # does not start with a plaintext exporter unless this names a reason.
  extraEnvVars:
    ALLOW_INSECURE_OTEL: "node-local collector"

  serviceAccount:
    create: true
    annotations: {}

# =============================================================================
# BUNDLED DEPENDENCIES: All disabled (using external databases)
# =============================================================================
# In production, use managed database services (AWS RDS, Atlas, etc.)
# instead of bundled containers.

postgresql:
  enabled: false

mongodb:
  enabled: false

rabbitmq:
  enabled: false

valkey:
  enabled: false

# =============================================================================
# OBSERVABILITY
# =============================================================================

# -- Inject OTEL env vars into the ledger, crm and tracer deployments.
# The chart reads only `enabled` here. The exporter endpoint is fixed at
# $(HOST_IP):4317, so this needs an OTLP collector on every node.
# To export elsewhere, set enabled: false and set
# global.observability.otlpEndpoint to an https:// endpoint instead.
otel-collector-lerian:
  enabled: true

The chart ignores any other key under otel-collector-lerian, such as external, extraEnvs, exporters, or opentelemetry-collector. You configure collector routing (processors, exporters, API keys) in the collector’s own chart, not here. See Configuring observability.

The chart ships no Grafana templates. A grafana: block in your values file renders nothing.

Key decisions explained

Why external databases?

Production deployments should use managed database services for:

Automated backups and point-in-time recovery
High availability with automatic failover
Monitoring and alerting built-in
Scaling without application downtime
Security patching managed by the provider

Why use Kubernetes Secrets instead of inline passwords?

Inline passwords in values.yaml are visible in Helm release history and may be committed to version control. Using useExistingSecret: true with pre-created Kubernetes Secrets:

Keeps credentials out of Helm values
Allows rotation without a Helm upgrade. Restart the pods to load the new values.
Integrates with secret management tools (Vault, External Secrets Operator, Sealed Secrets)

Pod anti-affinity

The podAntiAffinity rule prefers to place Ledger pods on different nodes, so a single node failure is less likely to stop the service.

Checklist before deploying

Create Kubernetes Secrets

Create all required secrets in the midaz namespace before running helm install:

midaz-ledger (database and message broker credentials, and the CRM encryption keys)
The bootstrap Secrets that the global section names

Configure DNS

Point your domains to the ingress controller’s external IP:

{your-midaz-api-domain} → ingress IP

Provision TLS certificates

Either use cert-manager for automatic certificate provisioning or manually create TLS secrets for each domain.

Verify database connectivity

Ensure your Kubernetes cluster can reach all external databases. Test with:

kubectl run test-pg --rm -it --image=postgres:17 -- \
  psql -h {your-postgres-host} -U {your-admin-user} -d postgres -c "SELECT 1"

Review resource limits

Adjust CPU and memory limits based on your expected transaction volume. Use the values in this reference as starting points.

Deploy

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

Verify deployment

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

Using Helm - Full installation guide with all configuration options
Upgrading Midaz - Step-by-step upgrade procedures
Troubleshooting - Diagnosing common deployment issues
Uninstalling Midaz - Cleanup procedures
Helm chart source - Full values.yaml with all available parameters

Introduction

Midaz

Other products

Production values reference

How to use

Full production values

Key decisions explained

Why external databases?

Why use Kubernetes Secrets instead of inline passwords?

Pod anti-affinity

Checklist before deploying

​How to use

​Full production values

​Key decisions explained

​Why external databases?

​Why use Kubernetes Secrets instead of inline passwords?

​Pod anti-affinity

​Checklist before deploying

​Related resources

How to use

Full production values

Key decisions explained

Why external databases?

Why use Kubernetes Secrets instead of inline passwords?

Pod anti-affinity

Checklist before deploying

Related resources