> ## 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 del tenant y pools de PostgreSQL específicos por tenant.
Para las solicitudes multi-tenant admitidas, Matcher primero deriva el contexto del tenant desde el JWT autorizado y luego lo usa para resolver la infraestructura de PostgreSQL específica del tenant mediante Tenant Manager. Es un modo de despliegue, no un toggle en tiempo de ejecución: valídalo en un entorno que no sea de producción antes de habilitarlo para 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 la autorización.
* Usa `AUTH_PROVIDER=plugin-auth`.
* Define `MULTI_TENANT_URL` con una URL HTTPS de solo origen en staging y producción, más un `MULTI_TENANT_SERVICE_API_KEY` no vacío. `MULTI_TENANT_ENVIRONMENT` es opcional y recurre a `ENV_NAME` cuando no se define. Se permite `http` en texto plano para el desarrollo local. En otros entornos también requiere un `MULTI_TENANT_ALLOW_INSECURE_HTTP=true` explícito.
* Define `ENVIRONMENT_NAME` (o `ENV_NAME`) como `staging` o `production`.
* Entrega un claim `tenant_id` o `tenantId` válido en las solicitudes autenticadas mediante `plugin-auth`.
* Mantén la base de datos del tenant predeterminado disponible en el pool raíz para las cargas de trabajo del tenant predeterminado y las herramientas operativas.
Matcher resuelve pools de PostgreSQL dedicados para los tenants que no son el predeterminado. El tenant predeterminado usa el pool raíz. No cambia de esquema de tenant mediante `SET search_path` de PostgreSQL. Las credenciales específicas del 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 `tenant_id` o `tenantId` válido. No acepta un selector de tenant controlado por el llamador desde el cuerpo de la solicitud, los parámetros de consulta ni headers arbitrarios. Los despliegues de un solo tenant y los que tienen la autenticación deshabilitada usan el tenant predeterminado configurado.
## Controles del pool de conexiones
***
| Control | Alcance | Efecto |
| ---------------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MULTI_TENANT_MAX_OPEN_CONNS_PER_TENANT` | Entorno de bootstrap | Valor predeterminado y techo duro de conexiones abiertas de PostgreSQL por tenant. De forma predeterminada es `0`; cuando ambas variables de límite de conexiones son `0`, lib-commons usa valores predeterminados de 25 abiertas / 5 inactivas y techos de 200 abiertas / 50 inactivas. Es independiente de los ajustes `POSTGRES_MAX_*` del pool raíz. Cámbialo mediante la configuración de despliegue y reinicia Matcher. |
| `MULTI_TENANT_MAX_IDLE_CONNS_PER_TENANT` | Entorno de bootstrap | Valor predeterminado y techo duro complementario de conexiones inactivas; comparte el comportamiento de respaldo de `0` de arriba. Cámbialo mediante la configuración de despliegue y reinicia Matcher. |
| `MULTI_TENANT_MAX_TENANT_POOLS` | Configuración en tiempo de ejecución de Systemplane | Cantidad máxima de pools de tenant que Matcher puede mantener abiertos; el valor predeterminado es `100` y el valor debe ser positivo. |
| `MULTI_TENANT_IDLE_TIMEOUT_SEC` | Configuración en tiempo de ejecución de Systemplane | Timeout de pool inactivo que usa el gestor de pools de tenant; el valor predeterminado es `300` segundos y el valor debe ser positivo. El nuevo valor se aplica mediante Systemplane sin reiniciar. |
En los límites configurados, el gestor de pools de tenant 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 de falla contra la integración de Tenant Manager desplegada.
## Infraestructura compartida
***
Matcher delega la resolución de infraestructura consciente del tenant al servicio de plataforma de multi-tenancy. No supongas un nombre fijo de virtual host de RabbitMQ, una convención de headers de mensaje, un formato de claves de Redis, un TTL de cache ni un prefijo de S3 solo a partir de Matcher. Esas convenciones son específicas del componente y del despliegue. Revisa la documentación de infraestructura y de plataforma correspondiente antes de construir una integración alrededor de ellas.
## Habilitar el modo
***
1. Aprovisiona y verifica el tenant predeterminado y los tenants que Matcher debe servir.
2. Configura el proveedor de autenticación, Tenant Manager, la conectividad con PostgreSQL y las variables de entorno de bootstrap.
3. Arranca Matcher y confirma los health checks y una solicitud autenticada con alcance de tenant.
4. Observa el conteo de pools de tenant y el uso de conexiones de base de datos bajo la carga esperada.
5. Haz el despliegue solo después de que el comportamiento de aislamiento y de falla se haya ejercitado en el entorno objetivo.
Cambiar la topología de tenants, las credenciales de base de datos o los límites de conexión de 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 los controles de autenticación, de aislamiento de tenants y de TLS de dependencias.