helm

Plugin BR Bank Transfer Helm Chart

Chart Contract

This Helm chart installs Plugin BR Bank Transfer for Midaz, a high-performance and open-source ledger.

Install Plugin BR Bank Transfer Helm Chart

To install Plugin BR Bank Transfer using Helm, run the following command:

$ helm install plugin-br-bank-transfer oci://registry-1.docker.io/lerianstudio/plugin-br-bank-transfer-helm --version <version> -n midaz-plugins --create-namespace

This will create a new namespace called midaz-plugins if it doesn’t already exist and deploy the Plugin BR Bank Transfer Helm chart.

After installation, you can verify that the release was successful by listing the Helm releases in the midaz-plugins namespace:

$ helm list -n midaz-plugins

Upgrading

To upgrade the chart to a new version:

$ helm upgrade plugin-br-bank-transfer oci://ghcr.io/lerianstudio/plugin-br-bank-transfer-helm --version <new-version> -n midaz-plugins

Uninstalling

To uninstall the chart:

$ helm uninstall plugin-br-bank-transfer -n midaz-plugins

Managed Cloud (global.cloud)

Point this chart at a managed-cloud environment (AWS/GCP/Azure) instead of the bundled in-cluster Postgres/Redis/MongoDB/RabbitMQ with one knob:

global:
  cloud: "aws"   # aws | gcp | azure — leave unset for the bundled dev topology
  datastores:
    postgres: { host: "my-rds.example.com", user: "bank_transfer" }
    redis: { host: "my-elasticache.example.com:6379", user: "default" }
  env:
    name: "production"
  auth:
    host: "http://plugin-access-manager-auth:4000"

# Disable the bundled subcharts — the masks above point at your managed
# infra instead, so the in-cluster Postgres/Redis/MongoDB would otherwise
# still deploy unused alongside it.
postgresql:
  enabled: false
  external: true
valkey:
  enabled: false
  external: true
mongodb:
  enabled: false
  external: true

global.cloud sets the connection TOPOLOGY (TLS, SSL mode) for the masks above; only the ENDPOINTS (host/port/user) still come from global.datastores — a cloud preset can’t know your RDS host. A native bankTransfer.configmap.<KEY> always overrides any mask. redis.host is host:port (no separate redis.port field); set redis.user only for ACL-authenticated Redis/Valkey deployments.

Copy values-template.yaml as your starting point — it documents every global.* mask with a working example, including the required enabled: false / external: true pair for each bundled subchart on a managed-cloud install. values.yaml is the full power-user reference; values.schema.json validates it.

Pod Spreading (global.scheduling.spread)

The bank-transfer Deployment renders topologySpreadConstraints from the lerian-common spread preset. The default is soft (ScheduleAnyway) across nodes, so replicas are spread across nodes (e.g. spot nodes) whenever possible, but a pod is never left Pending because of it.

Zone spreading is off by default (zone: ""). When scoring a soft spread, the scheduler skips every node that lacks the topology.kubernetes.io/zone label, so on clusters without zone labels (bare-metal, k3s) a zone constraint silently cancels the node spread. Turn it on (zone: ScheduleAnyway) where every node carries zone labels (EKS, GKE, AKS).

global:
  scheduling:
    spread:
      enabled: true            # master switch
      hostname: ScheduleAnyway # kubernetes.io/hostname: ScheduleAnyway | DoNotSchedule | "" (off)
      zone: ""                 # topology.kubernetes.io/zone: same values (off by default)
      maxSkew: 1               # integer >= 1
      minDomains: 0            # DoNotSchedule constraints only; 0 = off
      nodeTaintsPolicy: ""     # Honor | Ignore | "" (Kubernetes default Ignore)
bankTransfer:
  spread: { hostname: DoNotSchedule }  # field-level override
  topologySpreadConstraints: []        # raw list; non-empty replaces the preset

On EKS + Karpenter use a hard node spread:

global:
  scheduling:
    spread:
      hostname: DoNotSchedule
      zone: ScheduleAnyway
      maxSkew: 1
      minDomains: 2
      nodeTaintsPolicy: Honor

minDomains: 2 is required with DoNotSchedule. Skew is measured only against nodes that already exist, so on a single eligible node all replicas would otherwise share it. With fewer than 2 nodes the extra replica stays Pending until Karpenter launches another node. nodeTaintsPolicy: Honor stops tainted nodes (for example a node being drained) from counting as domains.

