Instalação e deploy

A orientação de CRM e Fees marcada como legada nesta página vale apenas para releases legados que já existem. O Midaz v4 entrega o Ledger unificado e serve CRM e Fees em /v2.

No Midaz v4, o Ledger unificado contém CRM e Fees como módulos. Use a API /v2 deles pelo Ledger. Eles não são serviços, portas, plugins nem releases Helm separados. Os plugins do Midaz são entregues como Helm charts independentes e seguem o mesmo modelo de deploy do Midaz Core. Cada plugin roda como um serviço separado ao lado da plataforma, com configuração, dependências e ciclo de vida próprios.

Antes de fazer o deploy de qualquer plugin, confirme que você tem uma instância do Midaz Core rodando. Os plugins dependem das APIs do Midaz Core e não conseguem operar de forma independente. Veja o guia de deploy do Midaz com Helm se você ainda não configurou o Midaz.

Pré-requisitos

Antes de fazer o deploy de plugins, confirme que você tem:

Um cluster Kubernetes rodando com o Midaz Core já no ar. Use uma minor release com suporte atual em produção.
Helm 3.8 ou posterior, para suporte a registry OCI.
kubectl configurado com acesso ao seu cluster.
Permissões de administrador do cluster ou papéis RBAC adequados.
Uma chave de licença Enterprise válida para o plugin do seu deploy.

Confirme que suas ferramentas estão prontas:

helm version

kubectl cluster-info

No Midaz v4, o CRM vem do mesmo repositório source-available do Midaz como um componente embutido do Ledger. Ele não é um plugin com licença separada. Plugins com deploy separado podem exigir uma licença Enterprise. Fale com um representante da Lerian se você precisar de uma.

Charts de plugin disponíveis

Cada plugin é entregue como um Helm chart compatível com OCI.

Plugin	Nome do chart	Namespace padrão
Fees	`plugin-fees-helm`	`midaz-plugins`
Pix	`plugin-br-pix-direct-jd-helm`	`midaz-plugins`
Indirect Pix (BTG)	`plugin-br-pix-indirect-btg-helm`	`midaz-plugins`
Bank Transfer	`plugin-br-bank-transfer-helm`	`midaz-plugins`

Cada chart é publicado em oci://registry-1.docker.io/lerianstudio/<chart-name>.

O CRM é um módulo dentro do chart midaz-helm. Você o habilita com o bloco de values crm. Não existe chart de CRM.

Instalando um plugin

O processo de instalação é o mesmo para todos os plugins. Substitua o nome do chart, o registry e a versão pelos do plugin do qual você quer fazer o deploy.

1. Verifique as versões disponíveis

Leia a versão atual do chart no registry:

helm show chart oci://registry-1.docker.io/lerianstudio/<chart-name>

Confira a compatibilidade de versões de plugin para achar uma versão de plugin compatível com a sua versão do Midaz Core, e inspecione os metadados do chart desse plugin antes do deploy.

2. Instale o chart

Pix
Indirect Pix (BTG)

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

Substitua <version> pela versão de chart desejada. A flag --create-namespace cria o namespace midaz-plugins se ele ainda não existe.

3. Verifique a instalação

Depois de instalar, confirme que o release está no ar:

helm list -n midaz-plugins

Verifique o status dos pods:

kubectl get pods -n midaz-plugins

Recomenda-se que todos os pods mostrem o status Running e o estado READY.

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

helm install <release-name> <oci-chart> \
  --version <version> \
  -n midaz-plugins \
  --create-namespace \
  -f my-plugin-values.yaml

Configure o chart escolhido

