Installing and deploying

Midaz plugins are distributed as independent Helm charts and follow the same deployment model as Midaz Core. Each plugin runs as a separate service alongside the platform, with its own configuration, dependencies, and lifecycle. This guide walks you through installing, configuring, and verifying plugin deployments on Kubernetes.

Before deploying any plugin, make sure you have a running Midaz Core instance. Plugins depend on Midaz Core APIs and cannot operate independently. See the Midaz Helm deployment guide if you haven’t set up Midaz yet.

Prerequisites

Before deploying plugins, ensure you have:

Kubernetes (v1.30+) – A running cluster with Midaz Core already deployed.
Helm 3+ – Installed and available.
kubectl configured with access to your cluster.
Cluster admin permissions or appropriate RBAC roles.
A valid Enterprise license key (required for all plugins except CRM).

Verify your tools are ready:

helm version

kubectl cluster-info

The CRM plugin is open source and does not require a license key. All other plugins require a valid Enterprise license. Contact a Lerian representative if you need one.

Available plugin charts

Each plugin is published as an OCI-compatible Helm chart. The table below lists all available plugins and their chart references.

Plugin	Chart name	OCI registry	Default namespace
CRM	`plugin-crm`	`oci://registry-1.docker.io/lerianstudio/plugin-crm`	`midaz-plugins`
Fees Engine	`plugin-fees`	`oci://registry-1.docker.io/lerianstudio/plugin-fees-helm`	`midaz-plugins`
Pix Direct (JD)	`plugin-br-pix-direct-jd`	`oci://registry-1.docker.io/lerianstudio/plugin-br-pix-direct-jd`	`midaz-plugins`
Pix Indirect (BTG)	`plugin-br-pix-indirect-btg`	`oci://registry-1.docker.io/lerianstudio/plugin-br-pix-indirect-btg`	`midaz-plugins`

Starting from Midaz v5.x, the CRM plugin is also available as an integrated component within the main Midaz Helm chart. If you are running v5.x, you can enable CRM directly in your Midaz values instead of deploying it separately. See the Midaz Helm guide for details. Also note that the Pix plugins are still under active development.

Installing a plugin

The installation process is the same for all plugins. Replace the chart name, registry, and version for the plugin you want to deploy.

1. Check available versions

You can find available chart versions by checking the Helm repository tags on GitHub. Filter by the plugin prefix (e.g., plugin-crm-v, plugin-fees-v). You can also check the version compatibility table to find the right chart version for your Midaz Core version.

2. Install the chart

CRM
Fees Engine
Pix Direct (JD)
Pix Indirect (BTG)

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

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

helm install plugin-br-pix-direct-jd oci://registry-1.docker.io/lerianstudio/plugin-br-pix-direct-jd \
  --version <version> \
  -n midaz-plugins \
  --create-namespace

helm install plugin-br-pix-indirect-btg oci://registry-1.docker.io/lerianstudio/plugin-br-pix-indirect-btg \
  --version <version> \
  -n midaz-plugins \
  --create-namespace

Replace <version> with the desired chart version. The --create-namespace flag creates the midaz-plugins namespace if it doesn’t already exist.

3. Verify the installation

After installing, confirm the release is deployed:

helm list -n midaz-plugins

Check that all pods are running:

kubectl get pods -n midaz-plugins

All pods should show Running status and READY state.

To install a plugin with custom configuration, create a values.yaml file and pass it with the -f flag:

helm install plugin-crm oci://registry-1.docker.io/lerianstudio/plugin-crm \
  --version <version> \
  -n midaz-plugins \
  --create-namespace \
  -f my-plugin-crm-values.yaml

Configuring license keys

All plugins except CRM require a valid Enterprise license key. You configure it through the Helm chart’s secrets section in your values.yaml:

<plugin>:
  secrets:
    LICENSE_KEY: "<your-license-key>"
    ORGANIZATION_IDS: "<your-organization-ids>"

Replace <plugin> with the plugin’s service key (e.g., crm, fees).

Deploying a licensed plugin without a valid key will result in the service starting but rejecting API requests. Make sure your license key and organization IDs are configured before going to production.

Configuring dependencies

Plugins bundle their own database dependencies by default. This means you can deploy a plugin and have a working setup without any extra database configuration. However, for production environments, you’ll likely want to use your own managed databases.

MongoDB

The CRM, Fees Engine, and Pix plugins use MongoDB for data storage. Each plugin chart includes a bundled Bitnami MongoDB dependency (v16.4.0) that is enabled by default. To use an external MongoDB instance, disable the bundled dependency and point the plugin to your instance:

mongodb:
  enabled: false

<plugin>:
  configmap:
    MONGO_HOST: <your-host>
    MONGO_NAME: <your-database-name>
    MONGO_USER: <your-user>
    MONGO_PORT: "<your-port>"
  secrets:
    MONGO_PASSWORD: <your-password>

Replace <plugin> with the plugin’s service key (e.g., crm, fees).

Using existing Kubernetes Secrets

For production environments, you can manage secrets outside of Helm by referencing an existing Kubernetes Secret. This avoids storing sensitive values directly in your values.yaml.

