Instalação e deploy

Os plugins do Midaz são distribuídos como charts de Helm independentes e seguem o mesmo modelo de deploy que o Midaz Core. Cada plugin é executado como um serviço separado junto à plataforma, com sua própria configuração, dependências e ciclo de vida. Este guia orienta você na instalação, configuração e verificação de deploys de plugins no Kubernetes.

Antes de fazer deploy de qualquer plugin, certifique-se de ter uma instância do Midaz Core em execução. Os plugins dependem das APIs do Midaz Core e não podem operar de forma independente. Consulte o guia de deploy do Midaz com Helm se você ainda não configurou o Midaz.

Pré-requisitos

Antes de fazer deploy dos plugins, certifique-se de ter:

Kubernetes (v1.30+) – Um cluster em execução com o Midaz Core já implantado.
Helm 3+ – Instalado e disponível.
kubectl configurado com acesso ao seu cluster.
Permissões de administrador do cluster ou roles RBAC apropriadas.
Uma chave de licença Enterprise válida (necessária para todos os plugins exceto CRM).

Verifique se suas ferramentas estão prontas:

helm version

kubectl cluster-info

O plugin CRM é Código Aberto e não requer chave de licença. Todos os outros plugins requerem uma licença Enterprise válida. Entre em contato com um representante da Lerian se você precisar de uma.

Charts de plugins disponíveis

Cada plugin é publicado como um chart de Helm compatível com OCI. A tabela abaixo lista todos os plugins disponíveis e suas referências de chart.