Precedence: bankTransfer.topologySpreadConstraints (non-empty, wins entirely) > bankTransfer.spread.<field> > global.scheduling.spread.<field> > off. Each preset constraint selects only this Deployment’s own pods (labelSelector = its spec.selector.matchLabels) of the same ReplicaSet (matchLabelKeys: [pod-template-hash]), so a rolling update is never blocked by the old ReplicaSet’s pods, even with DoNotSchedule. Requires Kubernetes >= 1.27 with the MatchLabelKeysInPodTopologySpread feature gate enabled (beta, on by default). Use DoNotSchedule only when the cluster can always provide enough distinct nodes/zones for the replica count. Jobs are not spread.

Upgrade note: the preset is on by default, so upgrading to the chart version that introduces it adds topologySpreadConstraints to the pod template and triggers one rolling restart of the Deployment. No values change is required. To keep the previous pod template exactly, set global.scheduling.spread.enabled: false.

Configuring Ingress for Different Controllers

The Plugin Bank Transfer Helm Chart optionally supports different Ingress Controllers for exposing services when necessary.

NGINX Ingress Controller

To use the NGINX Ingress Controller, configure the values.yaml as follows:

bankTransfer:
  ingress:
    enabled: true
    className: "nginx"
    annotations: {}
    hosts:
      - host: bank-transfer.example.com
        paths:
          - path: /
            pathType: Prefix
    tls:
      - secretName: bank-transfer-tls
        hosts:
          - bank-transfer.example.com

Parameters

Bank Transfer Service

Parameter Description Default
bankTransfer.enabled Enable or disable the bank-transfer service true
bankTransfer.replicaCount Number of replicas for the deployment 2
bankTransfer.image.repository Repository for the container image ghcr.io/lerianstudio/plugin-br-bank-transfer
bankTransfer.image.pullPolicy Image pull policy IfNotPresent
bankTransfer.image.tag Image tag used for deployment 2.0.0
bankTransfer.imagePullSecrets Secrets for pulling images from a private registry []
bankTransfer.revisionHistoryLimit Old ReplicaSets to retain 10
bankTransfer.nameOverride Overrides the default generated name by Helm ""
bankTransfer.fullnameOverride Overrides the full name generated by Helm ""
bankTransfer.ingress.enabled Enable or disable ingress false
bankTransfer.ingress.className Ingress class name ""
bankTransfer.ingress.annotations Additional ingress annotations {}
bankTransfer.ingress.hosts Ingress host configuration See values.yaml
bankTransfer.ingress.tls TLS configuration for ingress []
bankTransfer.service.type Kubernetes service type ClusterIP
bankTransfer.service.port Service port 4027
bankTransfer.deploymentUpdate.type Deployment strategy type RollingUpdate
bankTransfer.podSecurityContext Pod security context {}
bankTransfer.securityContext Security context for the container See values.yaml
bankTransfer.pdb.enabled Enable or disable PodDisruptionBudget true
bankTransfer.pdb.minAvailable Minimum number of available pods 1
bankTransfer.pdb.maxUnavailable Maximum number of unavailable pods 1
bankTransfer.resources CPU and memory limits for pods See values.yaml
bankTransfer.autoscaling.enabled Enable or disable horizontal pod autoscaling true
bankTransfer.autoscaling.minReplicas Minimum number of replicas 2
bankTransfer.autoscaling.maxReplicas Maximum number of replicas 5
global.scheduling.spread Pod spreading preset (enabled / hostname / zone / maxSkew / minDomains / nodeTaintsPolicy), see Pod Spreading {enabled: true, hostname: ScheduleAnyway, zone: "", maxSkew: 1, minDomains: 0, nodeTaintsPolicy: ""}
bankTransfer.spread Field-level override of global.scheduling.spread {}
bankTransfer.topologySpreadConstraints Raw topologySpreadConstraints; non-empty replaces the preset (an entry without labelSelector gets the selector labels) []
bankTransfer.nodeSelector Node selector for scheduling pods {}
bankTransfer.tolerations Tolerations for scheduling on tainted nodes []
bankTransfer.affinity Affinity rules for pod scheduling {}
bankTransfer.useExistingSecret Use an existing secret instead of creating a new one false
bankTransfer.existingSecretName The name of the existing secret to use ""

PostgreSQL Dependency

Parameter Description Default
postgresql.enabled Enable the PostgreSQL dependency true
postgresql.external Use an external PostgreSQL instance false
postgresql.auth.postgresPassword PostgreSQL admin password. Leave empty to let the subchart auto-generate it into the <release>-postgresql Secret (read via secretKeyRef). ""
postgresql.auth.username Application DB user bank_transfer
postgresql.auth.password Application DB password. Leave empty to let the subchart auto-generate it. ""
postgresql.auth.database Application DB name bank_transfer

