helm

Midaz Helm Chart

Chart Contract

Release name: The single-source Secret names are resolved collapse-aware from the bundled subcharts (common.names.dependency.fullname), so they follow any release name automatically — no midaz assumption. The bundled service hosts in configmap (e.g. midaz-postgresql-primary, midaz-mongodb-headless, midaz-valkey-primary, midaz-rabbitmq), however, are static literals that assume the release is named midaz (helm install midaz ...). If you install under a different release name, override the *_HOST entries under ledger.configmap/crm.configmap (or the equivalent global.datastores.* host masks) accordingly. Two more names do not follow the release name: the component Services are always midaz-ledger, midaz-crm and midaz-tracer (the midaz prefix comes from nameOverride, default midaz), so a TRACER_BASE_URL points at midaz-tracer:<port> whatever the release is called; and the tracer’s own DB_HOST does follow the release name (see the Tracer section). Mixed naming is therefore expected under a custom release name.

Uninstall keeps the data. helm uninstall leaves the bundled MongoDB volume (datadir-<release>-mongodb-0), the PostgreSQL volumes (data-<release>-postgresql-*) and both password Secrets (<release>-postgresql, <release>-mongodb), so a reinstall under the same release name opens the same data with the same passwords. Deleting the data is a separate, manual step: delete those PVCs and Secrets. Deleting only the Secrets resets nothing: a reinstall generates new passwords that the kept data never learned.

Source code can be found here:

This helm chart installs Midaz, a high-performance ledger.


Managed Cloud (global.cloud)

Point ledger/crm/tracer at a managed-cloud environment (AWS/GCP/Azure) instead of the bundled in-cluster PostgreSQL/MongoDB/Valkey/RabbitMQ, with one knob:

global:
  cloud: "aws"   # aws | gcp | azure — leave unset for the bundled dev topology
  datastores:
    postgresOnboarding:  { host: "my-rds.example.com", user: "midaz" }
    postgresTransaction: { host: "my-rds.example.com", user: "midaz" }
    mongoOnboarding:     { host: "my-docdb.example.com", user: "midaz" }
    mongoTransaction:    { host: "my-docdb.example.com", user: "midaz" }
    mongoCrm:            { host: "my-docdb.example.com", user: "midaz" }
    redis:               { host: "my-elasticache.example.com", port: "6379" }
    broker:              { host: "my-amazonmq.example.com" }
  env:
    name: "production"
  observability:
    enabled: true
  auth:
    host: "http://plugin-access-manager-auth:4000"

global.cloud sets the connection TOPOLOGY (TLS, AMQP scheme/ports, sslmode, DocumentDB connection params) for the masks above. Per-module identity (host/port/user — postgresOnboarding/postgresTransaction/mongoOnboarding/ mongoTransaction/mongoCrm/mongoFees) always comes from global.datastores or a dedicated ledger.datastores/crm.datastores/tracer.datastores override — a cloud preset can’t know your RDS host. TOPOLOGY-only fields that a cloud preset actually sets (postgres.ssl, mongo.params, redis.tls, broker.scheme/amqpPort/port) are shared across every module through the generic postgres/mongo/redis/broker keys, since onboarding/transaction/ crm/fees share one physical Postgres/Mongo engine in the overwhelming majority of real deployments even though their host/port/user can differ per module.

Precedence (highest to lowest): native <component>.configmap.<KEY> > dedicated <component>.datastores (this component’s own instance) > shared global.datastores (env-wide) > global.cloud topology preset (for the TOPOLOGY-only fields above) > chart default.

REDIS_HOST combines global.datastores.redis.host and .port (or the matching dedicated-tier fields) into the single host:port string the ledger service expects (e.g. host: "my-elasticache.example.com" + port: "6380" → REDIS_HOST=my-elasticache.example.com:6380); a native ledger.configmap.REDIS_HOST override is expected to already carry its own host:port and is used verbatim.

ENV_NAME is resolved once per component via global.env.name and reused as the default for that component’s OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT, so the two can’t drift out of sync; a native <component>.configmap.ENV_NAME (or .OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT) still overrides independently.

The ledger’s dedicated migration Job (templates/ledger/migrations-job.yaml) resolves its own DB_ONBOARDING_*/DB_TRANSACTION_* connection through the SAME masks as the ledger ConfigMap, so an operator who repoints the database via global.datastores/ledger.datastores migrates the exact host/db the app then connects to.

Copy values-template.yaml as your starting point — it documents every global.* mask with a working example. values.yaml is the full power-user reference; values.schema.json validates it.

Install Midaz Helm Chart:

Prerequisites:

To install Midaz using Helm, run:

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

Replace <version> with the desired chart version. This creates a namespace called midaz if it doesn’t already exist and deploys the Midaz Helm chart.

