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.
Install Midaz via Helm Chart
To install Midaz using Helm, run the following command:- Replace
<version>
with the desired Helm chart version. You can check available versions by running:
midaz
(if it doesn’t already exist) and deploys the chart. To confirm the deployment went through run:
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. In this chart, you can enable ingress individually for the Transaction, Onboarding, and Console services. 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.
NGINX ingress controller
To use the NGINX Ingress Controller, configure thevalues.yaml
as follows:
Check the ingress-nginx official documentation for a full reference on Nginx annotations.
AWS ALB (Application Load Balancer)
For AWS ALB Ingress Controller, configure thevalues.yaml
as follows:
Traefik Ingress Controller
For Traefik, configure thevalues.yaml
as follows:
Configuring observability
Midaz uses Grafana Docker OpenTelemetry LGTM to collect and visualize telemetry data such as traces and metrics.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:Option 2: Ingress access
To expose Grafana within your cluster or private network via DNS, enable and configure Ingress like this:Disabling observability
You can disable the observability stack entirely by setting:Configuring dependencies
The Midaz Helm Chart has the following dependencies for the project’s default installation. All dependencies are enabled by default.Valkey
- Version: 2.4.7
- Repository: Bitnami
- Disable:
valkey.enabled = false
PostgreSQL
- Version: 16.3.0
- Repository: Bitnami
- Disable:
postgresql.enabled = false
MongoDB
- Version: 15.4.5
- Repository: Bitnami
- Disable:
mongodb.enabled = false
RabbitMQ
- Version: 16.0.0
- Repository: Bitnami
- Disable:
rabbitmq.enabled = false
externalRabbitmqDefinitions
flag in your values.yaml
file to apply the default definitions automatically:
This Job only runs during the first install of the chart. It’s triggered by a Helm post-install hook and won’t run again during upgrades or re-installs.If you need to re-run it, delete the release and install it again.
load_definitions.json
file at: charts/midaz/files/rabbitmq/load_definitions.json
.
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:Nginx Proxy Manager (Plugins UIs)
The NGINX Proxy Manager in this chart routes traffic to plugin UIs. By default, it’s disabled, and all plugin UIs are only accessible through this proxy when enabled. To activate it, setnginx.enabled: true
in your values.yaml
.
- You can also configure ingress for it by setting
nginx.ingress.enabled: true
.
pluginsUi.enabled: true
in the Console service configuration and define the plugin settings, for example:
To allow NGINX to serve the plugin UIs, the corresponding Helm charts must be installed with UI enabled in the
midaz-plugins
namespace.Otell Collector
The Otell Collector gathers metrics from Midaz components. It’s disabled by default. To enable it, set:Midaz components
The Midaz system runs on four distinct layers that work together, distributed in segregated workloads:Onboarding
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. | "2.2.2" |
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. | "" |
Transaction
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. | "2.2.2" |
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. | "" |
Console
Parameter | Description | Default Value |
---|---|---|
console.name | Service name. | "console" |
console.enabled | Enable or disable the console service. | true |
console.replicaCount | Number of replicas for the deployment. | 1 |
console.image.repository | Docker image repository for Console. | "lerianstudio/midaz-console" |
console.image.pullPolicy | Docker image pull policy. | "IfNotPresent" |
console.image.tag | Docker image tag used for deployment. | "2.2.1" |
console.imagePullSecrets | Secrets for pulling Docker images from a private registry. | [] |
console.nameOverride | Overrides the resource name. | "" |
console.fullnameOverride | Overrides the full resource name. | "" |
console.podAnnotations | Annotations for the pods. | {} |
console.podSecurityContext | Security context applied at the pod level. | {} |
console.securityContext.* | Defines security context settings for the container. | See values.yaml |
console.pdb.enabled | Specifies whether PodDisruptionBudget is enabled. | false |
console.pdb.minAvailable | Minimum number of available pods for PodDisruptionBudget. | 1 |
console.pdb.maxUnavailable | Maximum number of unavailable pods for PodDisruptionBudget. | 1 |
console.pdb.annotations | Annotations for the PodDisruptionBudget. | {} |
console.deploymentUpdate.* | Deployment update strategy. | See values.yaml |
console.service.type | Kubernetes service type. | "ClusterIP" |
console.service.port | Service port. | 8081 |
console.service.annotations | Annotations for the service. | {} |
console.ingress.enabled | Specifies whether Ingress is enabled. | false |
console.ingress.className | Ingress class name. | "" |
console.ingress.annotations | Additional annotations for Ingress. | {} |
console.ingress.hosts | Configured hosts for Ingress and associated paths. | [] |
console.ingress.tls | TLS configurations for Ingress. | [] |
console.resources.* | CPU/Memory resource requests/limits. | See values.yaml |
console.autoscaling.enabled | Specifies whether horizontal pod autoscaling is enabled. | true |
console.autoscaling.minReplicas | Minimum number of replicas for autoscaling. | 1 |
console.autoscaling.maxReplicas | Maximum number of replicas for autoscaling. | 3 |
console.autoscaling.targetCPUUtilizationPercentage | Target CPU utilization percentage for autoscaling. | 80 |
console.autoscaling.targetMemoryUtilizationPercentage | Target memory utilization percentage for autoscaling. | 80 |
console.nodeSelector | Node selectors for pod scheduling. | {} |
console.tolerations | Tolerations for pod scheduling. | {} |
console.affinity | Affinity rules for pod scheduling. | {} |
console.configmap.* | Environment variables for the service. | See values.yaml |
console.secrets.* | Secrets for the service. | See values.yaml |
console.useExistingSecret | Use an existing secret instead of creating a new one. | false |
console.existingSecretName | The name of the existing secret to use. | "" |
console.extraEnvVars | A list of extra environment variables. | [] |
console.pluginsUi.enabled | Enable or disable the plugins UI proxy. | false |
console.pluginsUi.plugins.* | Configuration for each plugin UI. | See values.yaml |
console.serviceAccount.create | Specifies whether the service account should be created. | true |
console.serviceAccount.annotations | Annotations for the service account. | {} |
console.serviceAccount.name | Service account name. If not defined, it will be generated automatically. | "" |