> ## 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 deploy dos plugins do Midaz no Kubernetes usando Helm.

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.

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

## Pré-requisitos

***

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

* [**Kubernetes (v1.30+)**](https://kubernetes.io/releases/download/) – Um cluster em execução com o Midaz Core já implantado.
* [**Helm 3+**](https://helm.sh/docs/intro/install/) – 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:

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

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

<Tip>
  O CRM não requer chave de licença e, a partir do Midaz v5.x, está disponível como componente integrado do Midaz, distribuído a partir do mesmo repositório source-available do Midaz. Todos os outros plugins requerem uma licença Enterprise válida. Entre em contato com um representante da Lerian se você precisar de uma.
</Tip>

## 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`  |
| **Bank Transfer**      | `plugin-br-bank-transfer`    | `oci://registry-1.docker.io/lerianstudio/plugin-br-bank-transfer-helm` | `midaz-plugins`  |

<Note>
  A partir do Midaz v5.x, o **CRM** agora 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](/pt/platform/helm/midaz/midaz-installation) para detalhes.
</Note>

## 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](https://github.com/LerianStudio/helm/tags) 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](/pt/platform/helm/helm-version-compatibility) para encontrar a versão de chart correta para sua versão do Midaz Core.

### 2. Instale o chart

<Tabs>
  <Tab title="CRM">
    ```bash theme={null}
    helm install plugin-crm oci://registry-1.docker.io/lerianstudio/plugin-crm \
      --version <version> \
      -n midaz-plugins \
      --create-namespace
    ```
  </Tab>

  <Tab title="Fees Engine">
    ```bash theme={null}
    helm install plugin-fees oci://registry-1.docker.io/lerianstudio/plugin-fees-helm \
      --version <version> \
      -n midaz-plugins \
      --create-namespace
    ```
  </Tab>

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

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

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:

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

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

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

Todos os pods devem mostrar status `Running` e estado `READY`.

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

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

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

```yaml theme={null}
<plugin>:
  secrets:
    LICENSE_KEY: "<your-license-key>"
    ORGANIZATION_IDS: "<your-organization-ids>"
```

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

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

## 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 charts **CRM**, **Fees Engine** e **Pix** usam MongoDB para armazenamento de dados. Cada chart inclui uma dependência do [Bitnami MongoDB](https://charts.bitnami.com/bitnami) 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:

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

<Steps>
  <Step title="Crie o secret">
    Crie um Kubernetes Secret com as chaves necessárias para seu plugin. Por exemplo, para CRM:

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

  <Step title="Referencie nos seus valores">
    Configure o plugin para usar o secret existente:

    ```yaml theme={null}
    crm:
      useExistingSecret: true
      existingSecretName: "plugin-crm-secrets"
    ```
  </Step>
</Steps>

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:

```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**, consulte o [guia de deploy do Midaz com Helm](/pt/platform/helm/midaz/midaz-installation). Os mesmos padrões se aplicam aos charts de plugins.
</Tip>

## Verificando seu deploy

***

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

### Verifique o status dos pods

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

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

```bash theme={null}
kubectl port-forward -n midaz-plugins svc/<plugin-service-name> <local-port>:<service-port>
```

Depois verifique o endpoint de saúde:

```bash theme={null}
curl http://localhost:<local-port>/health
```

| Plugin             | Nome do serviço              | Porta padrão |
| :----------------- | :--------------------------- | :----------- |
| CRM                | `plugin-crm`                 | 4003         |
| Fees Engine        | `plugin-fees`                | 4002         |
| Pix Indirect (BTG) | `plugin-br-pix-indirect-btg` | 8080         |

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

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

## Desinstalando um plugin

***

Para remover um plugin do seu cluster:

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

Por exemplo:

```bash theme={null}
helm uninstall plugin-crm -n midaz-plugins
```

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

## Recursos relacionados

***

* [Deploy do Midaz usando Helm](/pt/platform/helm/midaz/midaz-installation) – Guia de instalação inicial do Midaz Core
* [Guia de atualização do Helm](/pt/platform/helm/midaz/midaz-upgrade-guide) – Procedimentos de atualização e instruções de rollback
* [Compatibilidade de versões](/pt/platform/helm/helm-version-compatibility) – Mapeamento de versões de charts de Helm e aplicações
* [Compatibilidade de versões de plugins](/pt/platform/plugins/midaz-version-compatibility) – Compatibilidade de plugins com versões do Midaz Core
* [O que são plugins?](/pt/platform/plugins/what-are-plugins) – Visão geral da arquitetura de plugins
* [Repositório Helm](https://github.com/LerianStudio/helm) – Código-fonte, charts e notas de release