The default ledger and tracer image is the stable 4.4.0. A ledger.image.tag or tracer.image.tag of 4.5.0-beta.94 or later, the first image that serves the health port, turns on the health preset (HEALTH_PORT 8099, preset probes, PDB and rollout strategy). The ledger partition runner is on for any ledger.image.tag from 4.5.0-beta.1. Below 4.5.0-beta.94 the chart renders the 4.4 layout: probes on the main port, RABBITMQ_HEALTH_CHECK_URL on the ledger, READYZ_DRAIN_GRACE_SECONDS on the tracer, and it honors readinessProbe, livenessProbe, terminationGracePeriodSeconds, deploymentUpdate and pdb.maxUnavailable/minAvailable values.

Upgrading a release that runs a 4.5.0 pre-release (chart 10.3.0 to 10.3.2 on default values): set ledger.image.tag and tracer.image.tag to the running tag before helm upgrade. Without the pin the default 4.4.0 migration Job finds a schema newer than its migrations and fails (no migration found for version N), so the upgrade stops before any pod changes. ledger.migrations.enabled: false or tracer.migrations.enabled: false removes the stop of that component only, and with Argo CD an empty deploymentSyncWave lets a Deployment apply even when its migrations Job fails; keep the pin in those installs.

After installation, you can verify that the release was successful by listing the Helm releases in the midaz namespace:

$ helm list -n midaz

Configuring Ingress for Different Controllers

The Midaz Helm Chart supports different Ingress Controllers for exposing services. Ingress is configured per component, under ledger.ingress, crm.ingress and tracer.ingress; the chart has no top-level ingress: key, and one placed there is silently ignored (no Ingress is rendered). The examples below use ledger.ingress; the same fields apply to the other two components. Below are configurations for commonly used controllers.

Note: Before configuring Ingress, ensure that you have an Ingress Controller installed in your cluster. The Ingress Controller manages external access to services. Examples include NGINX, AWS ALB, and Traefik.

NGINX Ingress Controller

To use the NGINX Ingress Controller, configure the values.yaml as follows:

ledger:
  ingress:
    enabled: true
    className: "nginx"
    # The `annotations` field adds custom metadata to the Nginx resource.
    # Annotations are key-value pairs that augment the behavior of the Nginx resource.
    # See 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  # Ensure this secret exists or is managed by cert-manager
        hosts:
          - midaz.example.com

AWS ALB (Application Load Balancer)

For AWS ALB Ingress Controller, use the following configuration:

ledger:
  ingress:
    enabled: true
    className: "alb"
    annotations:
      alb.ingress.kubernetes.io/scheme: internal  # Use "internet-facing" for public ALB
      alb.ingress.kubernetes.io/target-type: ip   # Use "instance" if targeting EC2 instances
      alb.ingress.kubernetes.io/group.name: "midaz"  # Group ALB resources under this name
      alb.ingress.kubernetes.io/healthcheck-path: "/health"  # Health check path (constant /health on the main port; /readyz is served on the internal health port 8099)
      alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80}, {"HTTPS": 443}]'  # Listen on HTTP and HTTPS
    hosts:
      - host: midaz.example.com
        paths:
          - path: /
            pathType: Prefix
    tls: []  # TLS is managed by the ALB using ACM certificates

Traefik Ingress Controller

For Traefik, configure the values.yaml as follows:

ledger:
  ingress:
    enabled: true
    className: "traefik"
    annotations:
      traefik.ingress.kubernetes.io/router.entrypoints: "web, websecure"  # Entrypoints defined in Traefik
      traefik.ingress.kubernetes.io/router.tls: "true"  # Enable TLS for this route
    hosts:
      - host: midaz.example.com
        paths:
          - path: /
            pathType: Prefix
    tls:
      - secretName: midaz-tls  # Ensure this secret exists and contains the TLS certificate
        hosts:
          - midaz.example.com

Pod Spreading (global.scheduling.spread)

Every Deployment of this chart (ledger, crm and tracer) renders topologySpreadConstraints from the lerian-common spread preset. The default is soft (ScheduleAnyway) across nodes, so replicas of the same component are spread across nodes (e.g. spot nodes) whenever possible, but a pod is never left Pending because of it.

Zone spreading is off by default (zone: ""). When scoring a soft spread, the scheduler skips every node that lacks the topology.kubernetes.io/zone label, so on clusters without zone labels (bare-metal, k3s) a zone constraint silently cancels the node spread. Turn it on (zone: ScheduleAnyway) where every node carries zone labels (EKS, GKE, AKS).

global:
  scheduling:
    spread:
      enabled: true            # master switch
      hostname: ScheduleAnyway # kubernetes.io/hostname: ScheduleAnyway | DoNotSchedule | "" (off)
      zone: ""                 # topology.kubernetes.io/zone: same values (off by default)
      maxSkew: 1               # integer >= 1
      minDomains: 0            # DoNotSchedule constraints only; 0 = off
      nodeTaintsPolicy: ""     # Honor | Ignore | "" (Kubernetes default Ignore)