Os charts de plugin não compartilham um mesmo contrato de licença, de secret ou de persistência. Inspecione o values.schema.json do chart escolhido e a documentação específica dele antes de definir values. Não reaproveite exemplos de CRM ou Fees: no Midaz v4 eles são módulos do Ledger, não charts de plugin. Por exemplo, o Bank Transfer exige chaves de criptografia específicas do chart e usa bankTransfer.secrets.MONGO_URI quando o MongoDB empacotado dele está desabilitado. A integração de licença dele é opcional quando LICENSE_SERVICE_ADDRESS e TENANT_IDS não estão definidos. Outros plugins têm requisitos diferentes.

Guarde valores sensíveis em Secrets do Kubernetes. Não suponha que uma chave aceita por um plugin é válida para outro.

Configurando ingress

Por padrão, os serviços de plugin usam ClusterIP, então eles são acessíveis apenas dentro do cluster. Para expor um plugin externamente, habilite o ingress no seu values.yaml. A configuração de ingress segue o mesmo padrão do Midaz Core. Veja um exemplo com 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, veja o guia de deploy do Midaz com Helm. Os mesmos padrões valem para charts de plugin.

Verificando seu deploy

Depois de instalar um plugin, verifique se ele roda corretamente.

Verifique o status dos pods

kubectl get pods -n midaz-plugins -o wide

Recomenda-se que todos os pods estejam 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 mensagens de subida bem-sucedida e confirme que não há erros ligados a conexões de banco, validação de licença ou configuração ausente.

Teste o endpoint de health

Cada plugin define os próprios caminhos de probe. Leia-os no Deployment:

kubectl get deploy <plugin-deployment-name> -n midaz-plugins -o yaml

Leia o nome do serviço e a porta dele com kubectl get svc -n midaz-plugins. Depois faça port-forward do Service e chame o caminho que você leu:

kubectl port-forward -n midaz-plugins svc/<plugin-service-name> <local-port>:<service-port>
curl http://localhost:<local-port>/<probe-path>

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 os plugins. Os plugins dependem das APIs do Midaz Core, então atualizar na ordem errada pode causar problemas de compatibilidade.

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

Desinstalando um plugin

Para remover um plugin do seu cluster:

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

Desinstalar um plugin remove os recursos Kubernetes dele (deployments, services, configmaps, secrets), mas não exclui os dados persistentes guardados em bancos de dados. Se você usou o MongoDB empacotado, os PersistentVolumeClaims podem permanecer. Exclua-os manualmente se você quiser limpar tudo.

Recursos relacionados

Deploy do Midaz com 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 do chart do Midaz – metadados atuais do chart e da aplicação Midaz
Compatibilidade de versões de plugin – compatibilidade dos plugins com as versões do Midaz Core
Nossos plugins – catálogo de plugins e como os plugins funcionam
Repositório do Helm – código-fonte, charts e notas de release

Introdução

Midaz

Outros produtos

Instalação e deploy

Pré-requisitos

Charts de plugin disponíveis

Instalando um plugin

1. Verifique as versões disponíveis

2. Instale o chart

3. Verifique a instalação

Configure o chart escolhido

Configurando ingress

Verificando seu deploy

Verifique o status dos pods

Verifique os logs dos pods

Teste o endpoint de health

Atualizando plugins

Desinstalando um plugin

Recursos relacionados

​Pré-requisitos

​Charts de plugin disponíveis

​Instalando um plugin

​1. Verifique as versões disponíveis

​2. Instale o chart

​3. Verifique a instalação

​Configure o chart escolhido

​Configurando ingress

​Verificando seu deploy

​Verifique o status dos pods

​Verifique os logs dos pods

​Teste o endpoint de health

​Atualizando plugins

​Desinstalando um plugin

​Recursos relacionados

Pré-requisitos

Charts de plugin disponíveis

Instalando um plugin

1. Verifique as versões disponíveis

2. Instale o chart

3. Verifique a instalação

Configure o chart escolhido

Configurando ingress

Verificando seu deploy

Verifique o status dos pods

Verifique os logs dos pods

Teste o endpoint de health

Atualizando plugins

Desinstalando um plugin

Recursos relacionados