> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Instalação e deploy

> Guia passo a passo para instalar e fazer o deploy dos plugins do Midaz em Kubernetes com Helm, cobrindo pré-requisitos, configuração de values e o trabalho após a instalação.

<Warning>
  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`.
</Warning>

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.

<Note>
  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](/pt/platform/deploy/midaz/midaz-installation) se você ainda não configurou o Midaz.
</Note>

## Pré-requisitos

***

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

* Um cluster [**Kubernetes**](https://kubernetes.io/releases/) rodando com o Midaz Core já no ar. Use uma minor release com suporte atual em produção.
* [**Helm 3.8 ou posterior**](https://helm.sh/docs/intro/install/), 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:

```bash theme={null}
helm version
```

```bash theme={null}
kubectl cluster-info
```

<Tip>
  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.
</Tip>

## 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>`.

<Note>
  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.
</Note>

## 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:

```bash theme={null}
helm show chart oci://registry-1.docker.io/lerianstudio/<chart-name>
```

Confira a [compatibilidade de versões de plugin](/pt/platform/deploy/midaz-version-compatibility) 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

<Tabs>
  <Tab title="Pix">
    ```bash theme={null}
    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
    ```
  </Tab>

  <Tab title="Indirect Pix (BTG)">
    ```bash theme={null}
    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
    ```
  </Tab>
</Tabs>

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:

```bash theme={null}
helm list -n midaz-plugins
```

Verifique o status dos pods:

```bash theme={null}
kubectl get pods -n midaz-plugins
```

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

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

  ```bash theme={null}
  helm install <release-name> <oci-chart> \
    --version <version> \
    -n midaz-plugins \
    --create-namespace \
    -f my-plugin-values.yaml
  ```
</Tip>

## 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.

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

## 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:

```yaml theme={null}
<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.

<Tip>
  Para exemplos detalhados de configuração de ingress com **AWS ALB** e **Traefik**, veja o [guia de deploy do Midaz com Helm](/pt/platform/deploy/midaz/midaz-ingress). Os mesmos padrões valem para charts de plugin.
</Tip>

## Verificando seu deploy

***

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

### Verifique o status dos pods

```bash theme={null}
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

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
helm upgrade <release-name> <oci-registry> \
  --version <new-version> \
  -n midaz-plugins \
  -f my-plugin-values.yaml
```

<Note>
  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.
</Note>

Para procedimentos de atualização detalhados, checklists de pré-atualização e instruções de rollback, veja o [guia de atualização do Helm](/pt/platform/deploy/midaz/midaz-upgrade-guide).

## Desinstalando um plugin

***

Para remover um plugin do seu cluster:

```bash theme={null}
helm uninstall <release-name> -n midaz-plugins
```

<Warning>
  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.
</Warning>

## Recursos relacionados

***

* [Deploy do Midaz com Helm](/pt/platform/deploy/midaz/midaz-installation) – guia de instalação inicial do Midaz Core
* [Guia de atualização do Helm](/pt/platform/deploy/midaz/midaz-upgrade-guide) – procedimentos de atualização e instruções de rollback
* [Compatibilidade de versões do chart do Midaz](/pt/platform/deploy/helm-version-compatibility) – metadados atuais do chart e da aplicação Midaz
* [Compatibilidade de versões de plugin](/pt/platform/deploy/midaz-version-compatibility) – compatibilidade dos plugins com as versões do Midaz Core
* [Nossos plugins](/pt/products/about-plugins) – catálogo de plugins e como os plugins funcionam
* [Repositório do Helm](https://github.com/LerianStudio/helm) – código-fonte, charts e notas de release