ledger:
  spread: { hostname: DoNotSchedule }  # field-level override of the global preset
  topologySpreadConstraints: []        # raw list; non-empty replaces the preset entirely

On EKS + Karpenter use a hard node spread:

global:
  scheduling:
    spread:
      hostname: DoNotSchedule
      zone: ScheduleAnyway
      maxSkew: 1
      minDomains: 2
      nodeTaintsPolicy: Honor

minDomains: 2 is required with DoNotSchedule. Skew is measured only against nodes that already exist, so on a single eligible node all replicas would otherwise share it. With fewer than 2 nodes the extra replica stays Pending until Karpenter launches another node. nodeTaintsPolicy: Honor stops tainted nodes (for example a node being drained) from counting as domains.

Precedence: <component>.topologySpreadConstraints (non-empty, wins entirely) > <component>.spread.<field> > global.scheduling.spread.<field> > off. Each preset constraint selects only the component’s own pods (labelSelector = the Deployment’s spec.selector.matchLabels) of the same ReplicaSet (matchLabelKeys: [pod-template-hash]), so a rolling update is never blocked by the old ReplicaSet’s pods, even with DoNotSchedule. Requires Kubernetes >= 1.27 (matchLabelKeys). Use DoNotSchedule only when the cluster can always provide enough distinct nodes/zones for the replica count (a hard constraint leaves extra pods Pending otherwise). Jobs (migrations, bootstrap) keep their nodeSelector / affinity / tolerations and are not spread.

Upgrade note: the preset is on by default, so upgrading to the chart version that introduces it adds topologySpreadConstraints to the pod template of every Deployment and triggers one rolling restart of each. No values change is required. To keep the previous pod template exactly, set global.scheduling.spread.enabled: false.

Midaz Components

Midaz deploys the following core services:

Ledger

