This guide walks you through upgrading your Midaz deployment from Midaz Helm v2.x to v3.x.

You’ll find a quick start for experienced operators, followed by a detailed breakdown of breaking changes, new features, and post-upgrade checks.

👍

Tip

Need a refresher on installing Midaz with Helm? Check the Using Helm guide in Deployment strategies before starting your upgrade.

Quick Start

1. Check the prerequisites

• Helm v3.8+ installed and available (helm version).
• Kubernetes v1.20+ cluster running.
• Backup your existing installation.

2. Run the upgrade command

helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm --version 3.0.0 -n midaz

3. Verify the upgrade

helm list -n midaz
kubectl get pods -n midaz

Version Compatibility

^*New Redis config supported

Pre-upgrade checklist

1. Backup existing Helm releases:

helm get values -n midaz midaz > midaz-v2-backup.yaml

2. Review the Breaking Changes section below.
3. Check resource requirements for v3.0.0.
4. Schedule a maintenance window.
5. Inform your team about the upgrade plan.

Breaking changes

Consolidation of REDIS_PORT into REDIS_HOST

The REDIS_PORT environment variable has been removed. Its value must now be included directly in the REDIS_HOST variable as <host>:<port>.

❗️

Important

Remove REDIS_PORT from your environment and update REDIS_HOST to avoid connection errors. Check the onboarding configmap and transaction configmap templates for more details.

This change affects the following components:

• onboarding
• transaction

Old configuration

REDIS_HOST=redis_host
REDIS_PORT=redis_port

New configuration

REDIS_HOST=redis_host:redis_port

App version bump

Midaz has been bumped to v3.0.0.

📘

Note

Check the app changelog for the complete list of changes.

Additions

New onboarding environment variable

A new environment variable (ACCOUNT_TYPE_VALIDATION) has been added to the onboarding service. You can use it to specify which ledgers are valid for account creation per organization:

# ACCOUNTING CONFIG
# List of <organization-id>:<ledger-id> separated by comma
ACCOUNT_TYPE_VALIDATION=

👍

Tip

Check the onboarding configmap template for more details.

New transaction environment variable

A new environment variable (TRANSACTION_ROUTE_VALIDATION) has been added to the transaction service. You can use it to define which ledgers are allowed per organization for transaction routing validation:

# ACCOUNTING CONFIG
# List of <organization-id>:<ledger-id> separated by comma
TRANSACTION_ROUTE_VALIDATION=

👍

Tip

Check the transaction configmap template for more details.

New Redis variables

The following environment variables have been introduced to the onboarding and transaction services:

# USE ONLY ON SENTINEL
REDIS_MASTER_NAME=

# TLS CONFIGURATION
REDIS_TLS=false
REDIS_CA_CERT=

# GCP IAM AUTHENTICATION
REDIS_USE_GCP_IAM=false
REDIS_SERVICE_ACCOUNT=
GOOGLE_APPLICATION_CREDENTIALS=
# <= 60 minutes
REDIS_TOKEN_LIFETIME=60
# minutes
REDIS_TOKEN_REFRESH_DURATION=45

# AUTH & DB SELECTION
REDIS_PASSWORD=lerian
REDIS_DB=0
REDIS_PROTOCOL=3

# POOL & RETRY CONFIGURATION
REDIS_POOL_SIZE=10
REDIS_MIN_IDLE_CONNS=0
# Seconds
REDIS_READ_TIMEOUT=3
REDIS_WRITE_TIMEOUT=3
REDIS_DIAL_TIMEOUT=5
REDIS_POOL_TIMEOUT=2

REDIS_MAX_RETRIES=3
# Milliseconds
REDIS_MIN_RETRY_BACKOFF=8
# Seconds
REDIS_MAX_RETRY_BACKOFF=1

👍

Tip

Check the onboarding configmap and transaction configmap templates for more details.

Enterprise: NGINX gateway for plugin UIs

A new optional NGINX component has been introduced to serve as a gateway/proxy for the plugins UIs of activated plugins in enterprise deployments.

• By default, this dependency is disabled.
• It can be enabled per customer based on the plugins they have access to.
• This gateway simplifies the routing and mounting of plugin frontends under the midaz-console domain.

Midaz Console environment variables

New environment variables have been added to midaz-console to support this feature:

