You’ll find a quick start for experienced operators, followed by a detailed breakdown of breaking changes, new features, and post-upgrade checks.
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

Componentv2.xv3.0.0
Kubernetes1.19+1.20+
Helm3.5+3.8+
Redis6.x6.x/7.x*
PostgreSQL13+13+
MongoDB4.4+4.4+
*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>.
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.
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=
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=
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
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
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
  ...
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: ""
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"
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>
Check the console secrets template to get the secrets keys.

​
For onboarding

Set: 
onboarding:
    useExistingSecrets: true
    existingSecretName: <existing-secret-name>
Check the onboarding secrets template to get the secrets keys.

​
For transaction

Set: 
transaction:
    useExistingSecrets: true
    existingSecretName: <existing-secret-name>
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

Figure 1. V2 architecture data flow.

  • Console: The main user interface and API gateway.
  • Onboarding Service: Handles account creation and management.
  • Transaction Service: Processes financial transactions.
  • Redis: Used for caching and temporary data storage.
  • PostgreSQL: Primary database for persistent storage

​
V3 architecture

Figure 2. V3 architecture data flow

  1. NGINX Gateway
  • New component for managing plugin UIs.
  • Enables dynamic plugin loading and routing.
  • Provides better security isolation for plugins.
  1. Plugin Architecture
  • Support for modular plugin UIs.
  • Each plugin can be enabled/disabled independently.
  • Plugins can be developed and deployed separately.
  1. Observability
  • New OTEL Collector for centralized metrics.
  • Improved monitoring capabilities.
  • Better integration with external monitoring tools.
  1. Enhanced Security
  • External secrets support.
  • Improved TLS configuration.
  • Better isolation between components.

​
Command to Upgrade

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