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

# Instalación y despliegue

> Guía paso a paso para instalar y desplegar los plugins de Midaz en Kubernetes usando Helm.

Los plugins de Midaz se distribuyen como **charts de Helm independientes** y siguen el mismo modelo de despliegue que Midaz Core. Cada plugin se ejecuta como un servicio separado junto a la plataforma, con su propia configuración, dependencias y ciclo de vida.

Esta guía te lleva a través de la instalación, configuración y verificación de despliegues de plugins en Kubernetes.

<Note>
  Antes de desplegar cualquier plugin, asegúrate de tener una instancia de **Midaz Core** en ejecución. Los plugins dependen de las APIs de Midaz Core y no pueden operar de forma independiente. Consulta la [guía de despliegue de Midaz con Helm](/es/platform/helm/midaz/midaz-installation) si aún no has configurado Midaz.
</Note>

## Prerrequisitos

***

Antes de desplegar plugins, asegúrate de tener:

* [**Kubernetes (v1.30+)**](https://kubernetes.io/releases/download/) – Un clúster en ejecución con Midaz Core ya desplegado.
* [**Helm 3+**](https://helm.sh/docs/intro/install/) – Instalado y disponible.
* **kubectl** configurado con acceso a tu clúster.
* Permisos de **administrador del clúster** o roles RBAC apropiados.
* Una **clave de licencia Enterprise** válida (requerida para todos los plugins excepto CRM).

Verifica que tus herramientas estén listas:

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

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

<Tip>
  El CRM no requiere clave de licencia y, a partir de Midaz v5.x, está disponible como componente integrado de Midaz, distribuido desde el mismo repositorio source-available de Midaz. Todos los demás plugins requieren una licencia Enterprise válida. Contacta a un representante de Lerian si necesitas una.
</Tip>

## Charts de plugins disponibles

***

Cada plugin se publica como un chart de Helm compatible con OCI. La tabla a continuación lista todos los plugins disponibles y sus referencias de chart.

| Plugin                 | Nombre del chart             | Registro OCI                                                           | Namespace predeterminado |
| :--------------------- | :--------------------------- | :--------------------------------------------------------------------- | :----------------------- |
| **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 Directo (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 de Midaz v5.x, el **CRM** ahora está disponible como componente integrado dentro del chart principal de Helm de Midaz. Si estás ejecutando v5.x, puedes habilitar CRM directamente en tus valores de Midaz en lugar de desplegarlo por separado. Consulta la [guía de Helm de Midaz](/es/platform/helm/midaz/midaz-installation) para más detalles.
</Note>

## Instalando un plugin

***

El proceso de instalación es el mismo para todos los plugins. Reemplaza el nombre del chart, registro y versión por el plugin que deseas desplegar.

### 1. Consulta las versiones disponibles

Puedes encontrar las versiones de chart disponibles revisando los [tags del repositorio Helm](https://github.com/LerianStudio/helm/tags) en GitHub. Filtra por el prefijo del plugin (ej., `plugin-crm-v`, `plugin-fees-v`).

También puedes consultar la [tabla de compatibilidad de versiones](/es/platform/helm/helm-version-compatibility) para encontrar la versión de chart correcta para tu versión de Midaz Core.

### 2. Instala el 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 Directo (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>

Reemplaza `<version>` con la versión deseada del chart. El flag `--create-namespace` crea el namespace `midaz-plugins` si aún no existe.

### 3. Verifica la instalación

Después de instalar, confirma que el release está desplegado:

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

Verifica que todos los pods estén en ejecución:

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

Todos los pods deben mostrar estado `Running` y estado `READY`.

<Tip>
  Para instalar un plugin con configuración personalizada, crea un archivo `values.yaml` y pásalo con el 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 claves de licencia

***

Todos los plugins excepto CRM requieren una clave de licencia Enterprise válida. La configuras a través de la sección `secrets` del chart de Helm en tu `values.yaml`:

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

Reemplaza `<plugin>` con la clave de servicio del plugin (ej., `crm`, `fees`).

<Warning>
  Desplegar un plugin con licencia sin una clave válida resultará en que el servicio inicie pero rechace las solicitudes de API. Asegúrate de que tu clave de licencia e IDs de organización estén configurados antes de ir a producción.
</Warning>

## Configurando dependencias

***

Los plugins incluyen sus propias dependencias de base de datos por defecto. Esto significa que puedes desplegar un plugin y tener una configuración funcional sin ninguna configuración de base de datos adicional. Sin embargo, para entornos de producción, probablemente querrás usar tus propias bases de datos gestionadas.

### MongoDB

Los charts **CRM**, **Fees Engine** y **Pix** usan MongoDB para almacenamiento de datos. Cada chart incluye una dependencia de [Bitnami MongoDB](https://charts.bitnami.com/bitnami) incluida (v16.4.0) que está habilitada por defecto.

Para usar una instancia **externa de MongoDB**, deshabilita la dependencia incluida y apunta el plugin a tu instancia:

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

Reemplaza `<plugin>` con la clave de servicio del plugin (ej., `crm`, `fees`).

## Usando Kubernetes Secrets existentes

***

Para entornos de producción, puedes gestionar secretos fuera de Helm referenciando un Kubernetes Secret existente. Esto evita almacenar valores sensibles directamente en tu `values.yaml`.

<Steps>
  <Step title="Crea el secret">
    Crea un Kubernetes Secret con las claves requeridas para tu plugin. Por ejemplo, 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="Referéncialo en tus valores">
    Configura el plugin para usar el secret existente:

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

Este patrón funciona para todos los plugins. Cada plugin acepta los parámetros `useExistingSecret` y `existingSecretName`.

## Configurando ingress

***

Los servicios de plugins se despliegan como `ClusterIP` por defecto, lo que significa que solo son accesibles dentro del clúster. Para exponer un plugin externamente, habilita ingress en tu `values.yaml`.

La configuración de ingress sigue el mismo patrón que Midaz Core. Aquí hay un ejemplo 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
```

Reemplaza `<plugin>` con la clave de servicio del plugin.

<Tip>
  Para ejemplos detallados de configuración de ingress con **AWS ALB** y **Traefik**, consulta la [guía de despliegue de Midaz con Helm](/es/platform/helm/midaz/midaz-installation). Los mismos patrones aplican a los charts de plugins.
</Tip>

## Verificando tu despliegue

***

Después de instalar un plugin, verifica que todo esté funcionando correctamente.

### Verifica el estado de los pods

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

Todos los pods deben estar en estado `Running` con todos los contenedores listos.

### Verifica los logs de los pods

```bash theme={null}
kubectl logs -n midaz-plugins deployment/<plugin-deployment-name> --tail=50
```

Busca mensajes de inicio exitoso y verifica que no haya errores relacionados con conexiones a la base de datos, validación de licencia o configuración faltante.

### Prueba el endpoint de salud

Todos los plugins exponen un endpoint `/health`. Puedes verificarlo vía port-forwarding:

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

Luego verifica el endpoint de salud:

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

| Plugin             | Nombre del servicio          | Puerto predeterminado |
| :----------------- | :--------------------------- | :-------------------- |
| CRM                | `plugin-crm`                 | 4003                  |
| Fees Engine        | `plugin-fees`                | 4002                  |
| Pix Indirect (BTG) | `plugin-br-pix-indirect-btg` | 8080                  |

## Actualizando plugins

***

Para actualizar un plugin a una nueva versión, usa `helm upgrade` con la versión objetivo:

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

<Note>
  Siempre actualiza **Midaz Core antes de actualizar plugins**. Los plugins dependen de las APIs de Midaz Core, por lo que actualizar en el orden incorrecto puede causar problemas de compatibilidad.
</Note>

Para procedimientos detallados de actualización, listas de verificación previas y instrucciones de rollback, consulta la [guía de actualización de Helm](/es/platform/helm/midaz/midaz-upgrade-guide).

## Desinstalando un plugin

***

Para eliminar un plugin de tu clúster:

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

Por ejemplo:

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

<Warning>
  Desinstalar un plugin elimina sus recursos de Kubernetes (deployments, services, configmaps, secrets) pero **no** elimina datos persistentes almacenados en bases de datos. Si usaste el MongoDB incluido, los PersistentVolumeClaims pueden permanecer. Elimínalos manualmente si deseas limpiar completamente.
</Warning>

## Recursos relacionados

***

* [Desplegar Midaz usando Helm](/es/platform/helm/midaz/midaz-installation) – Guía de instalación inicial de Midaz Core
* [Guía de actualización de Helm](/es/platform/helm/midaz/midaz-upgrade-guide) – Procedimientos de actualización e instrucciones de rollback
* [Compatibilidad de versiones](/es/platform/helm/helm-version-compatibility) – Mapeo de versiones de charts de Helm y aplicaciones
* [Compatibilidad de versiones de plugins](/es/platform/plugins/midaz-version-compatibility) – Compatibilidad de plugins con versiones de Midaz Core
* [¿Qué son los plugins?](/es/platform/plugins/what-are-plugins) – Resumen de la arquitectura de plugins
* [Repositorio Helm](https://github.com/LerianStudio/helm) – Código fuente, charts y notas de release