Parameter Description Default Value
ledger.enabled Enable or disable the ledger service. true
ledger.name Service name. "ledger"
ledger.health.stack, tracer.health.stack Runtime stack for the health preset. Probes, HEALTH_PORT 8099 (/health, /readyz, internal health Service port only), drain, grace, rollout strategy and PDB are owned by the chart from image tag 4.5.0-beta.94; at those tags the render refuses probe, grace, SHUTDOWN_* and HEALTH_PORT overrides. go
ledger.health.shutdownSeconds SHUTDOWN_TIMEOUT in seconds, the one shutdown budget after the 15s drain; pod grace is drain + this + 10s. unset (preset: 30)
ledger.replicaCount Number of replicas for the ledger service. 2
ledger.image.repository Repository for the ledger service container image. "lerianstudio/midaz-ledger"
ledger.image.pullPolicy Image pull policy. "IfNotPresent"
ledger.image.tag Image tag used for deployment. From 4.5.0-beta.94 the health preset applies. "4.4.0"
ledger.imagePullSecrets Secrets for pulling images from a private registry. []
ledger.nameOverride Overrides the default generated name by Helm. ""
ledger.fullnameOverride Overrides the full name generated by Helm. ""
ledger.podAnnotations Pod annotations for additional metadata. {}
ledger.podSecurityContext Security context applied at the pod level. {}
ledger.securityContext.* Security context for every ledger container: the application, its wait-for-dependencies init container and the migration Job. See values.yaml
ledger.pdb.enabled Specifies whether PodDisruptionBudget is enabled. true
ledger.pdb.annotations Annotations for the PodDisruptionBudget. {}
ledger.service.type Kubernetes service type. "ClusterIP"
ledger.service.port Port for the HTTP API. 3002
ledger.service.annotations Annotations for the service. {}
ledger.ingress.enabled Specifies whether Ingress is enabled. false
ledger.ingress.className Ingress class name. ""
ledger.ingress.annotations Additional ingress annotations. {}
ledger.ingress.hosts Configured hosts for Ingress and associated paths. []
ledger.ingress.tls TLS configurations for Ingress. []
ledger.resources.* CPU/Memory resource requests/limits. See values.yaml
ledger.autoscaling.enabled Specifies whether autoscaling is enabled. true
ledger.autoscaling.minReplicas Minimum number of replicas for autoscaling. 2
ledger.autoscaling.maxReplicas Maximum number of replicas for autoscaling. 9
ledger.autoscaling.targetCPUUtilizationPercentage Target CPU utilization percentage for autoscaling. 80
ledger.autoscaling.targetMemoryUtilizationPercentage Target memory utilization percentage for autoscaling. 80
ledger.spread Per-component override of global.scheduling.spread (fields: enabled, hostname, zone, maxSkew). {}
ledger.topologySpreadConstraints Raw topologySpreadConstraints; non-empty replaces the spread preset. []
ledger.nodeSelector Node selectors for pod scheduling. {}
ledger.tolerations Tolerations for pod scheduling. []
ledger.affinity Affinity rules for pod scheduling. {}
ledger.configmap.* Environment variables for the service. See values.yaml
ledger.secrets.* Secrets for the service. See values.yaml
ledger.useExistingSecret Use an existing secret instead of creating a new one. false
ledger.existingSecretName The name of the existing secret to use. ""
ledger.extraEnvVars Extra environment variables, as a map of NAME: value. {}
ledger.serviceAccount.create Specifies whether the service account should be created. true
ledger.serviceAccount.annotations Annotations for the service account. {}
ledger.serviceAccount.name Service account name. If not defined, it will be generated automatically. ""
ledger.aws.rolesAnywhere.enabled Enable the AWS IAM Roles Anywhere sidecar on the ledger, for clusters without IRSA. The multi-tenant ledger reads its per-tenant Tracer M2M credential from Secrets Manager. On EKS keep it false and set ledger.serviceAccount.annotations["eks.amazonaws.com/role-arn"]; never enable both. When enabled, trustAnchorArn, profileArn and roleArn are required, the client certificate Secret (certificateSecretName, default <midaz-ledger.fullname>-iam-tls) must be provisioned outside the chart, and ledger.podSecurityContext is replaced with fsGroup: 65532. Set AWS_REGION in ledger.extraEnvVars. false
ledger.partition.enabled Run the partition runner (CronJob and reconcile hook Job). Unset means auto: on for ledger tags >= 4.5.0-beta.1 (every ledger image from that tag on ships the runner), off below that and for non-SemVer tags; true/false pins it. unset
ledger.partition.schedule Cron schedule of the partition ensure --reconcile-indexes CronJob. Keep it outside the database’s backup and maintenance windows. "0 6 * * *"
ledger.partition.timeZone IANA time zone for schedule; empty uses the kube-controller-manager’s zone, UTC on most managed clusters. ""
ledger.partition.activeDeadlineSeconds Hard timeout for one ensure run, in seconds. 1800
ledger.partition.reconcile.enabled Run partition reconcile-indexes --tolerate-unavailable as a hook Job after the migration Job, alongside the app rollout. true
ledger.partition.reconcile.syncWave Argo CD sync wave of the reconcile Job (plain Helm orders it with hook weight 10). "1"
ledger.partition.reconcile.activeDeadlineSeconds Hard timeout for the reconcile Job, in seconds. 1800
ledger.partition.reconcile.ttlSecondsAfterFinished How long a failed reconcile Job is kept for inspection; a successful hook Job is deleted at once. 259200
ledger.partition.resources.* CPU/Memory requests/limits of the partition runner pods. See values.yaml

Ledger Partition Runner

Ledger images from 4.5.0-beta.1 on ship a /partition binary next to /app, and the chart runs it in two workloads that reuse the ledger image, ConfigMap, Secret and scheduling settings: the midaz-ledger-partition CronJob runs /partition ensure --reconcile-indexes daily (creates future partitions on a partitioned database, reports their health and retries pending registered indexes), and the midaz-ledger-partition-reconcile-<tag> hook Job runs /partition reconcile-indexes --tolerate-unavailable on every install, upgrade and Argo CD sync, after the ledger migration Job and alongside the app rollout (Helm hook weight 10, Argo CD wave ledger.partition.reconcile.syncWave, the Deployment’s wave). Both set DB_TRANSACTION_* and MULTI_TENANT_* inline from the release values, so the pre-upgrade hook never reads the previous ConfigMap. On a database that keeps the unpartitioned layout both exit 0 without changes (ensure logs skipped_reason=unpartitioned per table). The hook never fails a deploy because of an unreachable tenant or a pending index; those still fail the daily CronJob (kube_job_status_failed). A non-zero exit of the CronJob is the alert signal: 1 a database or table needs attention, 2 a usage or startup error. The hook still fails on an invalid registry entry, a failed index build, a name conflict or a startup error. Set ledger.partition.enabled=false to turn both off, or ledger.partition.reconcile.enabled=false to keep only the CronJob; on a partitioned database ensure is what keeps future partitions ahead of the clock, and without it new rows eventually land in the DEFAULT partition.

Signals to watch: the exit code of the CronJob (kube_job_status_failed{job_name=~".*-partition-.*"} > 0 with kube-state-metrics); on a partitioned single-tenant database the ledger gauges ledger_partition_future_buffer_depth (warn when below the table’s horizon for more than a day), ledger_partition_default_rows and ledger_partition_default_inserts_total (any value above zero is act-now); in multi-tenant mode tenant_dependency_up_ratio{dependency="partition"} == 0 for a tenant whose partitions are unhealthy. To check a database without waiting for the schedule, run kubectl -n <namespace> create job partition-manual --from=cronjob/midaz-ledger-partition.

