Instalación y despliegue

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.

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 si aún no has configurado Midaz.

Prerrequisitos

Antes de desplegar plugins, asegúrate de tener:

Kubernetes (v1.30+) – Un clúster en ejecución con Midaz Core ya desplegado.
Helm 3+ – 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:

helm version

kubectl cluster-info

El plugin CRM es de código abierto y no requiere clave de licencia. Todos los demás plugins requieren una licencia Enterprise válida. Contacta a un representante de Lerian si necesitas una.

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

A partir de Midaz v5.x, el plugin CRM también 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 para más detalles. También ten en cuenta que los plugins Pix aún están en desarrollo activo.

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 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 para encontrar la versión de chart correcta para tu versión de Midaz Core.

2. Instala el chart

CRM
Fees Engine
Pix Direct (JD)
Pix Indirect (BTG)

helm install plugin-crm oci://registry-1.docker.io/lerianstudio/plugin-crm \
  --version <version> \
  -n midaz-plugins \
  --create-namespace

helm install plugin-fees oci://registry-1.docker.io/lerianstudio/plugin-fees-helm \
  --version <version> \
  -n midaz-plugins \
  --create-namespace

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

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

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:

helm list -n midaz-plugins

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

kubectl get pods -n midaz-plugins

Todos los pods deben mostrar estado Running y estado READY.

Para instalar un plugin con configuración personalizada, crea un archivo values.yaml y pásalo con el flag -f:

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

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:

<plugin>:
  secrets:
    LICENSE_KEY: "<your-license-key>"
    ORGANIZATION_IDS: "<your-organization-ids>"

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

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.

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 plugins CRM, Fees Engine y Pix usan MongoDB para almacenamiento de datos. Cada chart de plugin incluye una dependencia de Bitnami MongoDB 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:

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.

Crea el secret

Crea un Kubernetes Secret con las claves requeridas para tu plugin. Por ejemplo, para CRM:

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

Referéncialo en tus valores

Configura el plugin para usar el secret existente:

crm:
  useExistingSecret: true
  existingSecretName: "plugin-crm-secrets"

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:

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

Para ejemplos detallados de configuración de ingress con AWS ALB y Traefik, consulta la guía de despliegue de Midaz con Helm. Los mismos patrones aplican a los charts de plugins.

Verificando tu despliegue

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

Verifica el estado de los pods

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

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:

kubectl port-forward -n midaz-plugins svc/<plugin-service-name> <local-port>:<service-port>

Luego verifica el endpoint de salud:

curl http://localhost:<local-port>/health

Plugin	Nombre del servicio	Puerto predeterminado
CRM	`plugin-crm`	4003
Fees Engine	`plugin-fees`	4002

Actualizando plugins

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

helm upgrade <release-name> <oci-registry> \
  --version <new-version> \
  -n midaz-plugins \
  -f my-plugin-values.yaml

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.

Para procedimientos detallados de actualización, listas de verificación previas y instrucciones de rollback, consulta la guía de actualización de Helm.

Desinstalando un plugin

Para eliminar un plugin de tu clúster:

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

Por ejemplo:

helm uninstall plugin-crm -n midaz-plugins

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.

Recursos relacionados

Desplegar Midaz usando Helm – Guía de instalación inicial de Midaz Core
Guía de actualización de Helm – Procedimientos de actualización e instrucciones de rollback
Compatibilidad de versiones – Mapeo de versiones de charts de Helm y aplicaciones
Compatibilidad de versiones de plugins – Compatibilidad de plugins con versiones de Midaz Core
¿Qué son los plugins? – Resumen de la arquitectura de plugins
Repositorio Helm – Código fuente, charts y notas de release

Introducción

CRM

Fees Engine

Pix

Pix Indirecto

Pix Directo

Transferencia bancaria (TED)

Instalación y despliegue

Prerrequisitos

Charts de plugins disponibles

Instalando un plugin

1. Consulta las versiones disponibles

2. Instala el chart

3. Verifica la instalación

Configurando claves de licencia

Configurando dependencias

MongoDB

Usando Kubernetes Secrets existentes

Configurando ingress

Verificando tu despliegue

Verifica el estado de los pods

Verifica los logs de los pods

Prueba el endpoint de salud

Actualizando plugins

Desinstalando un plugin

Recursos relacionados

Introducción

CRM

Fees Engine

Pix

Pix Indirecto

Pix Directo

Transferencia bancaria (TED)

​Prerrequisitos

​Charts de plugins disponibles

​Instalando un plugin

​1. Consulta las versiones disponibles

​2. Instala el chart

​3. Verifica la instalación

​Configurando claves de licencia

​Configurando dependencias

​MongoDB

​Usando Kubernetes Secrets existentes

​Configurando ingress

​Verificando tu despliegue

​Verifica el estado de los pods

​Verifica los logs de los pods

​Prueba el endpoint de salud

​Actualizando plugins

​Desinstalando un plugin

​Recursos relacionados

Prerrequisitos

Charts de plugins disponibles

Instalando un plugin

1. Consulta las versiones disponibles

2. Instala el chart

3. Verifica la instalación

Configurando claves de licencia

Configurando dependencias

MongoDB

Usando Kubernetes Secrets existentes

Configurando ingress

Verificando tu despliegue

Verifica el estado de los pods

Verifica los logs de los pods

Prueba el endpoint de salud

Actualizando plugins

Desinstalando un plugin

Recursos relacionados