Skip to main content

​
Pre-upgrade checklist

1
Backup existing Helm releases:
helm get values -n midaz midaz > midaz-v3-backup.yaml
2
Critical: Backup RabbitMQ data and definitions before upgrading.
3
Schedule a maintenance window.

​
Breaking changes in v4.x

​
RabbitMQ dependency change to Groundhog2k

The RabbitMQ chart dependency has been replaced from Bitnami to Groundhog2k.
This change may lead to PersistentVolumeClaim (PVC) data loss when upgrading existing installations because the underlying StatefulSet, volume mounts, and configuration differ from the previous dependency.
Important notes:
  • The Groundhog2k chart requires a valid Erlang cookie. Set rabbitmq.authentication.erlangCookie.value to a 32+ character printable string with no spaces. If missing or empty, RabbitMQ will fail to start.
  • If you need to preserve existing data, back up and plan a controlled migration of PVCs and definitions before upgrading.
Required configuration: 
rabbitmq:
  authentication:
    erlangCookie:
      value: "<32+ printable characters without spaces>"
This breaking change only impacts deployments that use the chart’s default RabbitMQ (rabbitmq.enabled: true). If you run an external or managed RabbitMQ, you are not affected.

​
App version bump

Midaz has been bumped to v3.3.1.
Check the app changelog for the complete list of changes.

​
New features in v4.x

​
BitnamiSecure images for core data services

The default images for core data services now use the BitnamiSecure repositories with the latest tag:
ServiceImage SourceTag
PostgreSQLBitnamiSecurelatest
MongoDBBitnamiSecurelatest
ValkeyBitnamiSecurelatest
If you require pinning to a specific version, override the tag in values.yaml: 
postgresql:
  image:
    tag: "16.2.0"

mongodb:
  image:
    tag: "7.0.5"

valkey:
  image:
    tag: "7.2.4"

​
Official NGINX image for microfrontends

The previous Bitnami NGINX dependency was replaced with an internal template based on the official nginx image.
If you previously customized the Bitnami-based NGINX configuration, review the new templates under templates/console/ and adjust your values accordingly.

​
Why we changed Bitnami dependencies

We moved away from Bitnami dependencies due to policy changes impacting stability and operations. For more context, see:

​
Upgrade command

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

​
Rollback procedure

# List release history
helm history midaz -n midaz

# Rollback to previous version
helm rollback midaz <REVISION> -n midaz
Due to the RabbitMQ dependency change, rolling back may require manual intervention to restore PVCs and data. Ensure you have backups before upgrading.

​
Common issues

RabbitMQ fails to start
  • Ensure the Erlang cookie is set correctly (32+ printable characters, no spaces).
RabbitMQ PVC data loss
  • This is expected due to the dependency change. Export RabbitMQ definitions before upgrading and restore after.
NGINX configuration issues
  • Review the new NGINX templates under templates/console/ and update your overrides.