Without this chart, run the same two steps from the ledger image with the ledger’s own DB_TRANSACTION_* variables (or MULTI_TENANT_* and APPLICATION_NAME in multi-tenant mode): /partition reconcile-indexes --tolerate-unavailable after every migration run, alongside the rollout, and /partition ensure --reconcile-indexes once a day, off-peak.

Creating Ledger Secret Manually

If you want to use an existing Kubernetes Secret for the ledger service, you can create it manually with the following command:

kubectl create secret generic midaz-ledger \
  --from-literal=DB_ONBOARDING_PASSWORD='<your-db-onboarding-password>' \
  --from-literal=DB_ONBOARDING_REPLICA_PASSWORD='<your-db-onboarding-replica-password>' \
  --from-literal=MONGO_ONBOARDING_PASSWORD='<your-mongo-onboarding-password>' \
  --from-literal=DB_TRANSACTION_PASSWORD='<your-db-transaction-password>' \
  --from-literal=DB_TRANSACTION_REPLICA_PASSWORD='<your-db-transaction-replica-password>' \
  --from-literal=MONGO_TRANSACTION_PASSWORD='<your-mongo-transaction-password>' \
  --from-literal=REDIS_PASSWORD='<your-redis-password>' \
  --from-literal=RABBITMQ_DEFAULT_PASS='<your-rabbitmq-password>' \
  --from-literal=RABBITMQ_CONSUMER_PASS='<your-rabbitmq-consumer-password>' \
  --from-literal=LICENSE_KEY='<your-license-key>' \
  --from-literal=LCRYPTO_HASH_SECRET_KEY='<your-hash-secret-key>' \
  --from-literal=LCRYPTO_ENCRYPT_SECRET_KEY='<your-encrypt-secret-key>' \
  --from-literal=MONGO_CRM_PASSWORD='<your-mongo-crm-password>' \
  --from-literal=MONGO_FEES_PASSWORD='<your-mongo-fees-password>' \
  -n midaz

Note: The ledger service uses module-specific database credentials (onboarding and transaction) since it combines both modules. The DB_*, MONGO_*, and REDIS_PASSWORD keys above are only read when the matching backend is external; for the bundled Bitnami subcharts those passwords are single-sourced from the subchart Secret via secretKeyRef, so the keys in this secret are ignored. Only RABBITMQ_DEFAULT_PASS, RABBITMQ_CONSUMER_PASS, LICENSE_KEY, the two LCRYPTO_* keys (4.x ledger with KMS_VENDOR=none) and (for external backends) the infra passwords are required.

Then configure the ledger service to use this existing secret:

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

Enabling Ledger Service

To enable the ledger service:

ledger:
  enabled: true

CRM (Customer Relationship Management)

The crm service provides APIs for managing holder data and their relationships with ledger accounts. Previously available as a separate chart (plugin-crm) deployed in the midaz-plugins namespace, the CRM is now served in-process by the 4.x ledger (the chart default); this crm workload runs the standalone 3.x image (lerianstudio/midaz-crm:3.8.4).

For more details, refer to the official documentation: CRM Documentation

Parameter Description Default Value
crm.enabled Enable or disable the CRM service. false
crm.name Service name. "crm"
crm.replicaCount Number of replicas for the CRM service. 1
crm.image.repository Repository for the CRM service container image. "lerianstudio/midaz-crm"
crm.image.pullPolicy Image pull policy. "Always"
crm.image.tag Image tag used for deployment. See values.yaml
crm.imagePullSecrets Secrets for pulling images from a private registry. []
crm.nameOverride Overrides the default generated name by Helm. ""
crm.fullnameOverride Overrides the full name generated by Helm. ""
crm.podAnnotations Pod annotations for additional metadata. {}
crm.podSecurityContext Security context applied at the pod level. {}
crm.securityContext.* Defines security context settings for the container. See values.yaml
crm.pdb.enabled Specifies whether PodDisruptionBudget is enabled. true
crm.pdb.maxUnavailable Maximum number of unavailable pods; ignored when minAvailable is set. 1
crm.pdb.annotations Annotations for the PodDisruptionBudget. {}
crm.deploymentUpdate.type Type of deployment strategy. "RollingUpdate"
crm.deploymentUpdate.maxSurge Maximum number of pods that can be created over the desired number of pods. 1
crm.deploymentUpdate.maxUnavailable Maximum number of pods that can be unavailable during the update. 0
crm.service.type Kubernetes service type. "ClusterIP"
crm.service.port Service port. 4003
crm.ingress.enabled Specifies whether Ingress is enabled. false
crm.ingress.className Ingress class name. ""
crm.ingress.annotations Additional ingress annotations. {}
crm.ingress.hosts Configured hosts for Ingress and associated paths. []
crm.ingress.tls TLS configurations for Ingress. []
crm.resources.* CPU/Memory resource requests/limits. See values.yaml
crm.autoscaling.enabled Specifies whether autoscaling is enabled. true
crm.autoscaling.minReplicas Minimum number of replicas for autoscaling. 1
crm.autoscaling.maxReplicas Maximum number of replicas for autoscaling. 3
crm.autoscaling.targetCPUUtilizationPercentage Target CPU utilization percentage for autoscaling. 80
crm.autoscaling.targetMemoryUtilizationPercentage Target memory utilization percentage for autoscaling. 80
crm.spread Per-component override of global.scheduling.spread (fields: enabled, hostname, zone, maxSkew). {}
crm.topologySpreadConstraints Raw topologySpreadConstraints; non-empty replaces the spread preset. []
crm.nodeSelector Node selectors for pod scheduling. {}
crm.tolerations Tolerations for pod scheduling. []
crm.affinity Affinity rules for pod scheduling. {}
crm.configmap.* Environment variables for the service. See values.yaml
crm.secrets.* Secrets for the service. See values.yaml
crm.useExistingSecret Use an existing secret instead of creating a new one. false
crm.existingSecretName The name of the existing secret to use. ""
crm.extraEnvVars Extra environment variables, as a map of NAME: value. {}