Valkey (Redis-compatible) Dependency

Parameter Description Default
valkey.enabled Enable the Valkey dependency true
valkey.architecture Valkey architecture standalone
valkey.auth.enabled Enable authentication true
valkey.auth.password Valkey password. Leave empty to let the subchart auto-generate it into the <release>-valkey Secret (read via secretKeyRef). ""
valkey.auth.username Valkey username bank_transfer

MongoDB Dependency

Parameter Description Default
mongodb.enabled Enable the MongoDB dependency true
mongodb.auth.rootPassword MongoDB admin password. Leave empty to let the subchart auto-generate it into the <release>-mongodb Secret. ""
mongodb.auth.usernames Application DB users ["bank_transfer"]
mongodb.auth.passwords Application DB passwords. Leave empty to let the subchart auto-generate them (read via secretKeyRef, key mongodb-passwords). [""]
mongodb.auth.databases Application databases ["plugin_br_bank_transfer_jd"]

RabbitMQ Dependency (Optional)

Parameter Description Default
rabbitmq.enabled Enable the RabbitMQ dependency false
rabbitmq.authentication.user.value RabbitMQ username bank_transfer
rabbitmq.authentication.password.value RabbitMQ password (operator-provided). ""
rabbitmq.authentication.erlangCookie.value RabbitMQ Erlang cookie (operator-provided; e.g. openssl rand -base64 32). Must be set when rabbitmq.enabled=true. ""

IMPORTANT - Security Warning:

ConfigMap Environment Variables

Key environment variables configured via bankTransfer.configmap:

Variable Description Default
ENV_NAME Environment name production
LOG_LEVEL Log level info
SERVER_ADDRESS Server listen address :4027
POSTGRES_HOST PostgreSQL host Dynamic based on release
REDIS_HOST Redis/Valkey host Dynamic based on release
PLUGIN_AUTH_ENABLED Enable authentication true
JD_SANDBOX_MODE Enable JD sandbox mode (fake adapter) false
MIDAZ_BASE_URL Midaz API base URL Required
MIDAZ_FEE_MODE Fee engine: auto (native on Midaz >= 4.1, legacy below), legacy (plugin-fees on /v1) or native (Midaz embedded fees on /v2) auto
MIDAZ_FEE_MODE_REFRESH How often auto re-reads the ledger version (positive Go duration) 5m
CRM_BASE_URL CRM adapter base URL Required
FEES_BASE_URL Fees adapter base URL Required
JD_BASE_URL JD SPB SOAP API URL Required (unless JD_SANDBOX_MODE=true)
JD_ORIGIN_ISPB Bank ISPB code for JD Required (unless JD_SANDBOX_MODE=true)
LICENSE_SERVICE_ADDRESS License validation service URL Optional
TENANT_IDS Tenant IDs for license validation Optional

For a complete list, see values.yaml.

Secrets

Key secrets configured via bankTransfer.secrets:

Secret Description
POSTGRES_PASSWORD PostgreSQL password. With the bundled subchart it is auto-generated and read via secretKeyRef; set only for an external PostgreSQL without postgresql.auth.existingSecret.
REDIS_PASSWORD Redis/Valkey password. With the bundled subchart it is auto-generated and read via secretKeyRef; set only for an external Valkey without valkey.auth.existingSecret.
MONGO_PASSWORD MongoDB password. With the bundled subchart it is read from the subchart Secret (key mongodb-passwords); set only for an external MongoDB without mongodb.auth.existingSecret.
MONGO_URI MongoDB connection URI. Auto-assembled on the deployment from MONGO_PASSWORD; set explicitly only to override (e.g. external MongoDB).
JD_INCOMING_RAW_XML_ENCRYPTION_KEY Encryption key (hex-encoded 32-byte AES-256, 64 hex chars). Required.
RECIPIENT_DETAILS_ENCRYPTION_KEY Encryption key (hex-encoded 32-byte AES-256, 64 hex chars). Required.

Development Mode

For local development/testing, you can disable authentication and use sandbox mode:

bankTransfer:
  configmap:
    ENV_NAME: "development"
    PLUGIN_AUTH_ENABLED: "false"
    POSTGRES_SSLMODE: "disable"
    JD_SANDBOX_MODE: "true"  # Uses fake JD adapter (no real bank calls)

Note: License validation is controlled via LICENSE_SERVICE_ADDRESS and TENANT_IDS. When these are not set, license validation is skipped.

Support

For more information, see the Lerian Studio Documentation or contact the maintainers.

This site is open source. Improve this page.