Este guia cobre o Helm chart do Midaz v5.x. Para atualizar a partir de versões anteriores, veja Atualizando o Helm.
Fazendo o deploy do Midaz com Helm
Pré-requisitos
Antes de fazer o deploy do Midaz com Helm, certifique-se de ter:- Kubernetes (v1.30+) – Cluster em execução.
- Helm 3+ – Instalado e disponível (
helm version). - Acesso a um registro de containers com as imagens do Midaz.
- Certificados DNS e TLS para ingress (ou cert-manager instalado).
O código-fonte deste Helm chart está disponível em:A instalação padrão corresponde à fornecida no Guia de instalação rápida do Midaz.
Instalar o Midaz via Helm Chart
Para instalar o Midaz usando Helm, execute o seguinte comando:<version> pela versão desejada do Helm chart. Você pode verificar as versões disponíveis executando:
midaz (se ainda não existir) e faz o deploy do chart. Para confirmar que o deploy foi realizado, execute:
Configurando o ingress
O Ingress permite expor os serviços do Midaz fora do cluster Kubernetes, vinculando-os a domínios específicos e certificados TLS. Você pode habilitar o ingress individualmente para cada serviço do Midaz. Para usar o ingress, você precisará de um ingress controller em execução no seu cluster (ex.: NGINX, AWS ALB ou Traefik) e entradas DNS apontando para ele. As seções a seguir fornecem exemplos de configuração para os ingress controllers mais comuns.
NGINX ingress controller
Para usar o NGINX Ingress Controller, configure ovalues.yaml da seguinte forma:
AWS ALB (Application Load Balancer)
Para o AWS ALB Ingress Controller, configure ovalues.yaml da seguinte forma:
Traefik Ingress Controller
Para o Traefik, configure ovalues.yaml da seguinte forma:
Configurando a observabilidade
O Midaz usa o Grafana Docker OpenTelemetry LGTM para coletar e visualizar dados de telemetria como traces e métricas. Você pode acessar o dashboard do Grafana usando uma de duas opções:
Opção 1: Acesso local
Para acessar o dashboard localmente, execute:Opção 2: Acesso via Ingress
Para expor o Grafana dentro do seu cluster ou rede privada via DNS, habilite e configure o Ingress assim:Desabilitando a observabilidade
Você pode desabilitar toda a stack de observabilidade configurando:OpenTelemetry Collector (Lerian)
O OpenTelemetry Collector é usado para coletar e exportar dados de telemetria dos componentes do Midaz. Por padrão, ele está desabilitado. Para habilitá-lo:Configurando dependências
O Helm Chart do Midaz possui as seguintes dependências para a instalação padrão do projeto. Todas as dependências são habilitadas por padrão.
Os exemplos abaixo mostram configurações tanto para o Ledger (recomendado) quanto para os serviços Onboarding/Transaction (legado). Escolha a configuração que corresponde ao seu deployment.
Valkey
- Versão: 2.4.7
- Repositório: Bitnami
- Desabilitar:
valkey.enabled = false
- Ledger (recomendado)
- Onboarding/Transaction (legado)
PostgreSQL
- Versão: 16.3.0
- Repositório: Bitnami
- Desabilitar:
postgresql.enabled = false
- Ledger (recomendado)
- Onboarding/Transaction (legado)
Job de Bootstrap para PostgreSQL Externo
Ao usar um PostgreSQL externo (postgresql.enabled: false), este chart fornece um Job de bootstrap único que:
- Cria os bancos de dados
onboardingetransactionse não existirem. - Cria o role/usuário
midazse não existir e define sua senha. - Concede privilégios de banco de dados e permissões no schema
publicpara que omidazpossa criar tabelas. - Aguarda conectividade com timeout de 300s.
- É idempotente: se tudo já existir, apenas imprime e encerra.
values.yaml:
Todos os secrets devem estar no mesmo namespace que o release. O Job tem um TTL de 300 segundos após a conclusão.
MongoDB
- Versão: 15.4.5
- Repositório: Bitnami
- Desabilitar:
mongodb.enabled = false
- Ledger (recomendado)
- Onboarding/Transaction (legado)
RabbitMQ
- Versão: 16.0.0
- Repositório: Groundhog2k
- Desabilitar:
rabbitmq.enabled = false
values.yaml para aplicar automaticamente as definições do RabbitMQ na sua instância externa:
load_definitions.json está localizado em: charts/midaz/files/rabbitmq/load_definitions.json.
Job de Bootstrap para RabbitMQ Externo
Para simplificar a configuração de um RabbitMQ externo, este chart fornece um Job único que:- Aplica o arquivo de definições padrão via API HTTP.
- Cria/atualiza os usuários
transactioneconsumercom senhas customizadas. - Aguarda conectividade AMQP com timeout de 300s.
- É idempotente: se os usuários já existirem, pula e encerra.
values.yaml:
Todos os secrets devem estar no mesmo namespace que o release. O Job tem um TTL de 300 segundos após a conclusão. Usuários criados:
midaz (admin), transaction, consumer.RabbitMQ com TLS/SSL
Se o seu servidor RabbitMQ requer TLS/SSL, atualize as variáveis de ambiente do cliente para usar protocolos seguros:- Ledger (recomendado)
- Onboarding/Transaction (legado)
Use seu próprio RabbitMQ
Se você já tem uma instância de RabbitMQ em execução, pode desabilitar a dependência integrada e apontar os componentes do Midaz para sua configuração externa.- Ledger (recomendado)
- Onboarding/Transaction (legado)
Componentes do Midaz
O Helm chart do Midaz faz o deploy dos servicos core que lidam com operacoes de ledger, gerenciamento de contas e processamento de transacoes.
| Parâmetro | Descrição | Valor Padrão |
|---|---|---|
ledger.enabled | Habilita ou desabilita the ledger service. | false |
ledger.name | Nome do serviço. | "ledger" |
ledger.replicaCount | Número de réplicas para o serviço ledger service. | 1 |
ledger.image.repository | Repositório da imagem de container do serviço ledger service . | "lerianstudio/midaz-ledger" |
ledger.image.pullPolicy | Política de pull da imagem. | "IfNotPresent" |
ledger.image.tag | Tag da imagem usada para o deployment. | "" (defaults to Chart.AppVersion) |
ledger.imagePullSecrets | Secrets para pull de imagens de um registro privado. | [] |
ledger.nameOverride | Sobrescreve o nome padrão gerado pelo Helm. | "" |
ledger.fullnameOverride | Sobrescreve o nome completo gerado pelo Helm. | "" |
ledger.podAnnotations | Annotations do pod para metadados adicionais. | {} |
ledger.podSecurityContext | Contexto de segurança aplicado no nível do pod. | {} |
ledger.securityContext.* | Define configurações de contexto de segurança para o container. | See values.yaml |
ledger.pdb.enabled | Especifica se o PodDisruptionBudget está habilitado. | true |
ledger.pdb.minAvailable | Número mínimo de pods disponíveis. | 1 |
ledger.pdb.maxUnavailable | Número máximo de pods indisponíveis. | 1 |
ledger.pdb.annotations | Annotations para o PodDisruptionBudget. | {} |
ledger.deploymentUpdate.* | Estratégia de atualização do deployment. | See values.yaml |
ledger.service.type | Tipo de serviço Kubernetes. | "ClusterIP" |
ledger.service.port | Porta para a API HTTP. | 3000 |
ledger.service.annotations | Annotations para o serviço. | {} |
ledger.ingress.enabled | Especifica se o Ingress está habilitado. | false |
ledger.ingress.className | Nome da classe do Ingress. | "" |
ledger.ingress.annotations | Annotations adicionais do ingress. | {} |
ledger.ingress.hosts | Hosts configurados para Ingress e paths associados. | [] |
ledger.ingress.tls | Configurações TLS para Ingress. | [] |
ledger.resources.* | Requests/limits de recursos CPU/Memória. | See values.yaml |
ledger.autoscaling.enabled | Especifica se o autoscaling está habilitado. | true |
ledger.autoscaling.minReplicas | Número mínimo de réplicas para autoscaling. | 2 |
ledger.autoscaling.maxReplicas | Número máximo de réplicas para autoscaling. | 5 |
ledger.autoscaling.targetCPUUtilizationPercentage | Percentual alvo de utilização de CPU para autoscaling. | 80 |
ledger.autoscaling.targetMemoryUtilizationPercentage | Percentual alvo de utilização de memória para autoscaling. | 80 |
ledger.nodeSelector | Seletores de node para agendamento de pods. | {} |
ledger.tolerations | Tolerations para agendamento de pods. | {} |
ledger.affinity | Regras de afinidade para agendamento de pods. | {} |
ledger.configmap.* | Variáveis de ambiente para o serviço. | See values.yaml |
ledger.secrets.* | Secrets para o serviço. | See values.yaml |
ledger.useExistingSecret | Usar um secret existente em vez de criar um novo. | false |
ledger.existingSecretName | Nome do secret existente a ser usado. | "" |
ledger.extraEnvVars | Lista de variáveis de ambiente extras. | [] |
ledger.serviceAccount.create | Especifica se a service account deve ser criada. | true |
ledger.serviceAccount.annotations | Annotations para a service account. | {} |
ledger.serviceAccount.name | Nome da service account. Se não definido, será gerado automaticamente. | "" |
Criando o secret do Ledger manualmente
Se você deseja usar um Kubernetes Secret existente para o serviço ledger, pode criá-lo manualmente:O serviço ledger usa credenciais de banco de dados específicas por módulo (onboarding e transaction), pois combina ambos os módulos.
Onboarding (legado)
| Parâmetro | Descrição | Valor Padrão |
|---|---|---|
onboarding.name | Nome do serviço. | "onboarding" |
onboarding.replicaCount | Número de réplicas para o serviço onboarding service. | 2 |
onboarding.image.repository | Repositório da imagem de container do serviço onboarding service . | "lerianstudio/midaz-onboarding" |
onboarding.image.pullPolicy | Política de pull da imagem. | "IfNotPresent" |
onboarding.image.tag | Tag da imagem usada para o deployment. | "3.3.4" |
onboarding.imagePullSecrets | Secrets para pull de imagens de um registro privado. | [] |
onboarding.nameOverride | Sobrescreve o nome padrão gerado pelo Helm. | "" |
onboarding.fullnameOverride | Sobrescreve o nome completo gerado pelo Helm. | "" |
onboarding.podAnnotations | Annotations do pod para metadados adicionais. | {} |
onboarding.podSecurityContext | Contexto de segurança aplicado no nível do pod. | {} |
onboarding.securityContext.* | Define configurações de contexto de segurança para o container. | See values.yaml |
onboarding.pdb.enabled | Especifica se o PodDisruptionBudget está habilitado. | true |
onboarding.pdb.minAvailable | Número mínimo de pods disponíveis. | 1 |
onboarding.pdb.maxUnavailable | Número máximo de pods indisponíveis. | 1 |
onboarding.pdb.annotations | Annotations para o PodDisruptionBudget. | {} |
onboarding.deploymentUpdate.* | Estratégia de atualização do deployment. | See values.yaml |
onboarding.service.type | Tipo de serviço Kubernetes. | "ClusterIP" |
onboarding.service.port | Porta para a API HTTP. | 3000 |
onboarding.service.annotations | Annotations para o serviço. | {} |
onboarding.ingress.enabled | Especifica se o Ingress está habilitado. | false |
onboarding.ingress.className | Nome da classe do Ingress. | "" |
onboarding.ingress.annotations | Annotations adicionais do ingress. | {} |
onboarding.ingress.hosts | Hosts configurados para Ingress e paths associados. | "" |
onboarding.ingress.tls | Configurações TLS para Ingress. | [] |
onboarding.resources.* | Requests/limits de recursos CPU/Memória. | See values.yaml |
onboarding.autoscaling.enabled | Especifica se o autoscaling está habilitado. | true |
onboarding.autoscaling.minReplicas | Número mínimo de réplicas para autoscaling. | 2 |
onboarding.autoscaling.maxReplicas | Número máximo de réplicas para autoscaling. | 5 |
onboarding.autoscaling.targetCPUUtilizationPercentage | Percentual alvo de utilização de CPU para autoscaling. | 80 |
onboarding.autoscaling.targetMemoryUtilizationPercentage | Percentual alvo de utilização de memória para autoscaling. | 80 |
onboarding.nodeSelector | Seletores de node para agendamento de pods. | {} |
onboarding.tolerations | Tolerations para agendamento de pods. | {} |
onboarding.affinity | Regras de afinidade para agendamento de pods. | {} |
onboarding.configmap.* | Variáveis de ambiente para o serviço. | See values.yaml |
onboarding.secrets.* | Secrets para o serviço. | See values.yaml |
onboarding.useExistingSecret | Usar um secret existente em vez de criar um novo. | false |
onboarding.existingSecretName | Nome do secret existente a ser usado. | "" |
onboarding.extraEnvVars | Lista de variáveis de ambiente extras. | [] |
onboarding.serviceAccount.create | Especifica se a service account deve ser criada. | true |
onboarding.serviceAccount.annotations | Annotations para a service account. | {} |
onboarding.serviceAccount.name | Nome da service account. Se não definido, será gerado automaticamente. | "" |
Criando o secret do Onboarding manualmente
Se você deseja usar um Kubernetes Secret existente para o serviço onboarding:Transaction (legado)
| Parâmetro | Descrição | Valor Padrão |
|---|---|---|
transaction.name | Nome do serviço. | "transaction" |
transaction.replicaCount | Número de réplicas para o serviço transaction service. | 1 |
transaction.image.repository | Repositório da imagem de container do serviço transaction service . | "lerianstudio/midaz-transaction" |
transaction.image.pullPolicy | Política de pull da imagem. | "IfNotPresent" |
transaction.image.tag | Tag da imagem usada para o deployment. | "3.3.4" |
transaction.imagePullSecrets | Secrets para pull de imagens de um registro privado. | [] |
transaction.nameOverride | Sobrescreve o nome padrão gerado pelo Helm. | "" |
transaction.fullnameOverride | Sobrescreve o nome completo gerado pelo Helm. | "" |
transaction.podAnnotations | Annotations do pod para metadados adicionais. | {} |
transaction.podSecurityContext | Contexto de segurança para o pod. | {} |
transaction.securityContext.* | Define configurações de contexto de segurança para o container. | See values.yaml |
transaction.pdb.enabled | Habilita ou desabilita PodDisruptionBudget. | true |
transaction.pdb.minAvailable | Número mínimo de pods disponíveis. | 2 |
transaction.pdb.maxUnavailable | Número máximo de pods indisponíveis. | 1 |
transaction.pdb.annotations | Annotations para o PodDisruptionBudget. | {} |
transaction.deploymentUpdate.* | Estratégia de atualização do deployment. | See values.yaml |
transaction.service.type | Tipo de serviço Kubernetes. | "ClusterIP" |
transaction.service.port | Porta para a API HTTP. | 3001 |
transaction.service.annotations | Annotations para o serviço. | {} |
transaction.ingress.enabled | Habilita ou desabilita ingress. | false |
transaction.ingress.className | Nome da classe do Ingress. | "" |
transaction.ingress.annotations | Annotations adicionais do ingress. | {} |
transaction.ingress.hosts | Hosts configurados para ingress e paths associados. | [] |
transaction.ingress.tls | Configuração TLS para ingress. | [] |
transaction.resources.* | Requests/limits de recursos CPU/Memória. | See values.yaml |
transaction.autoscaling.enabled | Habilita ou desabilita horizontal pod autoscaling. | true |
transaction.autoscaling.minReplicas | Número mínimo de réplicas para autoscaling. | 1 |
transaction.autoscaling.maxReplicas | Número máximo de réplicas para autoscaling. | 5 |
transaction.autoscaling.targetCPUUtilizationPercentage | Percentual alvo de utilização de CPU para autoscaling. | 80 |
transaction.autoscaling.targetMemoryUtilizationPercentage | Percentual alvo de utilização de memória para autoscaling. | 80 |
transaction.nodeSelector | Seletor de node para agendamento de pods em nodes específicos. | {} |
transaction.tolerations | Tolerations para agendamento em nodes com taints. | {} |
transaction.affinity | Regras de afinidade para agendamento de pods. | {} |
transaction.configmap.* | Variáveis de ambiente para o serviço. | See values.yaml |
transaction.secrets.* | Secrets para o serviço. | See values.yaml |
transaction.useExistingSecret | Usar um secret existente em vez de criar um novo. | false |
transaction.existingSecretName | Nome do secret existente a ser usado. | "" |
transaction.extraEnvVars | Lista de variáveis de ambiente extras. | [] |
transaction.serviceAccount.create | Especifica se uma ServiceAccount deve ser criada. | true |
transaction.serviceAccount.annotations | Annotations para a ServiceAccount. | {} |
transaction.serviceAccount.name | Nome da service account. | "" |
Criando o secret do Transaction manualmente
Se você deseja usar um Kubernetes Secret existente para o serviço transaction:O serviço transaction requer uma chave de secret adicional
RABBITMQ_CONSUMER_PASS em comparação ao onboarding.CRM (Customer Relationship Management)
O serviçocrm fornece APIs para gerenciar dados de holders e seus relacionamentos com contas do ledger. Anteriormente disponível como um chart separado (plugin-crm) implantado no namespace midaz-plugins, o CRM agora está integrado ao Helm chart principal do Midaz e é implantado no namespace midaz.
Se você está atualmente usando o
plugin-crm no namespace midaz-plugins, recomendamos migrar para este novo workload integrado de CRM. Veja o guia Atualizando o Helm para os passos de migração.| Parâmetro | Descrição | Valor Padrão |
|---|---|---|
crm.enabled | Habilita ou desabilita the CRM service. | false |
crm.name | Nome do serviço. | "crm" |
crm.replicaCount | Número de réplicas para o serviço CRM service. | 1 |
crm.image.repository | Repositório da imagem de container do serviço CRM service . | "ghcr.io/lerianstudio/midaz-crm" |
crm.image.pullPolicy | Política de pull da imagem. | "Always" |
crm.image.tag | Tag da imagem usada para o deployment. | "3.5.0" |
crm.imagePullSecrets | Secrets para pull de imagens de um registro privado. | [] |
crm.nameOverride | Sobrescreve o nome padrão gerado pelo Helm. | "" |
crm.fullnameOverride | Sobrescreve o nome completo gerado pelo Helm. | "" |
crm.podAnnotations | Annotations do pod para metadados adicionais. | {} |
crm.podSecurityContext | Contexto de segurança aplicado no nível do pod. | {} |
crm.securityContext.* | Define configurações de contexto de segurança para o container. | See values.yaml |
crm.pdb.enabled | Especifica se o PodDisruptionBudget está habilitado. | true |
crm.pdb.minAvailable | Número mínimo de pods disponíveis. | 1 |
crm.pdb.maxUnavailable | Número máximo de pods indisponíveis. | 1 |
crm.pdb.annotations | Annotations para o PodDisruptionBudget. | {} |
crm.deploymentUpdate.type | Tipo de estratégia de deployment. | "RollingUpdate" |
crm.deploymentUpdate.maxSurge | Número máximo de pods que podem ser criados acima do número desejado. | 1 |
crm.deploymentUpdate.maxUnavailable | Número máximo de pods que podem estar indisponíveis durante a atualização. | 1 |
crm.service.type | Tipo de serviço Kubernetes. | "ClusterIP" |
crm.service.port | Porta do serviço. | 4003 |
crm.ingress.enabled | Especifica se o Ingress está habilitado. | false |
crm.ingress.className | Nome da classe do Ingress. | "" |
crm.ingress.annotations | Annotations adicionais do ingress. | {} |
crm.ingress.hosts | Hosts configurados para Ingress e paths associados. | [] |
crm.ingress.tls | Configurações TLS para Ingress. | [] |
crm.resources.* | Requests/limits de recursos CPU/Memória. | See values.yaml |
crm.autoscaling.enabled | Especifica se o autoscaling está habilitado. | true |
crm.autoscaling.minReplicas | Número mínimo de réplicas para autoscaling. | 1 |
crm.autoscaling.maxReplicas | Número máximo de réplicas para autoscaling. | 3 |
crm.autoscaling.targetCPUUtilizationPercentage | Percentual alvo de utilização de CPU para autoscaling. | 80 |
crm.autoscaling.targetMemoryUtilizationPercentage | Percentual alvo de utilização de memória para autoscaling. | 80 |
crm.nodeSelector | Seletores de node para agendamento de pods. | {} |
crm.tolerations | Tolerations para agendamento de pods. | {} |
crm.affinity | Regras de afinidade para agendamento de pods. | {} |
crm.configmap.* | Variáveis de ambiente para o serviço. | See values.yaml |
crm.secrets.* | Secrets para o serviço. | See values.yaml |
crm.useExistingSecret | Usar um secret existente em vez de criar um novo. | false |
crm.existingSecretName | Nome do secret existente a ser usado. | "" |
crm.extraEnvVars | Lista de variáveis de ambiente extras. | {} |