Create the secret

Create a Kubernetes Secret with the required keys for your plugin. For example, for CRM:

kubectl create secret generic plugin-crm-secrets \
  --from-literal=LCRYPTO_HASH_SECRET_KEY='<your-hash-key>' \
  --from-literal=LCRYPTO_ENCRYPT_SECRET_KEY='<your-encrypt-key>' \
  --from-literal=MONGO_PASSWORD='<your-mongo-password>' \
  --from-literal=LICENSE_KEY='<your-license-key>' \
  --from-literal=ORGANIZATION_IDS='<your-org-ids>' \
  -n midaz-plugins

Reference it in your values

Configure the plugin to use the existing secret:

crm:
  useExistingSecret: true
  existingSecretName: "plugin-crm-secrets"

This pattern works for all plugins. Each plugin accepts useExistingSecret and existingSecretName parameters.

Configuring ingress

Plugin services are deployed as ClusterIP by default, meaning they are only accessible within the cluster. To expose a plugin externally, enable ingress in your values.yaml. The ingress configuration follows the same pattern as Midaz Core. Here’s an example using NGINX:

<plugin>:
  ingress:
    enabled: true
    className: "nginx"
    annotations: {}
    hosts:
      - host: plugin.example.com
        paths:
          - path: /
            pathType: Prefix
    tls:
      - secretName: plugin-tls
        hosts:
          - plugin.example.com

Replace <plugin> with the plugin’s service key.

For detailed ingress configuration examples with AWS ALB and Traefik, refer to the Midaz Helm deployment guide. The same patterns apply to plugin charts.

Verifying your deployment

After installing a plugin, verify that everything is running correctly.

Check pod status

kubectl get pods -n midaz-plugins -o wide

All pods should be in Running state with all containers ready.

Check pod logs

kubectl logs -n midaz-plugins deployment/<plugin-deployment-name> --tail=50

Look for successful startup messages and verify there are no errors related to database connections, license validation, or missing configuration.

Test the health endpoint

All plugins expose a /health endpoint. You can verify it via port-forwarding:

kubectl port-forward -n midaz-plugins svc/<plugin-service-name> <local-port>:<service-port>

Then check the health endpoint:

curl http://localhost:<local-port>/health

Plugin	Service name	Default port
CRM	`plugin-crm`	4003
Fees Engine	`plugin-fees`	4002

Upgrading plugins

To upgrade a plugin to a new version, use helm upgrade with the target version:

helm upgrade <release-name> <oci-registry> \
  --version <new-version> \
  -n midaz-plugins \
  -f my-plugin-values.yaml

Always upgrade Midaz Core before upgrading plugins. Plugins depend on Midaz Core APIs, so upgrading in the wrong order may cause compatibility issues.

For detailed upgrade procedures, pre-upgrade checklists, and rollback instructions, see the Helm upgrade guide.

Uninstalling a plugin

To remove a plugin from your cluster:

helm uninstall <release-name> -n midaz-plugins

For example:

helm uninstall plugin-crm -n midaz-plugins

Uninstalling a plugin removes its Kubernetes resources (deployments, services, configmaps, secrets) but does not delete persistent data stored in databases. If you used the bundled MongoDB, the PersistentVolumeClaims may remain. Delete them manually if you want to fully clean up.

Deploy Midaz using Helm – Initial Midaz Core installation guide
Helm upgrade guide – Upgrade procedures and rollback instructions
Version compatibility – Helm chart and application version mapping
Plugin version compatibility – Plugin compatibility with Midaz Core versions
What are plugins? – Overview of the plugin architecture
Helm repository – Source code, charts, and release notes

Introduction

CRM

Fees Engine

Pix

Indirect Pix

Direct Pix

Bank Transfer (TED)

Installing and deploying

Prerequisites

Available plugin charts

Installing a plugin

1. Check available versions

2. Install the chart

3. Verify the installation

Configuring license keys

Configuring dependencies

MongoDB

Using existing Kubernetes Secrets

Configuring ingress

Verifying your deployment

Check pod status

Check pod logs

Test the health endpoint

Upgrading plugins

Uninstalling a plugin

Introduction

CRM

Fees Engine

Pix

Indirect Pix

Direct Pix

Bank Transfer (TED)

​Prerequisites

​Available plugin charts

​Installing a plugin

​1. Check available versions

​2. Install the chart

​3. Verify the installation

​Configuring license keys

​Configuring dependencies

​MongoDB

​Using existing Kubernetes Secrets

​Configuring ingress

​Verifying your deployment

​Check pod status

​Check pod logs

​Test the health endpoint

​Upgrading plugins

​Uninstalling a plugin

​Related resources

Prerequisites

Available plugin charts

Installing a plugin

1. Check available versions

2. Install the chart

3. Verify the installation

Configuring license keys

Configuring dependencies

MongoDB

Using existing Kubernetes Secrets

Configuring ingress

Verifying your deployment

Check pod status

Check pod logs

Test the health endpoint

Upgrading plugins

Uninstalling a plugin

Related resources