console:
  configmap:
    NEXT_PUBLIC_MIDAZ_CONSOLE_BASE_URL: https://midaz-console.yourdomain.io
    NGINX_PORT: 8080
    NGINX_HOST: midaz-nginx.midaz.svc.cluster.local
    NGINX_BASE_PATH: http://midaz-nginx.midaz.svc.cluster.local:8080

👍

Tip

Check the console configmap template for more details.

Helm parameters

New Helm parameters were also introduced:

# Plugins UIs
  pluginsUi:
    enabled: false
    plugins:
      plugin-smart-templates-ui:
        enabled: false
        port: 8083
      plugin-crm-ui:
        enabled: false
        port: 8084
      plugin-fees-ui:
        enabled: false
        port: 8082
  ...

👍

Tip

Check the Plugin UIs section in values.yaml for more details.

NGINX variables

nginx:
  enabled: false

  service:
    type: ClusterIP
    ports:
      http: 8080

  existingServerBlockConfigmap: "midaz-console-nginx-config"

  # Mount the plugins configmap as a volume
  extraVolumes:
    - name: nginx-plugins-config
      configMap:
        name: midaz-console-nginx-config-plugins

  # Mount the volume into the nginx container
  extraVolumeMounts:
    - name: nginx-plugins-config
      mountPath: /opt/bitnami/nginx/conf/plugins_blocks

  ingress:
    enabled: false
    pathType: Prefix
    hostname: ""
    path: /
    annotations: {}
    ingressClassName: ""

👍

Tip

Check the nginx section in values.yaml for more details.

Enterprise: OTEL Collector

A new optional OTEL Collector component has been introduced for enterprise clients who want to send metrics to Lerian's telemetry stack. This collector is disabled by default and can be enabled in values:

otel-collector-lerian:
  enabled: true

To redirect metrics to a custom Prometheus adapter on the customer's side, modify:

otel-collector-lerian:
  exporters:
    prometheus/local:
      endpoint: "http://<customer-prometheus-endpoint>:9090"

👍

Tip

Check the otel-collector-lerian section in values.yaml for more details.

External secrets support

You can now use external secrets for sensitive data in console, onboarding, and transaction.

For console

Set:

console:
    useExistingSecrets: true
    existingSecretName: <existing-secret-name>

👍

Tip

Check the console secrets template to get the secrets keys.

For onboarding

Set:

onboarding:
    useExistingSecrets: true
    existingSecretName: <existing-secret-name>

👍

Tip

Check the onboarding secrets template to get the secrets keys.

For transaction

Set:

transaction:
    useExistingSecrets: true
    existingSecretName: <existing-secret-name>

👍

Tip

Check the transaction secrets template to get the secrets keys.

Post-upgrade verification

1. Check pod status

kubectl get pods -n midaz

All pods should be Running and READY.

2. Verify services

kubectl get svc -n midaz

3. Check the logs

# Check console logs
kubectl logs -n midaz deployment/midaz-console
   
# Check onboarding service logs
kubectl logs -n midaz deployment/midaz-onboarding
   
# Check transaction service logs
kubectl logs -n midaz deployment/midaz-transaction

Rollback procedure

If you encounter issues after the upgrade, you can roll back to the previous version:

# List release history
helm history midaz -n midaz

# Rollback to previous version
helm rollback midaz <REVISION> -n midaz

# Verify rollback
helm list -n midaz
kubectl get pods -n midaz

Common issues and fixes

Redis Connection Issues

• Symptom: Services fail to start with Redis connection errors.
• Solution: Verify your Redis configuration in values.yaml:

redis:
  host: your-redis-host:6379  # Include port in host
  # Remove redis.port if present

Missing Secrets

• Symptom: Pods crash with missing secret errors.
• Solution: Ensure all required secrets are correctly configured:
  • Check secret names in your values.yaml.
  • Verify external secrets exist if using useExistingSecrets: true.

NGINX Gateway Issues

• Symptom: Plugin UIs are not accessible.
• Solution:
  • Verify NGINX is enabled in values.yaml.
  • Check NGINX logs:

kubectl logs -n midaz deployment/midaz-nginx

Architecture changes

V2 architecture

V3 architecture

Command to Upgrade

helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm --version 3.0.0 -n midaz