Saltar al contenido principal

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.

El modo multi-tenant permite que Matcher sirva a múltiples clientes con aislamiento completo de datos. Cada inquilino opera en su propia base de datos, broker de mensajes y namespace de caché, asegurando que los datos de un inquilino nunca sean visibles para otro. Esto es esencial para despliegues SaaS, entornos regulados o cualquier escenario donde se requieran límites estrictos de datos entre clientes.

​
Descripción general

Por defecto, Matcher se ejecuta en modo single-tenant: todas las solicitudes comparten una base de datos y un conjunto de conexiones de infraestructura. Esta es la configuración más simple y funciona bien para despliegues de un solo cliente. Cuando se habilita el modo multi-tenant, cada inquilino recibe:
  • Base de datos aislada — una base de datos PostgreSQL dedicada provisionada y gestionada por el servicio Tenant Manager
  • Broker de mensajes aislado — un virtual host dedicado de RabbitMQ, más encabezados X-Tenant-ID en cada mensaje como defensa en profundidad
  • Caché aislado — todas las claves de Redis se prefijan automáticamente con el identificador del inquilino
  • Almacenamiento aislado — los objetos S3 se prefijan con el identificador del inquilino
La identidad del inquilino se determina a partir del token JWT en cada solicitud de API. El claim tenant_id en el token le indica a Matcher a qué inquilino pertenece la solicitud, y las conexiones de infraestructura correctas se resuelven automáticamente. El claim heredado tenantId también se acepta como alternativa para compatibilidad con versiones anteriores.

​
Cómo activar

​
Prerrequisitos

  • El servicio Tenant Manager debe estar en ejecución y accesible desde la red de Matcher. Puede verificar esto llamando a su endpoint /health.
  • Matcher debe estar configurado con autenticación habilitada (PLUGIN_AUTH_ENABLED=true), ya que la identidad del inquilino proviene del token JWT.

​
Configuración

Las configuraciones multi-tenant se establecen a través de variables de entorno, igual que otras configuraciones de Matcher. Dónde las defina depende de su método de despliegue:
  • Docker Compose: agréguelas a un archivo .env en la raíz del proyecto o directamente en docker-compose.yml en la sección environment
  • Kubernetes / Helm: agréguelas a su archivo de valores de Helm en la sección de entorno correspondiente
  • Standalone: defínalas en su entorno de shell o configuración del gestor de procesos
Consulte la Guía de instalación para detalles sobre dónde se ubican los archivos de entorno en su despliegue.

​
Variables requeridas

Agregue estas a su configuración de entorno para habilitar el modo multi-tenant: 
# Enable multi-tenant mode
MULTI_TENANT_ENABLED=true

# URL of the Tenant Manager service
MULTI_TENANT_URL=https://tenant-manager.example.com

# API key for authenticating with the Tenant Manager
MULTI_TENANT_SERVICE_API_KEY=your-api-key

​
Ajuste opcional

Puede ajustar tamaños de pool, tiempos de espera y comportamiento del circuit breaker: 
# Maximum number of concurrent tenant connection pools (default: 100)
MULTI_TENANT_MAX_TENANT_POOLS=200

# Seconds before an idle tenant pool is evicted (default: 300)
MULTI_TENANT_IDLE_TIMEOUT_SEC=600

# Consecutive Tenant Manager failures before circuit breaker opens (default: 5)
MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLD=3

# Seconds the circuit breaker stays open before retrying (default: 30)
MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SEC=60

# Environment label for environment-scoped tenant resolution (optional)
MULTI_TENANT_ENVIRONMENT=production
Después de actualizar la configuración, reinicie el servicio Matcher. Al iniciar, debería ver mensajes de log confirmando que la infraestructura multi-tenant fue inicializada.

​
Aislamiento de inquilinos

​
Aislamiento de base de datos

Cada inquilino obtiene su propia base de datos PostgreSQL. Cuando llega una solicitud, Matcher resuelve el inquilino desde el JWT y se conecta a la base de datos dedicada de ese inquilino. Si aún no existe un pool de conexiones para ese inquilino, se crea bajo demanda usando la configuración del Tenant Manager. Los pools de conexiones están limitados por MULTI_TENANT_MAX_TENANT_POOLS y se desalojan cuando están inactivos más allá de MULTI_TENANT_IDLE_TIMEOUT_SEC.

​
Aislamiento del broker de mensajes

El aislamiento de RabbitMQ utiliza dos capas:
  • Virtual host por inquilino — los mensajes de cada inquilino se enrutan a través de un vhost dedicado, previniendo cualquier filtración de mensajes entre inquilinos
  • Encabezados de Tenant ID — cada mensaje publicado incluye un encabezado X-Tenant-ID como capa de seguridad adicional para consumidores posteriores
No se necesita crear vhosts manualmente. El Tenant Manager provisiona los vhosts automáticamente.

