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

# Instalar y desplegar

> Guía paso a paso para instalar y desplegar plugins de Midaz en Kubernetes con Helm, que cubre requisitos previos, configuración de values y el trabajo posterior a la instalación.

<Warning>
  La orientación sobre CRM y Fees marcada como legacy en esta página aplica solo a releases legacy que ya existen. Midaz v4 despliega el Ledger unificado y sirve CRM y Fees en `/v2`.
</Warning>

En Midaz v4, el Ledger unificado contiene CRM y Fees como módulos. Usa su API `/v2` a través del Ledger. No son servicios, puertos, plugins ni releases de Helm separados.

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

<Note>
  Antes de desplegar cualquier plugin, confirma que tienes 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/deploy/midaz/midaz-installation) si todavía no configuraste Midaz.
</Note>

## Requisitos previos

***

Antes de desplegar plugins, confirma que tienes:

* Un clúster [**Kubernetes**](https://kubernetes.io/releases/) en ejecución con Midaz Core ya desplegado. Usa una versión menor con soporte vigente en producción.
* [**Helm 3.8 o posterior**](https://helm.sh/docs/intro/install/), para el soporte de registry OCI.
* **kubectl** configurado con acceso a tu clúster.
* Permisos de **administrador del clúster** o roles RBAC adecuados.
* Una **clave de licencia Enterprise** válida para el plugin que despliegas.

Verifica que tus herramientas estén listas:

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

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

<Tip>
  En Midaz v4, CRM se distribuye desde el mismo repositorio source-available de Midaz como un componente embebido del Ledger. No es un plugin con licencia separada. Los plugins desplegados por separado pueden requerir una licencia Enterprise. Contacta a un representante de Lerian si necesitas una.
</Tip>

## Charts de plugins disponibles

***

Cada plugin se distribuye como un Helm chart compatible con OCI.

| Plugin                  | Nombre del chart                  | Namespace predeterminado |
| :---------------------- | :-------------------------------- | :----------------------- |
| **Fees**                | `plugin-fees-helm`                | `midaz-plugins`          |
| **Pix**                 | `plugin-br-pix-direct-jd-helm`    | `midaz-plugins`          |
| **Pix Indirecto (BTG)** | `plugin-br-pix-indirect-btg-helm` | `midaz-plugins`          |
| **Bank Transfer**       | `plugin-br-bank-transfer-helm`    | `midaz-plugins`          |

Cada chart se publica en `oci://registry-1.docker.io/lerianstudio/<chart-name>`.

<Note>
  CRM es un módulo dentro del chart `midaz-helm`. Lo habilitas con el bloque de values `crm`. No existe un chart de CRM.
</Note>

## Instalar un plugin

***

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

### 1. Revisa las versiones disponibles

Lee la versión actual del chart desde el registry:

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

Revisa la [compatibilidad de versiones de plugins](/es/platform/deploy/midaz-version-compatibility) para encontrar una versión de plugin compatible con tu versión de Midaz Core, e inspecciona los metadatos del chart de ese plugin antes de desplegarlo.

### 2. Instala el 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="Pix Indirecto (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>

Reemplaza `<version>` por la versión de chart deseada. El flag `--create-namespace` crea el namespace `midaz-plugins` si todavía 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
```

Revisa el estado de los pods:

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

Se recomienda que todos los pods muestren el estado `Running` y el 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 <release-name> <oci-chart> \
    --version <version> \
    -n midaz-plugins \
    --create-namespace \
    -f my-plugin-values.yaml
  ```
</Tip>

## Configura el chart elegido

***

Los charts de plugins no comparten un único contrato de licencia, secret o persistencia. Inspecciona el `values.schema.json` del chart elegido y su documentación específica antes de definir values. No reutilices los ejemplos de CRM o Fees: en Midaz v4 son módulos del Ledger, no charts de plugin.

Por ejemplo, Bank Transfer requiere claves de cifrado específicas del chart y usa `bankTransfer.secrets.MONGO_URI` cuando su MongoDB incluido está deshabilitado. Su integración de licencia es opcional cuando `LICENSE_SERVICE_ADDRESS` y `TENANT_IDS` no están definidos. Otros plugins tienen requisitos distintos.

<Warning>
  Mantén los valores sensibles en Secrets de Kubernetes. No supongas que una clave aceptada por un plugin es válida para otro.
</Warning>

## Configurar el ingress

***

De forma predeterminada, los servicios de plugin usan `ClusterIP`, así que solo son accesibles dentro del clúster. Para exponer un plugin externamente, habilita el ingress en tu `values.yaml`.

La configuración de ingress sigue el mismo patrón que Midaz Core. Este es un ejemplo con 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>` por 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/deploy/midaz/midaz-ingress). Los mismos patrones aplican a los charts de plugins.
</Tip>

## Verificar tu despliegue

***

Después de instalar un plugin, verifica que corre correctamente.

### Revisa el estado de los pods

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

Se recomienda que todos los pods estén en estado `Running` con todos los contenedores listos.

### Revisa los logs de los pods

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

Busca mensajes de arranque exitoso y verifica que no haya errores relacionados con conexiones de base de datos, validación de licencia o configuración ausente.

### Prueba el endpoint de health

Cada plugin define sus propias rutas de probe. Léelas desde el Deployment:

```bash theme={null}
kubectl get deploy <plugin-deployment-name> -n midaz-plugins -o yaml
```

Lee el nombre del servicio y su puerto con `kubectl get svc -n midaz-plugins`. Luego haz port-forward del Service y llama a la ruta que leíste:

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

## Actualizar plugins

***

Para actualizar un plugin a una versión nueva, 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>
  Actualiza siempre **Midaz Core antes de actualizar los plugins**. Los plugins dependen de las APIs de Midaz Core, así que actualizar en el orden equivocado 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 con Helm](/es/platform/deploy/midaz/midaz-upgrade-guide).

## Desinstalar un plugin

***

Para quitar un plugin de tu clúster:

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

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

## Recursos relacionados

***

* [Desplegar Midaz con Helm](/es/platform/deploy/midaz/midaz-installation) – Guía de instalación inicial de Midaz Core
* [Guía de actualización con Helm](/es/platform/deploy/midaz/midaz-upgrade-guide) – Procedimientos de actualización e instrucciones de rollback
* [Compatibilidad de versiones del chart de Midaz](/es/platform/deploy/helm-version-compatibility) – Metadatos actuales del chart y de la aplicación de Midaz
* [Compatibilidad de versiones de plugins](/es/platform/deploy/midaz-version-compatibility) – Compatibilidad de los plugins con las versiones de Midaz Core
* [Nuestros plugins](/es/products/about-plugins) – Catálogo de plugins y cómo funcionan
* [Repositorio de Helm](https://github.com/LerianStudio/helm) – Código fuente, charts y notas de release