Using Helm

This guide walks you through installing and configuring a Midaz environment on Kubernetes using Helm. You’ll find instructions on setting up Ingress controllers, enabling observability, and managing dependencies.

This guide covers Midaz Helm chart v5.x. For upgrading from previous versions, see Upgrading Helm.

Deploying Midaz with Helm

Prerequisites

Before deploying Midaz with Helm, make sure you have:

Kubernetes (v1.30+) – Running cluster.
Helm 3+ – Installed and available (helm version).
Access to a container registry with Midaz images.
DNS and TLS certificates for ingress (or cert-manager installed).

The source code for this Helm chart is available at:

The default installation matches the one provided in the Midaz quick installation guide.

Want a deeper understanding of the architecture? Check the Midaz architecture overview.

Install Midaz via Helm Chart

To install Midaz using Helm, run the following command:

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

Replace <version> with the desired Helm chart version. You can check available versions by running:

helm search repo oci://registry-1.docker.io/lerianstudio/midaz-helm --versions

This creates a namespace called midaz (if it doesn’t already exist) and deploys the chart. To confirm the deployment went through run:

helm list -n midaz

The Helm chart is in our GitHub repository. You can fork it, customize values, or extend as needed.

Configuring ingress

Ingress allows you to expose Midaz services outside the Kubernetes cluster, binding them to specific domains and TLS certificates. You can enable ingress individually for each Midaz service. To use ingress, you’ll need an ingress controller running in your cluster (e.g., NGINX, AWS ALB, or Traefik) and DNS entries pointing to it.

You can enable ingress per service in your values.yaml file and configure hostnames, TLS secrets, and any controller-specific annotations.

The following sections provide configuration examples for the most common ingress controllers.

NGINX ingress controller

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

ingress:
  enabled: true
  className: "nginx"
  # The `annotations` field is used to add custom metadata to the Nginx resource.
  # Annotations are key-value pairs that can be used to attach arbitrary non-identifying metadata to objects.
  # These annotations can be used by various tools and libraries to augment the behavior of the Nginx resource.
  # See more 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

Check the ingress-nginx official documentation for a full reference on Nginx annotations.

AWS ALB (Application Load Balancer)

For AWS ALB Ingress Controller, configure the values.yaml as follows:

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: "/healthz"  # Health check path
    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:

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

Configuring observability

Midaz uses Grafana Docker OpenTelemetry LGTM to collect and visualize telemetry data such as traces and metrics. You can access the Grafana dashboard using one of two options:

Option 1: Local access

To access the dashboard locally run:

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

Then use http://localhost:3000 to open the dashboard.

Option 2: Ingress access

To expose Grafana within your cluster or private network via DNS, enable and configure Ingress like this:

grafana:
  enabled: true
  name: grafana
  ingress:
    enabled: true
    className: "nginx"
    annotations:
      nginx.ingress.kubernetes.io/rewrite-target: /
    hosts:
      - host: "midaz-otel.example.com"
        paths:
          - path: /
            pathType: Prefix
    tls: []

Disabling observability

You can disable the observability stack entirely by setting:

grafana:
  enabled: false

OpenTelemetry Collector (Lerian)

The OpenTelemetry Collector is used to collect and export telemetry data from Midaz components. By default, it is disabled. To enable it:

otel-collector-lerian:
  enabled: true

Configuring dependencies

The Midaz Helm Chart has the following dependencies for the project’s default installation. All dependencies are enabled by default.

The examples below show configurations for both Ledger (recommended) and Onboarding/Transaction (legacy) services. Choose the configuration that matches your deployment.

Valkey

Version: 2.4.7
Repository: Bitnami
Disable: valkey.enabled = false

If you have an existing Valkey or Redis instance, you can disable this dependency and configure Midaz components to use your external instance.

Ledger (recommended)
Onboarding/Transaction (legacy)

