> ## 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.
# Configuración multi-tenant
> Configura Matcher para autenticación consciente de tenants y pools PostgreSQL específicos por tenant.
En las solicitudes multi-tenant compatibles, Matcher primero deriva el contexto de tenant del JWT autorizado y después lo usa para resolver la infraestructura PostgreSQL específica del tenant mediante Tenant Manager. Es un modo de despliegue, no un interruptor de runtime: valídalo en un entorno no productivo antes de habilitarlo en una instalación compartida.
## Requisitos
***
Antes de habilitar el modo multi-tenant:
* Define `MULTI_TENANT_ENABLED=true` y `PLUGIN_AUTH_ENABLED=true`. Matcher rechaza el arranque multi-tenant sin aplicación de autorización.
* Usa `AUTH_PROVIDER=plugin-auth`. El proveedor actual `workos` resuelve las solicitudes verificadas en el tenant predeterminado y no es compatible con la selección de tenant.
* Define `MULTI_TENANT_URL` como una URL HTTPS de solo origen en staging y producción, además de un `MULTI_TENANT_SERVICE_API_KEY` no vacío. `MULTI_TENANT_ENVIRONMENT` es opcional y usa `ENV_NAME` como fallback si no se define. El protocolo `http` sin cifrar se permite en desarrollo local; en otros entornos también requiere que definas explícitamente `MULTI_TENANT_ALLOW_INSECURE_HTTP=true`.
* Define `ENVIRONMENT_NAME` (o `ENV_NAME`) como `staging` o `production`.
* Incluye un claim válido `tenant_id` o `tenantId` en solicitudes autenticadas mediante `plugin-auth`.
* Mantén disponible la base de datos del tenant predeterminado en el pool raíz para cargas del tenant predeterminado y herramientas operativas.
Matcher resuelve pools PostgreSQL dedicados para tenants que no son el predeterminado; el tenant predeterminado usa el pool raíz. No cambia esquemas de tenant mediante `SET search_path` de PostgreSQL; las credenciales específicas de tenant, los límites de red y la configuración de Tenant Manager siguen siendo parte del límite de aislamiento.
## Identidad del tenant
***
Con `AUTH_PROVIDER=plugin-auth` en modo multi-tenant, Matcher deriva la identidad del tenant de un claim JWT válido `tenant_id` o `tenantId`. No acepta un selector de tenant controlado por quien llama desde cuerpos de solicitud, parámetros de consulta o headers arbitrarios. Los despliegues con `workos`, single-tenant o autenticación deshabilitada usan el tenant predeterminado configurado.
## Controles de connection pool
***
| Control | Alcance | Efecto |
| ---------------------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MULTI_TENANT_MAX_OPEN_CONNS_PER_TENANT` | Entorno de bootstrap | Valor predeterminado y límite máximo de conexiones PostgreSQL abiertas por tenant. Su valor predeterminado es `0`; cuando ambas variables de límites de conexión tienen `0`, lib-commons usa valores predeterminados de 25 abiertas / 5 inactivas y límites de 200 abiertas / 50 inactivas. Es independiente de la configuración `POSTGRES_MAX_*` del pool raíz. Cámbialo mediante la configuración del despliegue y reinicia Matcher. |
| `MULTI_TENANT_MAX_IDLE_CONNS_PER_TENANT` | Entorno de bootstrap | Configuración complementaria de conexiones inactivas, con el mismo valor predeterminado y límite máximo; comparte el comportamiento de fallback con `0` indicado arriba. Cámbialo mediante la configuración del despliegue y reinicia Matcher. |
| `MULTI_TENANT_MAX_TENANT_POOLS` | Configuración de runtime de Systemplane | Máximo número de pools de tenants que Matcher puede mantener abiertos; el valor predeterminado es `100` y debe ser positivo. |
| `MULTI_TENANT_IDLE_TIMEOUT_SEC` | Configuración de runtime de Systemplane | Timeout de pool inactivo usado por el administrador de pools de tenants; el valor predeterminado es `300` segundos y debe ser positivo. El nuevo valor se aplica mediante Systemplane sin reinicio. |
Con los límites configurados, el administrador de pools de tenants de Matcher expulsa un pool inactivo usado menos recientemente cuando resolver un tenant nuevo superaría `MULTI_TENANT_MAX_TENANT_POOLS`; el tenant expulsado se vuelve a resolver bajo demanda. Valida el comportamiento de migración y fallos con la integración de Tenant Manager desplegada.
## Infraestructura compartida
***
Matcher delega la resolución de infraestructura consciente de tenants al servicio de plataforma multi-tenancy. No supongas un nombre fijo de virtual host de RabbitMQ, una convención de headers de mensajes, formato de claves Redis, TTL de caché o prefijo S3 a partir de Matcher únicamente. Esas convenciones son específicas del componente y del despliegue; revisa la documentación de infraestructura y plataforma correspondiente antes de crear una integración.
## Habilitar el modo
***
1. Aprovisiona y verifica el tenant predeterminado y los tenants que Matcher debe atender.
2. Configura el proveedor de autenticación, Tenant Manager, conectividad PostgreSQL y las variables de entorno de bootstrap.
3. Inicia Matcher y confirma los health checks y una solicitud autenticada con alcance de tenant.
4. Observa el número de pools de tenants y el uso de conexiones de base de datos bajo la carga esperada.
5. Despliega solo después de probar el aislamiento y el comportamiento ante fallos en el entorno objetivo.
Cambiar la topología de tenants, las credenciales de base de datos o los límites de conexiones PostgreSQL por pool es un cambio de infraestructura. Aplícalo mediante el proceso de despliegue; Systemplane no puede cambiar esos valores de bootstrap sin reiniciar.
## Próximos pasos
***
Revisa los valores que Matcher puede cambiar mediante Systemplane.
Revisa autenticación, aislamiento de tenants y controles TLS de dependencias.