Creating CRM Secret Manually

If you want to use an existing Kubernetes Secret for the CRM service, you can create it manually with the following command:

kubectl create secret generic midaz-crm \
  --from-literal=LCRYPTO_HASH_SECRET_KEY='<your-hash-secret-key>' \
  --from-literal=LCRYPTO_ENCRYPT_SECRET_KEY='<your-encrypt-secret-key>' \
  --from-literal=MONGO_PASSWORD='<your-mongo-password>' \
  -n midaz

Note: MONGO_PASSWORD is only read when MongoDB is external; for the bundled MongoDB it is single-sourced from the chart’s <release>-mongodb Secret via secretKeyRef, so the key in this secret is ignored.

Then configure the CRM service to use this existing secret:

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

Enabling CRM Service

To enable the CRM service:

crm:
  enabled: true
  configmap:
    MONGO_NAME: "crm"
    MONGO_USER: "midaz"
  # MONGO_PASSWORD is single-sourced from the chart's bundled-MongoDB Secret
  # (Secret `midaz-mongodb`, key `mongodb-root-password`) — only set it here when
  # using an EXTERNAL MongoDB (mongodb.enabled=false / mongodb.external=true).
  # secrets:
  #   MONGO_PASSWORD: "<your-mongo-password>"

Tracer

The tracer service provides real-time transaction validation and fraud prevention. From midaz v4 it ships from the monorepo (components/tracer) and is published as lerianstudio/midaz-tracer; the standalone lerianstudio/tracer 1.x image predates this configuration contract. It is disabled by default (tracer.enabled=false) and existing releases render unchanged.

tracer:
  enabled: true
  configmap:
    API_KEY_ENABLED: "true"
    CORS_ALLOWED_ORIGINS: "https://app.example.com"
  secrets:
    API_KEY: "<your-api-key>"
  # DB_PASSWORD is single-sourced from the chart's bundled-PostgreSQL Secret
  # (Secret `midaz-postgresql`, key `password`) — only set it here when using an
  # EXTERNAL PostgreSQL (postgresql.enabled=false / postgresql.external=true).

Images. Every image this chart references is expected to be pullable anonymously, so no imagePullSecrets are needed for a default install; anonymous manifest requests for the ledger, ledger-migrations, tracer, tracer-migrations and CRM tags in values.yaml returned HTTP 200 on Docker Hub when this was last checked. If you mirror the images to a private registry, set imagePullSecrets and image.repository on each component.

Observability

This chart deploys no observability stack. It creates no Grafana Deployment, Service or Ingress, and it bundles no collector.

The application workloads export OpenTelemetry traces and metrics to a collector you run yourself. That export is configured with otel-collector-lerian.enabled — see OpenTelemetry Collector wiring for the supported settings and for how to point the workloads at a collector that is not node-local.

Dependencies

This chart includes the following dependencies for the default installation. All dependencies are enabled by default.

Valkey

PostgreSQL

External PostgreSQL Bootstrap Job

When using an external PostgreSQL (i.e., postgresql.enabled: false), this chart provides a one-shot bootstrap Job that:

Configure in values.yaml:

postgresql:
  enabled: false  # disable bundled PostgreSQL to use an external one