ledger:
  configmap:
    REDIS_HOST: {your-host}:{your-host-port}
  secrets:
    REDIS_PASSWORD: {your-host-pass}

onboarding:
  configmap:
    REDIS_HOST: {your-host}:{your-host-port}
  secrets:
    REDIS_PASSWORD: {your-host-pass}

transaction:
  configmap:
    REDIS_HOST: {your-host}:{your-host-port}
  secrets:
    REDIS_PASSWORD: {your-host-pass}

PostgreSQL

Version: 16.3.0
Repository: Bitnami
Disable: postgresql.enabled = false

If you have an existing PostgreSQL instance, you can disable this dependency and configure Midaz components to use your external PostgreSQL.

Ledger (recommended)
Onboarding/Transaction (legacy)

ledger:
  configmap:
    # Onboarding module database
    DB_ONBOARDING_HOST: {your-host}
    DB_ONBOARDING_USER: {your-host-user}
    DB_ONBOARDING_PORT: {your-host-port}
    DB_ONBOARDING_REPLICA_HOST: {your-replication-host}
    DB_ONBOARDING_REPLICA_USER: {your-replication-host-user}
    DB_ONBOARDING_REPLICA_PORT: {your-replication-host-port}
    # Transaction module database
    DB_TRANSACTION_HOST: {your-host}
    DB_TRANSACTION_USER: {your-host-user}
    DB_TRANSACTION_PORT: {your-host-port}
    DB_TRANSACTION_REPLICA_HOST: {your-replication-host}
    DB_TRANSACTION_REPLICA_USER: {your-replication-host-user}
    DB_TRANSACTION_REPLICA_PORT: {your-replication-host-port}
  secrets:
    DB_ONBOARDING_PASSWORD: {your-host-pass}
    DB_ONBOARDING_REPLICA_PASSWORD: {your-replication-host-pass}
    DB_TRANSACTION_PASSWORD: {your-host-pass}
    DB_TRANSACTION_REPLICA_PASSWORD: {your-replication-host-pass}

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

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

External PostgreSQL Bootstrap Job

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

Creates the onboarding and transaction databases if they do not exist.
Creates the midaz role/user if it does not exist and sets its password.
Grants database privileges and public schema permissions so midaz can create tables.
Waits for connectivity with a 300s timeout.
Is idempotent: if everything already exists, it prints and exits.

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"

All secrets must be in the same namespace as the release. The Job has a TTL of 300 seconds after completion.

MongoDB

Version: 15.4.5
Repository: Bitnami
Disable: mongodb.enabled = false

If you have an existing MongoDB instance, you can disable this dependency and configure Midaz components to use your external MongoDB.

Ledger (recommended)
Onboarding/Transaction (legacy)

ledger:
  configmap:
    # Onboarding module
    MONGO_ONBOARDING_HOST: {your-host}
    MONGO_ONBOARDING_NAME: {your-host-name}
    MONGO_ONBOARDING_USER: {your-host-user}
    MONGO_ONBOARDING_PORT: {your-host-port}
    # Transaction module
    MONGO_TRANSACTION_HOST: {your-host}
    MONGO_TRANSACTION_NAME: {your-host-name}
    MONGO_TRANSACTION_USER: {your-host-user}
    MONGO_TRANSACTION_PORT: {your-host-port}
  secrets:
    MONGO_ONBOARDING_PASSWORD: {your-host-pass}
    MONGO_TRANSACTION_PASSWORD: {your-host-pass}

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

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

RabbitMQ

Version: 16.0.0
Repository: Groundhog2k
Disable: rabbitmq.enabled = false

If you’re using an external RabbitMQ instance, you need to load the required load_definitions.json file. Without these queues, exchanges, and bindings in place, Midaz won’t work as expected. You can load the definitions in one of two ways: Automatically Enable the bootstrap job in your values.yaml to automatically apply the RabbitMQ definitions to your external instance:

global:
  externalRabbitmqDefinitions:
    enabled: true

Manually If you prefer to apply the definitions yourself, use RabbitMQ’s HTTP API:

curl -u {user}:{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:

Applies the standard definitions file via the HTTP API.
Creates/updates the transaction and consumer users with custom passwords.
Waits for AMQP connectivity with a 300s timeout.
Is idempotent: if users already exist, it skips and exits.

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"

All secrets must be in the same namespace as the release. The Job has a TTL of 300 seconds after completion. Users created: midaz (admin), transaction, consumer.

RabbitMQ over TLS/SSL

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

Ledger (recommended)
Onboarding/Transaction (legacy)

ledger:
  configmap:
    RABBITMQ_URI: "amqps"      # was "amqp"
    RABBITMQ_PROTOCOL: "https" # was "http"

onboarding:
  configmap:
    RABBITMQ_URI: "amqps"      # was "amqp"
    RABBITMQ_PROTOCOL: "https" # was "http"

transaction:
  configmap:
    RABBITMQ_URI: "amqps"      # was "amqp"
    RABBITMQ_PROTOCOL: "https" # was "http"

Use your own RabbitMQ

If you already have a RabbitMQ instance running, you can disable the built-in dependency and point Midaz components to your external setup.

Ledger (recommended)
Onboarding/Transaction (legacy)

ledger:
  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}
    RABBITMQ_CONSUMER_PASS: {your-rabbitmq-consumer-password}

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}

Midaz components

The Midaz Helm chart deploys core services that handle ledger operations, account management, and transaction processing.

Recommended for new installations: Use the unified Ledger service. The separate Onboarding and Transaction services are still supported but will become legacy in a future release.

Ledger (recommended)

The ledger service is a unified service that combines the functionality of both onboarding and transaction modules into a single deployment. This service is recommended for new installations and will become mandatory in future releases.

When ledger.enabled is set to true, the onboarding and transaction services are automatically disabled (unless migration.allowAllServices is set to true for testing purposes).

Enabling Ledger service:

ledger:
  enabled: true

onboarding:
  enabled: false

transaction:
  enabled: false

When ledger is enabled, the onboarding and transaction ingresses will automatically redirect traffic to the ledger service, maintaining backward compatibility with existing DNS configurations.