​
Aislamiento de caché

Todas las claves de Redis se prefijan automáticamente con el identificador del inquilino en el formato tenant:{tenantID}:{key}. Esto aplica a verificaciones de idempotencia, deduplicación, limitación de tasa y almacenamiento en caché de credenciales.

​
Aislamiento de almacenamiento

Los objetos almacenados en almacenamiento compatible con S3 se prefijan con {tenantID}/, asegurando que las exportaciones y archivos de cada inquilino estén separados a nivel de almacenamiento.

​
Gestión de pools de conexiones

Matcher mantiene un pool de conexiones de base de datos para cada inquilino activo. Estas configuraciones controlan el uso de recursos:
VariablePor defectoDescripción
MULTI_TENANT_MAX_TENANT_POOLS100Número máximo de pools de inquilinos mantenidos simultáneamente. Cuando se alcanza el límite, el pool menos recientemente usado se desaloja.
MULTI_TENANT_IDLE_TIMEOUT_SEC300Cuánto tiempo (en segundos) un pool de inquilino inactivo permanece abierto antes de ser limpiado.

​
Planificación de capacidad

Cada pool de inquilino usa hasta POSTGRES_MAX_OPEN_CONNS conexiones (por defecto: 25). Con 100 pools de inquilinos, el peor caso total es 2,500 conexiones PostgreSQL. Dimensione el max_connections de su base de datos en consecuencia.

​
Verificaciones de salud automáticas

Matcher verifica periódicamente la configuración de inquilinos (cada MULTI_TENANT_CONNECTIONS_CHECK_INTERVAL_SEC, por defecto 30s) para detectar rotación de credenciales o cambios en la configuración del pool. Las configuraciones actualizadas se aplican sin requerir un reinicio.

​
Circuit breaker

Si el Tenant Manager se vuelve inaccesible, un circuit breaker protege a Matcher de fallos en cascada.
VariablePor defectoDescripción
MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLD5Cuántos fallos consecutivos antes de que el circuit breaker se active.
MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SEC30Cuánto tiempo el breaker permanece activo antes de permitir un reintento.
Mientras el circuit breaker está activo, las solicitudes para nuevos inquilinos fallarán rápidamente. Sin embargo, las conexiones existentes de inquilinos continúan funcionando normalmente — solo la incorporación de nuevos inquilinos se ve afectada.

​
Caché de configuración de inquilinos

Para reducir llamadas al Tenant Manager, Matcher almacena en caché las configuraciones de inquilinos en memoria.
VariablePor defectoDescripción
MULTI_TENANT_CACHE_TTL_SEC120Cuánto tiempo (en segundos) la configuración del inquilino se almacena en caché antes de actualizarse desde el Tenant Manager.
En la primera solicitud para un inquilino, Matcher obtiene la configuración de la API del Tenant Manager y la almacena en caché. Las solicitudes posteriores para el mismo inquilino se sirven desde caché hasta que el TTL expire.

​
Credenciales M2M (integración con Fetcher)

Cuando el modo multi-tenant está habilitado y Matcher necesita llamar al servicio Fetcher, se autentica usando credenciales machine-to-machine (M2M) por inquilino almacenadas en AWS Secrets Manager.

​
Cómo funciona

  1. Cuando Matcher llama a Fetcher en nombre de un inquilino, busca las credenciales de ese inquilino
  2. Las credenciales se almacenan en caché en dos niveles para rendimiento: en memoria (30 segundos) y Redis (TTL configurable)
  3. Si Fetcher devuelve un 401 Unauthorized, ambas cachés se limpian automáticamente y se obtienen credenciales frescas

​
Configuración

Agregue estas a su configuración de entorno si Matcher necesita llamar a Fetcher en modo multi-tenant: 
# AWS region where Secrets Manager stores the credentials
AWS_REGION=us-east-1

# Target service name (default: fetcher)
M2M_TARGET_SERVICE=fetcher

# How long credentials are cached in Redis, in seconds (default: 300)
M2M_CREDENTIAL_CACHE_TTL_SEC=300
El rol IAM del servicio necesita el permiso secretsmanager:GetSecretValue para la ruta tenants/{env}/{tenantOrgID}/matcher/m2m/fetcher/credentials.

​
Todas las variables de entorno

​
Infraestructura multi-tenant