global:
  externalPostgresDefinitions:
    enabled: true
    connection:
      host: "your-postgres-host"
      port: "5432"
    postgresAdminLogin:
      # Option A: Use an existing Secret (recommended)
      # Required keys: DB_USER_ADMIN, DB_ADMIN_PASSWORD
      useExistingSecret:
        name: "my-postgres-admin-secret"
      # Option B: Inline credentials (not recommended in production)
      # username: "postgres"
      # password: "s3cret"
    midazCredentials:
      # Option A: Use an existing Secret (recommended)
      # Required key: DB_PASSWORD_MIDAZ
      useExistingSecret:
        name: "my-midaz-credentials-secret"
      # Option B: Inline password (not recommended in production)
      # password: "midaz-password"

Notes:

MongoDB

MongoDB replica set (chart 11.0.0)

The bundled MongoDB is now a one-member replica set (mongodb.architecture: replicaset, replicaCount: 1, no arbiter). The ledger records fee quota usage in a Mongo transaction, and a single-tenant ledger refuses to boot on a standalone MongoDB. The ledger and CRM hosts now default to midaz-mongodb-headless.

Who is affected: every release with mongodb.enabled: true (the default). An external MongoDB is untouched, but it must be a replica set or DocumentDB 4.0+ instance-based.

Upgrading without acting: the replica set starts on a new empty volume (datadir-midaz-mongodb-0), because a StatefulSet cannot mount the old claim midaz-mongodb, so holders, fee packages and every other Mongo document appear to be gone. With the Helm CLI the old volume is kept, unmounted. With Argo CD and prune on, the old claim is deleted and, with reclaimPolicy Delete, so is the data. With Argo CD and prune off (the default), the old Deployment midaz-mongodb keeps running and its pod is selected by the new midaz-mongodb-headless Service, so the ledger splits its connections between the old and the new MongoDB; delete deploy/midaz-mongodb and svc/midaz-mongodb before the ledger runs again.

Option A, stay standalone for now. Valid only while the ledger runs a release that does not record quota usage in a transaction; a newer single-tenant ledger refuses to boot on standalone.

mongodb:
  architecture: standalone
  updateStrategy:
    type: Recreate

Option B, migrate the data. Commands assume release midaz in namespace midaz; turn Argo CD auto-sync off first. Under Argo CD the sync would undo the scale to 0 below on an install with autoscaling off (the Deployments then render spec.replicas from replicaCount), so before the sync that takes 11.0.0 set ledger.autoscaling.enabled: false and ledger.replicaCount: 0 in the application values (and crm.autoscaling.enabled: false and crm.replicaCount: 0 when crm.enabled): the Deployments then carry replicas: 0 through the sync, which runs with prune (safe once the volume is patched to Retain). Run the wait before the dump. There is no Helm release to helm upgrade: after the restore, put the original values back and sync, then check that the ledger has ready pods (kubectl -n midaz get deploy -l 'app.kubernetes.io/instance=midaz,app.kubernetes.io/name=midaz-ledger'). With autoscaling on (the default) the Deployments omit spec.replicas and the HPA does not scale a Deployment sitting at 0, so scale both explicitly: kubectl -n midaz scale deploy -l 'app.kubernetes.io/instance=midaz,app.kubernetes.io/name in (midaz-ledger,midaz-crm)' --replicas=<n>, <n> being the autoscaling.minReplicas you use.

$ kubectl -n midaz scale deploy -l 'app.kubernetes.io/instance=midaz,app.kubernetes.io/name in (midaz-ledger,midaz-crm)' --replicas=0
$ kubectl -n midaz wait --for=delete pod -l 'app.kubernetes.io/instance=midaz,app.kubernetes.io/name in (midaz-ledger,midaz-crm)' --timeout=120s
$ kubectl -n midaz exec deploy/midaz-mongodb -- sh -c 'mongodump --username "$MONGODB_ROOT_USER" --password "$MONGODB_ROOT_PASSWORD" --authenticationDatabase admin --archive' > midaz-mongo.archive
$ PV=$(kubectl -n midaz get pvc midaz-mongodb -o jsonpath='{.spec.volumeName}')
$ kubectl patch pv "$PV" -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}'
$ helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm --version 11.0.0 -n midaz -f values.yaml --set ledger.autoscaling.enabled=false,ledger.replicaCount=0,crm.autoscaling.enabled=false,crm.replicaCount=0
$ kubectl -n midaz rollout status sts/midaz-mongodb
$ kubectl -n midaz exec -i midaz-mongodb-0 -- sh -c 'mongorestore --username "$MONGODB_ROOT_USER" --password "$MONGODB_ROOT_PASSWORD" --authenticationDatabase admin --archive --drop --nsExclude "admin.*" --nsExclude "config.*"' < midaz-mongo.archive
$ helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm --version 11.0.0 -n midaz -f values.yaml