Parameter	Description	Default Value
`ledger.enabled`	Enable or disable the ledger service.	`false`
`ledger.name`	Service name.	`"ledger"`
`ledger.replicaCount`	Number of replicas for the ledger service.	`1`
`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.	`""` (defaults to Chart.AppVersion)
`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.*`	Defines security context settings for the container.	See `values.yaml`
`ledger.pdb.enabled`	Specifies whether PodDisruptionBudget is enabled.	`true`
`ledger.pdb.minAvailable`	Minimum number of available pods.	`1`
`ledger.pdb.maxUnavailable`	Maximum number of unavailable pods.	`1`
`ledger.pdb.annotations`	Annotations for the PodDisruptionBudget.	`{}`
`ledger.deploymentUpdate.*`	Deployment update strategy.	See `values.yaml`
`ledger.service.type`	Kubernetes service type.	`"ClusterIP"`
`ledger.service.port`	Port for the HTTP API.	`3000`
`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.	`5`
`ledger.autoscaling.targetCPUUtilizationPercentage`	Target CPU utilization percentage for autoscaling.	`80`
`ledger.autoscaling.targetMemoryUtilizationPercentage`	Target memory utilization percentage for autoscaling.	`80`
`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`	A list of extra environment variables.	`[]`
`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.	`""`

Creating Ledger secret manually

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

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>' \
  -n midaz

The ledger service uses module-specific database credentials (onboarding and transaction) since it combines both modules.

Then configure the ledger service to use this existing secret:

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

Onboarding (legacy)

The Onboarding service is still supported but will become legacy in a future release. We recommend using the unified Ledger service for new installations.

Parameter	Description	Default Value
`onboarding.name`	Service name.	`"onboarding"`
`onboarding.replicaCount`	Number of replicas for the onboarding service.	`2`
`onboarding.image.repository`	Repository for the onboarding service container image.	`"lerianstudio/midaz-onboarding"`
`onboarding.image.pullPolicy`	Image pull policy.	`"IfNotPresent"`
`onboarding.image.tag`	Image tag used for deployment.	`"3.3.4"`
`onboarding.imagePullSecrets`	Secrets for pulling images from a private registry.	`[]`
`onboarding.nameOverride`	Overrides the default generated name by Helm.	`""`
`onboarding.fullnameOverride`	Overrides the full name generated by Helm.	`""`
`onboarding.podAnnotations`	Pod annotations for additional metadata.	`{}`
`onboarding.podSecurityContext`	Security context applied at the pod level.	`{}`
`onboarding.securityContext.*`	Defines security context settings for the container.	See `values.yaml`
`onboarding.pdb.enabled`	Specifies whether PodDisruptionBudget is enabled.	`true`
`onboarding.pdb.minAvailable`	Minimum number of available pods.	`1`
`onboarding.pdb.maxUnavailable`	Maximum number of unavailable pods.	`1`
`onboarding.pdb.annotations`	Annotations for the PodDisruptionBudget.	`{}`
`onboarding.deploymentUpdate.*`	Deployment update strategy.	See `values.yaml`
`onboarding.service.type`	Kubernetes service type.	`"ClusterIP"`
`onboarding.service.port`	Port for the HTTP API.	`3000`
`onboarding.service.annotations`	Annotations for the service.	`{}`
`onboarding.ingress.enabled`	Specifies whether Ingress is enabled.	`false`
`onboarding.ingress.className`	Ingress class name.	`""`
`onboarding.ingress.annotations`	Additional ingress annotations.	`{}`
`onboarding.ingress.hosts`	Configured hosts for Ingress and associated paths.	`""`
`onboarding.ingress.tls`	TLS configurations for Ingress.	`[]`
`onboarding.resources.*`	CPU/Memory resource requests/limits.	See `values.yaml`
`onboarding.autoscaling.enabled`	Specifies whether autoscaling is enabled.	`true`
`onboarding.autoscaling.minReplicas`	Minimum number of replicas for autoscaling.	`2`
`onboarding.autoscaling.maxReplicas`	Maximum number of replicas for autoscaling.	`5`
`onboarding.autoscaling.targetCPUUtilizationPercentage`	Target CPU utilization percentage for autoscaling.	`80`
`onboarding.autoscaling.targetMemoryUtilizationPercentage`	Target memory utilization percentage for autoscaling.	`80`
`onboarding.nodeSelector`	Node selectors for pod scheduling.	`{}`
`onboarding.tolerations`	Tolerations for pod scheduling.	`{}`
`onboarding.affinity`	Affinity rules for pod scheduling.	`{}`
`onboarding.configmap.*`	Environment variables for the service.	See `values.yaml`
`onboarding.secrets.*`	Secrets for the service.	See `values.yaml`
`onboarding.useExistingSecret`	Use an existing secret instead of creating a new one.	`false`
`onboarding.existingSecretName`	The name of the existing secret to use.	`""`
`onboarding.extraEnvVars`	A list of extra environment variables.	`[]`
`onboarding.serviceAccount.create`	Specifies whether the service account should be created.	`true`
`onboarding.serviceAccount.annotations`	Annotations for the service account.	`{}`
`onboarding.serviceAccount.name`	Service account name. If not defined, it will be generated automatically.	`""`

Creating Onboarding secret manually

If you want to use an existing Kubernetes Secret for the onboarding service:

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

Then configure the onboarding service to use this existing secret:

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

Transaction (legacy)

The Transaction service is still supported but will become legacy in a future release. We recommend using the unified Ledger service for new installations.

Parameter	Description	Default Value
`transaction.name`	Service name.	`"transaction"`
`transaction.replicaCount`	Number of replicas for the transaction service.	`1`
`transaction.image.repository`	Repository for the transaction service container image.	`"lerianstudio/midaz-transaction"`
`transaction.image.pullPolicy`	Image pull policy.	`"IfNotPresent"`
`transaction.image.tag`	Image tag used for deployment.	`"3.3.4"`
`transaction.imagePullSecrets`	Secrets for pulling images from a private registry.	`[]`
`transaction.nameOverride`	Overrides the default generated name by Helm.	`""`
`transaction.fullnameOverride`	Overrides the full name generated by Helm.	`""`
`transaction.podAnnotations`	Pod annotations for additional metadata.	`{}`
`transaction.podSecurityContext`	Security context for the pod.	`{}`
`transaction.securityContext.*`	Defines security context settings for the container.	See `values.yaml`
`transaction.pdb.enabled`	Enable or disable PodDisruptionBudget.	`true`
`transaction.pdb.minAvailable`	Minimum number of available pods.	`2`
`transaction.pdb.maxUnavailable`	Maximum number of unavailable pods.	`1`
`transaction.pdb.annotations`	Annotations for the PodDisruptionBudget.	`{}`
`transaction.deploymentUpdate.*`	Deployment update strategy.	See `values.yaml`
`transaction.service.type`	Kubernetes service type.	`"ClusterIP"`
`transaction.service.port`	Port for the HTTP API.	`3001`
`transaction.service.annotations`	Annotations for the service.	`{}`
`transaction.ingress.enabled`	Enable or disable ingress.	`false`
`transaction.ingress.className`	Ingress class name.	`""`
`transaction.ingress.annotations`	Additional ingress annotations.	`{}`
`transaction.ingress.hosts`	Configured hosts for ingress and associated paths.	`[]`
`transaction.ingress.tls`	TLS configuration for ingress.	`[]`
`transaction.resources.*`	CPU/Memory resource requests/limits.	See `values.yaml`
`transaction.autoscaling.enabled`	Enable or disable horizontal pod autoscaling.	`true`
`transaction.autoscaling.minReplicas`	Minimum number of replicas for autoscaling.	`1`
`transaction.autoscaling.maxReplicas`	Maximum number of replicas for autoscaling.	`5`
`transaction.autoscaling.targetCPUUtilizationPercentage`	Target CPU utilization percentage for autoscaling.	`80`
`transaction.autoscaling.targetMemoryUtilizationPercentage`	Target memory utilization percentage for autoscaling.	`80`
`transaction.nodeSelector`	Node selector for scheduling pods on specific nodes.	`{}`
`transaction.tolerations`	Tolerations for scheduling on tainted nodes.	`{}`
`transaction.affinity`	Affinity rules for pod scheduling.	`{}`
`transaction.configmap.*`	Environment variables for the service.	See `values.yaml`
`transaction.secrets.*`	Secrets for the service.	See `values.yaml`
`transaction.useExistingSecret`	Use an existing secret instead of creating a new one.	`false`
`transaction.existingSecretName`	The name of the existing secret to use.	`""`
`transaction.extraEnvVars`	A list of extra environment variables.	`[]`
`transaction.serviceAccount.create`	Specifies whether a ServiceAccount should be created.	`true`
`transaction.serviceAccount.annotations`	Annotations for the ServiceAccount.	`{}`
`transaction.serviceAccount.name`	Name of the service account.	`""`

Creating Transaction secret manually

If you want to use an existing Kubernetes Secret for the transaction service:

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

The transaction service requires an additional secret key RABBITMQ_CONSUMER_PASS compared to onboarding.

Then configure the transaction service to use this existing secret:

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

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 integrated into the main Midaz Helm chart and deployed in the midaz namespace.

If you are currently using plugin-crm in the midaz-plugins namespace, we recommend migrating to this new integrated CRM workload. See the Upgrading Helm guide for migration steps.

For more details about CRM functionality, refer to the CRM Documentation.

Enabling CRM service:

crm:
  enabled: true
  configmap:
    MONGO_HOST: "midaz-mongodb"  # Use your MongoDB host
    MONGO_NAME: "crm"
    MONGO_USER: "midaz"
  secrets:
    MONGO_PASSWORD: "lerian"

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.	`"ghcr.io/lerianstudio/midaz-crm"`
`crm.image.pullPolicy`	Image pull policy.	`"Always"`
`crm.image.tag`	Image tag used for deployment.	`"3.5.0"`
`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.minAvailable`	Minimum number of available pods.	`1`
`crm.pdb.maxUnavailable`	Maximum number of unavailable pods.	`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.	`1`
`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.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`	A list of extra environment variables.	`{}`

