Instalar y desplegar

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.

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.

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 si todavía no configuraste Midaz.

Requisitos previos

Antes de desplegar plugins, confirma que tienes:

Un clúster Kubernetes en ejecución con Midaz Core ya desplegado. Usa una versión menor con soporte vigente en producción.
Helm 3.8 o posterior, 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:

helm version

kubectl cluster-info

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.

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

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

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:

helm show chart oci://registry-1.docker.io/lerianstudio/<chart-name>

Revisa la compatibilidad de versiones de plugins 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

Pix
Pix Indirecto (BTG)

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

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

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:

helm list -n midaz-plugins

Revisa el estado de los pods:

kubectl get pods -n midaz-plugins

Se recomienda que todos los pods muestren el estado Running y el estado READY.

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

helm install <release-name> <oci-chart> \
  --version <version> \
  -n midaz-plugins \
  --create-namespace \
  -f my-plugin-values.yaml

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.

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

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:

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

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.

Verificar tu despliegue

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

Revisa el estado de los pods

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

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:

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:

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:

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

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.

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

Desinstalar un plugin

Para quitar un plugin de tu clúster:

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

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.

Recursos relacionados

Desplegar Midaz con Helm – Guía de instalación inicial de Midaz Core
Guía de actualización con Helm – Procedimientos de actualización e instrucciones de rollback
Compatibilidad de versiones del chart de Midaz – Metadatos actuales del chart y de la aplicación de Midaz
Compatibilidad de versiones de plugins – Compatibilidad de los plugins con las versiones de Midaz Core
Nuestros plugins – Catálogo de plugins y cómo funcionan
Repositorio de Helm – Código fuente, charts y notas de release

Introducción

Midaz

Otros productos

Instalar y desplegar

Requisitos previos

Charts de plugins disponibles

Instalar un plugin

1. Revisa las versiones disponibles

2. Instala el chart

3. Verifica la instalación

Configura el chart elegido

Configurar el ingress

Verificar tu despliegue

Revisa el estado de los pods

Revisa los logs de los pods

Prueba el endpoint de health

Actualizar plugins

Desinstalar un plugin

Recursos relacionados

​Requisitos previos

​Charts de plugins disponibles

​Instalar un plugin

​1. Revisa las versiones disponibles

​2. Instala el chart

​3. Verifica la instalación

​Configura el chart elegido

​Configurar el ingress

​Verificar tu despliegue

​Revisa el estado de los pods

​Revisa los logs de los pods

​Prueba el endpoint de health

​Actualizar plugins

​Desinstalar un plugin

​Recursos relacionados

Requisitos previos

Charts de plugins disponibles

Instalar un plugin

1. Revisa las versiones disponibles

2. Instala el chart

3. Verifica la instalación

Configura el chart elegido

Configurar el ingress

Verificar tu despliegue

Revisa el estado de los pods

Revisa los logs de los pods

Prueba el endpoint de health

Actualizar plugins

Desinstalar un plugin

Recursos relacionados