Plugin	Nome do chart	Registro OCI	Namespace padrão
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`

A partir do Midaz v5.x, o plugin CRM também está disponível como componente integrado dentro do chart principal de Helm do Midaz. Se você está executando v5.x, pode habilitar o CRM diretamente nos seus valores do Midaz em vez de fazer deploy separadamente. Consulte o guia de Helm do Midaz para detalhes. Note também que os plugins Pix ainda estão em desenvolvimento ativo.

Instalando um plugin

O processo de instalação é o mesmo para todos os plugins. Substitua o nome do chart, registro e versão pelo plugin que deseja fazer deploy.

1. Consulte as versões disponíveis

Você pode encontrar as versões de chart disponíveis verificando as tags do repositório Helm no GitHub. Filtre pelo prefixo do plugin (ex.: plugin-crm-v, plugin-fees-v). Você também pode consultar a tabela de compatibilidade de versões para encontrar a versão de chart correta para sua versão do Midaz Core.

2. Instale o 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

Substitua <version> pela versão desejada do chart. O flag --create-namespace cria o namespace midaz-plugins se ele ainda não existir.

3. Verifique a instalação

Após instalar, confirme que o release está implantado:

helm list -n midaz-plugins

Verifique se todos os pods estão em execução:

kubectl get pods -n midaz-plugins

Todos os pods devem mostrar status Running e estado READY.

Para instalar um plugin com configuração personalizada, crie um arquivo values.yaml e passe-o com o flag -f:

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

Configurando chaves de licença

Todos os plugins exceto CRM requerem uma chave de licença Enterprise válida. Você a configura através da seção secrets do chart de Helm no seu values.yaml:

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

Substitua <plugin> pela chave de serviço do plugin (ex.: crm, fees).

Fazer deploy de um plugin licenciado sem uma chave válida resultará no serviço iniciando mas rejeitando requisições de API. Certifique-se de que sua chave de licença e IDs de organização estejam configurados antes de ir para produção.

Configurando dependências

Os plugins incluem suas próprias dependências de banco de dados por padrão. Isso significa que você pode fazer deploy de um plugin e ter uma configuração funcional sem nenhuma configuração adicional de banco de dados. No entanto, para ambientes de produção, você provavelmente vai querer usar seus próprios bancos de dados gerenciados.

MongoDB

Os plugins CRM, Fees Engine e Pix usam MongoDB para armazenamento de dados. Cada chart de plugin inclui uma dependência do Bitnami MongoDB incluída (v16.4.0) que é habilitada por padrão. Para usar uma instância externa de MongoDB, desabilite a dependência incluída e aponte o plugin para sua instância:

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>

Substitua <plugin> pela chave de serviço do plugin (ex.: crm, fees).

Usando Kubernetes Secrets existentes

Para ambientes de produção, você pode gerenciar secrets fora do Helm referenciando um Kubernetes Secret existente. Isso evita armazenar valores sensíveis diretamente no seu values.yaml.

Crie o secret

Crie um Kubernetes Secret com as chaves necessárias para seu plugin. Por exemplo, para 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

Referencie nos seus valores

Configure o plugin para usar o secret existente:

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

Este padrão funciona para todos os plugins. Cada plugin aceita os parâmetros useExistingSecret e existingSecretName.

Configurando ingress

Os serviços de plugins são implantados como ClusterIP por padrão, o que significa que só são acessíveis dentro do cluster. Para expor um plugin externamente, habilite ingress no seu values.yaml. A configuração de ingress segue o mesmo padrão do Midaz Core. Aqui está um exemplo usando 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

Substitua <plugin> pela chave de serviço do plugin.

Para exemplos detalhados de configuração de ingress com AWS ALB e Traefik, consulte o guia de deploy do Midaz com Helm. Os mesmos padrões se aplicam aos charts de plugins.

Verificando seu deploy

Após instalar um plugin, verifique se tudo está funcionando corretamente.

Verifique o status dos pods

kubectl get pods -n midaz-plugins -o wide

Todos os pods devem estar no estado Running com todos os containers prontos.

Verifique os logs dos pods

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

Procure por mensagens de inicialização bem-sucedidas e verifique se não há erros relacionados a conexões com o banco de dados, validação de licença ou configuração ausente.

Teste o endpoint de saúde

Todos os plugins expõem um endpoint /health. Você pode verificá-lo via port-forwarding:

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

Depois verifique o endpoint de saúde:

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

Plugin	Nome do serviço	Porta padrão
CRM	`plugin-crm`	4003
Fees Engine	`plugin-fees`	4002

Atualizando plugins

Para atualizar um plugin para uma nova versão, use helm upgrade com a versão-alvo:

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

Sempre atualize o Midaz Core antes de atualizar plugins. Os plugins dependem das APIs do Midaz Core, então atualizar na ordem errada pode causar problemas de compatibilidade.

Para procedimentos detalhados de atualização, checklists pré-atualização e instruções de rollback, consulte o guia de atualização do Helm.

Desinstalando um plugin

Para remover um plugin do seu cluster:

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

Por exemplo:

helm uninstall plugin-crm -n midaz-plugins

Desinstalar um plugin remove seus recursos do Kubernetes (deployments, services, configmaps, secrets) mas não exclui dados persistentes armazenados em bancos de dados. Se você usou o MongoDB incluído, os PersistentVolumeClaims podem permanecer. Exclua-os manualmente se quiser fazer uma limpeza completa.

Recursos relacionados

Deploy do Midaz usando Helm – Guia de instalação inicial do Midaz Core
Guia de atualização do Helm – Procedimentos de atualização e instruções de rollback
Compatibilidade de versões – Mapeamento de versões de charts de Helm e aplicações
Compatibilidade de versões de plugins – Compatibilidade de plugins com versões do Midaz Core
O que são plugins? – Visão geral da arquitetura de plugins
Repositório Helm – Código-fonte, charts e notas de release

Introdução

CRM

Fees Engine

Pix

Pix Indireto

Pix Direto

Transferência bancária (TED)

Instalação e deploy

Pré-requisitos

Charts de plugins disponíveis

Instalando um plugin

1. Consulte as versões disponíveis

2. Instale o chart

3. Verifique a instalação

Configurando chaves de licença

Configurando dependências

MongoDB

Usando Kubernetes Secrets existentes

Configurando ingress

Verificando seu deploy

Verifique o status dos pods

Verifique os logs dos pods

Teste o endpoint de saúde

Atualizando plugins

Desinstalando um plugin

Recursos relacionados

Introdução

CRM

Fees Engine

Pix

Pix Indireto

Pix Direto

Transferência bancária (TED)

​Pré-requisitos

​Charts de plugins disponíveis

​Instalando um plugin

​1. Consulte as versões disponíveis

​2. Instale o chart

​3. Verifique a instalação

​Configurando chaves de licença

​Configurando dependências

​MongoDB

​Usando Kubernetes Secrets existentes

​Configurando ingress

​Verificando seu deploy

​Verifique o status dos pods

​Verifique os logs dos pods

​Teste o endpoint de saúde

​Atualizando plugins

​Desinstalando um plugin

​Recursos relacionados

Pré-requisitos

Charts de plugins disponíveis

Instalando um plugin

1. Consulte as versões disponíveis

2. Instale o chart

3. Verifique a instalação

Configurando chaves de licença

Configurando dependências

MongoDB

Usando Kubernetes Secrets existentes

Configurando ingress

Verificando seu deploy

Verifique o status dos pods

Verifique os logs dos pods

Teste o endpoint de saúde

Atualizando plugins

Desinstalando um plugin

Recursos relacionados