Creating CRM secret manually

If you want to use an existing Kubernetes Secret for the CRM service:

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

Then configure the CRM service to use this existing secret:

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

Getting started

Understanding Midaz

Installing & deploying

Use cases

Core entities

Best practices

Midaz SDKs & libs

Deploying Midaz with Helm

Prerequisites

Install Midaz via Helm Chart

Configuring ingress

NGINX ingress controller

AWS ALB (Application Load Balancer)

Traefik Ingress Controller

Configuring observability

Option 1: Local access

Option 2: Ingress access

Disabling observability

OpenTelemetry Collector (Lerian)

Configuring dependencies

Valkey

PostgreSQL

External PostgreSQL Bootstrap Job

MongoDB

RabbitMQ

External RabbitMQ Bootstrap Job

RabbitMQ over TLS/SSL

Use your own RabbitMQ

Midaz components

Ledger (recommended)

Creating Ledger secret manually

Onboarding (legacy)

Creating Onboarding secret manually

Transaction (legacy)

Creating Transaction secret manually

CRM (Customer Relationship Management)

Creating CRM secret manually

Getting started

Understanding Midaz

Installing & deploying

Use cases

Core entities

Best practices

Midaz SDKs & libs

​Deploying Midaz with Helm

​Prerequisites

​Install Midaz via Helm Chart