The password comes from the container’s own MONGODB_ROOT_USER and MONGODB_ROOT_PASSWORD variables, so it never travels in the pods/exec request (kubectl sends exec arguments as query parameters, which an audit log records) and a custom mongodb.auth.rootUser needs no change. Inside the container --password is still visible in the mongod-side process list for the duration of the command: the MongoDB tools read no password from the environment, and a --config file would put it on disk. Then check holders and fee packages through the API, and once satisfied delete the old claim and its disk: kubectl patch pv "$PV" -p '{"spec":{"persistentVolumeReclaimPolicy":"Delete"}}', then kubectl -n midaz delete pvc midaz-mongodb.

Also check:

RabbitMQ

  1. Automatically: Enable the bootstrap job in your values.yaml to automatically apply the RabbitMQ definitions to your external instance:

       global:
         externalRabbitmqDefinitions:
           enabled: true
    
  2. Manually: You can also apply them with RabbitMQ’s HTTP API. First create the two users with your own passwords, the ones you give the ledger as RABBITMQ_DEFAULT_PASS and RABBITMQ_CONSUMER_PASS (JSON-escape a " or \ in them), then load the definitions, whose permissions need those users:

     curl -u {admin-user}:{admin-pass} -X PUT -H "Content-Type: application/json" \
       -d '{"password":"{transaction-pass}","tags":"management"}' http://{host}:{port}/api/users/transaction
     curl -u {admin-user}:{admin-pass} -X PUT -H "Content-Type: application/json" \
       -d '{"password":"{consumer-pass}","tags":"management"}' http://{host}:{port}/api/users/consumer
     curl -u {admin-user}:{admin-pass} -X POST -H "Content-Type: application/json" \
       -d @load_definitions.json http://{host}:{port}/api/definitions
    

    The load_definitions.json file is located at:

     charts/midaz/files/rabbitmq/load_definitions.json
    

External RabbitMQ Bootstrap Job

To streamline external RabbitMQ setup, this chart provides a one-shot Job that:

Configure in values.yaml:

rabbitmq:
  enabled: false  # disable bundled RabbitMQ to use an external one

global:
  externalRabbitmqDefinitions:
    enabled: true
    connection:
      protocol: "http"          # http or https
      host: "your-rabbitmq-host"
      port: "15672"             # HTTP management port
      portAmqp: "5672"          # AMQP port (for connectivity check)
    rabbitmqAdminLogin:
      # Option A: Use an existing Secret (recommended)
      # Required keys: RABBITMQ_ADMIN_USER, RABBITMQ_ADMIN_PASS
      useExistingSecret:
        name: "my-rabbitmq-admin-secret"
      # Option B: Inline credentials (not recommended in production)
      # username: "admin"
      # password: "s3cret"
    appCredentials:
      # Option A: Use an existing Secret (recommended)
      # Required keys: RABBITMQ_DEFAULT_PASS, RABBITMQ_CONSUMER_PASS
      useExistingSecret:
        name: "my-rabbitmq-app-credentials"
      # Option B: Inline passwords (not recommended in production)
      # transactionPassword: "transaction-pass"
      # consumerPassword: "consumer-pass"

Notes:

RabbitMQ over TLS/SSL

If your RabbitMQ server requires TLS/SSL, update the client environment variables to use secure protocols:

ledger:
  configmap:
    RABBITMQ_URI: "amqps"      # was "amqp"

OpenTelemetry Collector wiring

Since 8.4.0 the otel-collector-lerian subchart is no longer installed as a dependency of this chart (the dependency was removed; see UPGRADE-8.4.md for the migration story). The otel-collector-lerian.enabled flag now only controls whether HOST_IP, POD_IP, OTEL_EXPORTER_OTLP_ENDPOINT=$(HOST_IP):4317 and OTEL_RESOURCE_ATTRIBUTES=k8s.pod.ip=$(POD_IP) are injected into the ledger, crm and tracer deployments.

By default enabled: true — Midaz expects a node-local OTel collector listening on 4317 (hostPort or hostNetwork). Install the otel-collector-lerian chart separately or point your own collector at the same port.

otel-collector-lerian:
  enabled: true    # injects OTEL env vars (default)

If you don’t want telemetry exported, or you want to send telemetry to an endpoint that isn’t a node-local collector on :4317, leave enabled: false and configure OTEL_EXPORTER_OTLP_ENDPOINT directly in the application configmap:

otel-collector-lerian:
  enabled: false

ledger:
  configmap:
    OTEL_EXPORTER_OTLP_ENDPOINT: "https://your-collector.example.com:4317"
crm:
  configmap:
    OTEL_EXPORTER_OTLP_ENDPOINT: "https://your-collector.example.com:4317"

The schema declares only enabled under otel-collector-lerian: and does not reject other keys (additionalProperties is true), but the templates read only enabled: legacy keys such as external, extraEnvs, exporters or opentelemetry-collector render without error and have no effect.