VariableTipoPor defectoRequeridaDescripción
MULTI_TENANT_ENABLEDboolfalseNoInterruptor principal para el modo multi-tenant.
MULTI_TENANT_URLstring—Sí (cuando está habilitado)URL base del servicio Tenant Manager.
MULTI_TENANT_SERVICE_API_KEYstring—Sí (cuando está habilitado)Clave API para autenticarse con el Tenant Manager.
MULTI_TENANT_ENVIRONMENTstring—NoEtiqueta de entorno para resolución de inquilinos.
MULTI_TENANT_MAX_TENANT_POOLSint100NoPools de conexiones de inquilinos concurrentes máximos.
MULTI_TENANT_IDLE_TIMEOUT_SECint300NoSegundos antes de que un pool de inquilino inactivo sea desalojado.
MULTI_TENANT_TIMEOUTint30NoTiempo de espera HTTP (segundos) para llamadas a la API del Tenant Manager.
MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLDint5NoFallos consecutivos antes de que el circuit breaker se active.
MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SECint30NoSegundos que el circuit breaker permanece activo.
MULTI_TENANT_CACHE_TTL_SECint120NoTTL de caché (segundos) para configuraciones de inquilinos.
MULTI_TENANT_CONNECTIONS_CHECK_INTERVAL_SECint30NoIntervalo (segundos) para verificaciones de salud del pool de conexiones.
MULTI_TENANT_REDIS_HOSTstring—NoHost de Redis para descubrimiento de inquilinos basado en eventos.
MULTI_TENANT_REDIS_PORTstring6379NoPuerto de Redis para descubrimiento de inquilinos.
MULTI_TENANT_REDIS_PASSWORDstring—NoContraseña de Redis para descubrimiento de inquilinos.
MULTI_TENANT_REDIS_TLSboolfalseNoHabilitar TLS para Redis de descubrimiento de inquilinos.

​
Inquilino por defecto

VariableTipoPor defectoDescripción
DEFAULT_TENANT_IDstring11111111-1111-1111-1111-111111111111UUID del inquilino por defecto (fallback). Usado en modo single-tenant.
DEFAULT_TENANT_SLUGstringdefaultSlug del inquilino por defecto.

​
Credenciales M2M (Fetcher)

VariableTipoPor defectoRequeridaDescripción
M2M_TARGET_SERVICEstringfetcherNoNombre del servicio de destino para búsqueda de credenciales.
M2M_CREDENTIAL_CACHE_TTL_SECint300NoTTL de caché en Redis (segundos) para credenciales M2M.
AWS_REGIONstring—Sí (si M2M)Región de AWS para Secrets Manager.

​
Verificar el modo multi-tenant

Después de activar el modo multi-tenant, verifique que todo esté funcionando:
  1. Revise los logs de inicio. Busque mensajes que confirmen que la infraestructura multi-tenant se inicializó correctamente.
  2. Pruebe con un JWT de inquilino. Envíe una solicitud de API (por ejemplo, listar contextos) usando un JWT que contenga un claim tenant_id. La solicitud debería ser exitosa y devolver datos para ese inquilino específico.
  3. Verifique el aislamiento. Realice la misma llamada de API con JWTs para dos inquilinos diferentes. Confirme que los datos creados bajo un inquilino no son visibles para el otro.
  4. Revise las métricas (si la telemetría está habilitada). La métrica tenant_connections_total debería incrementarse a medida que se crean nuevos pools de inquilinos.
  5. Verifique las credenciales M2M (si usa Fetcher). Revise los logs para verificar la obtención exitosa de credenciales cuando Matcher llama a Fetcher para un inquilino.

​
Desactivar el modo multi-tenant

Para volver al modo single-tenant:
  1. Establezca MULTI_TENANT_ENABLED=false en su configuración de entorno (o elimine la variable completamente).
  2. Reinicie el servicio Matcher.
El servicio operará con una sola base de datos compartida y la identidad del inquilino por defecto se aplicará a todas las solicitudes.

​
Consideraciones de despliegue

Al cambiar de modo single-tenant a multi-tenant, las claves de Redis cambian de formato. Las claves con formato antiguo se tratan como cache misses hasta que expire su TTL. Esto se auto-repara y típicamente se resuelve en 1–5 minutos.
Los objetos existentes creados antes de la activación multi-tenant permanecen en sus rutas originales. Los nuevos objetos obtienen el prefijo de inquilino automáticamente. Si los datos históricos deben ser accesibles por inquilino, puede ser necesario un script de migración único.
Planifique el max_connections de PostgreSQL basándose en el número máximo de pools de inquilinos multiplicado por las conexiones por pool. Use MULTI_TENANT_IDLE_TIMEOUT_SEC para reclamar pools de inquilinos inactivos.
Mientras el circuit breaker está activo, las solicitudes de nuevos inquilinos fallan rápidamente pero los pools de inquilinos existentes continúan funcionando. Planifique alta disponibilidad del Tenant Manager en producción.

​
Próximos pasos

Configuración en tiempo de ejecución

Cambie la configuración de Matcher en tiempo de ejecución sin reinicios.

Guía de instalación

Configure Matcher desde cero.

Seguridad

Autenticación, autorización y protección de datos.

Discovery (Fetcher)

Descubrimiento automático de fuentes a través de Fetcher.