​Configuring ingress

​NGINX ingress controller

​AWS ALB (Application Load Balancer)

​Traefik Ingress Controller

​Configuring observability

​Option 1: Local access

​Option 2: Ingress access

​Disabling observability

​OpenTelemetry Collector (Lerian)

​Configuring dependencies

​Valkey

​PostgreSQL

​External PostgreSQL Bootstrap Job

​MongoDB

​RabbitMQ

​External RabbitMQ Bootstrap Job

​RabbitMQ over TLS/SSL

​Use your own RabbitMQ

​Midaz components

​Ledger (recommended)

​Creating Ledger secret manually

​Onboarding (legacy)

​Creating Onboarding secret manually

​Transaction (legacy)

​Creating Transaction secret manually

​CRM (Customer Relationship Management)

​Creating CRM secret manually

Deploying Midaz with Helm

Prerequisites

Install Midaz via Helm Chart

Configuring ingress

NGINX ingress controller

AWS ALB (Application Load Balancer)

Traefik Ingress Controller

Configuring observability

Option 1: Local access

Option 2: Ingress access

Disabling observability

OpenTelemetry Collector (Lerian)

Configuring dependencies

Valkey

PostgreSQL

External PostgreSQL Bootstrap Job

MongoDB

RabbitMQ

External RabbitMQ Bootstrap Job

RabbitMQ over TLS/SSL

Use your own RabbitMQ

Midaz components

Ledger (recommended)

Creating Ledger secret manually

Onboarding (legacy)

Creating Onboarding secret manually

Transaction (legacy)

Creating Transaction secret manually

CRM (Customer Relationship Management)

Creating CRM secret manually