Pular para o conteúdo 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.

O modo multi-tenant permite que o Matcher atenda múltiplos clientes com isolamento completo de dados. Cada tenant opera em seu próprio banco de dados, message broker e namespace de cache — garantindo que os dados de um tenant nunca sejam visíveis para outro. Isso é essencial para deployments SaaS, ambientes regulados ou qualquer cenário onde limites rígidos de dados entre clientes sejam necessários.

​
Visão geral

Por padrão, o Matcher roda em modo single-tenant: todas as requisições compartilham um banco de dados e um conjunto de conexões de infraestrutura. Essa é a configuração mais simples e funciona bem para deployments de um único cliente. Quando o modo multi-tenant é habilitado, cada tenant recebe:
  • Banco de dados isolado — um banco de dados PostgreSQL dedicado provisionado e gerenciado pelo serviço Tenant Manager
  • Message broker isolado — um virtual host RabbitMQ dedicado, além de headers X-Tenant-ID em cada mensagem como defesa em profundidade
  • Cache isolado — todas as chaves Redis são automaticamente prefixadas com o identificador do tenant
  • Storage isolado — objetos S3 são prefixados com o identificador do tenant
A identidade do tenant é determinada a partir do token JWT em cada requisição de API. A claim tenant_id no token indica ao Matcher a qual tenant a requisição pertence, e as conexões de infraestrutura corretas são resolvidas automaticamente. A claim legada tenantId também é aceita como fallback para compatibilidade com versões anteriores.

​
Como ativar

​
Pré-requisitos

  • O serviço Tenant Manager deve estar em execução e acessível a partir da rede do Matcher. Você pode verificar isso chamando seu endpoint /health.
  • O Matcher deve estar configurado com autenticação habilitada (PLUGIN_AUTH_ENABLED=true), já que a identidade do tenant vem do token JWT.

​
Configuração

As configurações multi-tenant são definidas através de variáveis de ambiente, assim como outras configurações do Matcher. Onde você as define depende do seu método de deployment:
  • Docker Compose: adicione-as a um arquivo .env na raiz do projeto ou diretamente no docker-compose.yml na seção environment
  • Kubernetes / Helm: adicione-as ao seu arquivo de valores Helm na seção de ambiente apropriada
  • Standalone: defina-as no ambiente do seu shell ou na configuração do gerenciador de processos
Consulte o Guia de instalação para detalhes sobre onde os arquivos de ambiente estão localizados no seu deployment.

​
Variáveis obrigatórias

Adicione estas à sua configuração de ambiente para habilitar o modo multi-tenant: 
# Habilitar modo multi-tenant
MULTI_TENANT_ENABLED=true

# URL do serviço Tenant Manager
MULTI_TENANT_URL=https://tenant-manager.example.com

# Chave de API para autenticação com o Tenant Manager
MULTI_TENANT_SERVICE_API_KEY=your-api-key

​
Ajustes opcionais

Você pode ajustar tamanhos de pool, timeouts e comportamento do circuit breaker: 
# Número máximo de pools de conexão de tenants simultâneos (padrão: 100)
MULTI_TENANT_MAX_TENANT_POOLS=200

# Segundos antes de um pool de tenant ocioso ser removido (padrão: 300)
MULTI_TENANT_IDLE_TIMEOUT_SEC=600

# Falhas consecutivas do Tenant Manager antes do circuit breaker abrir (padrão: 5)
MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLD=3

# Segundos que o circuit breaker permanece aberto antes de tentar novamente (padrão: 30)
MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SEC=60

# Label de ambiente para resolução de tenant com escopo de ambiente (opcional)
MULTI_TENANT_ENVIRONMENT=production
Após atualizar a configuração, reinicie o serviço Matcher. Na inicialização, você deve ver mensagens de log confirmando que a infraestrutura multi-tenant foi inicializada.

​
Isolamento de tenants

​
Isolamento de banco de dados

Cada tenant recebe seu próprio banco de dados PostgreSQL. Quando uma requisição chega, o Matcher resolve o tenant a partir do JWT e conecta ao banco de dados dedicado daquele tenant. Se ainda não existir um pool de conexões para aquele tenant, um é criado sob demanda usando configuração do Tenant Manager. Os pools de conexão são limitados por MULTI_TENANT_MAX_TENANT_POOLS e removidos quando ociosos além de MULTI_TENANT_IDLE_TIMEOUT_SEC.

​
Isolamento do message broker

O isolamento do RabbitMQ usa duas camadas:
  • Virtual host por tenant — as mensagens de cada tenant são roteadas através de um vhost dedicado, prevenindo qualquer vazamento de mensagens entre tenants
  • Headers de tenant ID — cada mensagem publicada inclui um header X-Tenant-ID como uma camada adicional de segurança para consumidores downstream
Não é necessário criar vhosts manualmente. O Tenant Manager provisiona vhosts automaticamente.

​
Isolamento de cache

Todas as chaves Redis são automaticamente prefixadas com o identificador do tenant no formato tenant:{tenantID}:{key}. Isso se aplica a verificações de idempotência, deduplicação, rate limiting e cache de credenciais.

​
Isolamento de storage

Objetos armazenados em storage compatível com S3 são prefixados com {tenantID}/, garantindo que exportações e arquivos de cada tenant sejam separados no nível de armazenamento.

​
Gerenciamento de pools de conexão

O Matcher mantém um pool de conexões de banco de dados para cada tenant ativo. Estas configurações controlam o uso de recursos:
VariávelPadrãoDescrição
MULTI_TENANT_MAX_TENANT_POOLS100Número máximo de pools de tenants mantidos simultaneamente. Quando o limite é atingido, o pool menos recentemente utilizado é removido.
MULTI_TENANT_IDLE_TIMEOUT_SEC300Quanto tempo (em segundos) um pool de tenant não utilizado permanece aberto antes de ser limpo.

​
Planejamento de capacidade

Cada pool de tenant usa até POSTGRES_MAX_OPEN_CONNS conexões (padrão: 25). Com 100 pools de tenants, o total no pior caso é 2.500 conexões PostgreSQL. Dimensione o max_connections do seu banco de dados adequadamente.

​
Verificações de saúde automáticas

O Matcher periodicamente re-verifica a configuração dos tenants (a cada MULTI_TENANT_CONNECTIONS_CHECK_INTERVAL_SEC, padrão 30s) para detectar rotação de credenciais ou mudanças nas configurações do pool. Configurações atualizadas são aplicadas sem necessidade de reinicialização.

​
Circuit breaker

Se o Tenant Manager se tornar inacessível, um circuit breaker protege o Matcher de falhas em cascata.
VariávelPadrãoDescrição
MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLD5Quantas falhas consecutivas antes do circuit breaker ativar.
MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SEC30Quanto tempo o breaker permanece ativo antes de permitir uma nova tentativa.
Enquanto o circuit breaker está ativo, requisições para novos tenants falharão rapidamente. No entanto, conexões existentes de tenants continuam funcionando normalmente — apenas o onboarding de novos tenants é afetado.

​
Cache de configuração de tenants

Para reduzir chamadas ao Tenant Manager, o Matcher armazena em cache as configurações dos tenants em memória.
VariávelPadrãoDescrição
MULTI_TENANT_CACHE_TTL_SEC120Quanto tempo (em segundos) a configuração do tenant é cacheada antes de ser atualizada a partir do Tenant Manager.
Na primeira requisição para um tenant, o Matcher busca a configuração na API do Tenant Manager e a armazena em cache. Requisições subsequentes para o mesmo tenant são servidas a partir do cache até o TTL expirar.

​
Credenciais M2M (integração com Fetcher)

Quando o modo multi-tenant está habilitado e o Matcher precisa chamar o serviço Fetcher, ele se autentica usando credenciais machine-to-machine (M2M) por tenant armazenadas no AWS Secrets Manager.

​
Como funciona

  1. Quando o Matcher chama o Fetcher em nome de um tenant, ele busca as credenciais daquele tenant
  2. As credenciais são cacheadas em dois níveis para performance: em memória (30 segundos) e Redis (TTL configurável)
  3. Se o Fetcher retornar um 401 Unauthorized, ambos os caches são automaticamente limpos e novas credenciais são buscadas

​
Configuração

Adicione estas à sua configuração de ambiente se o Matcher precisar chamar o Fetcher em modo multi-tenant: 
# Região AWS onde o Secrets Manager armazena as credenciais
AWS_REGION=us-east-1

# Nome do serviço de destino (padrão: fetcher)
M2M_TARGET_SERVICE=fetcher

# Quanto tempo as credenciais são cacheadas no Redis, em segundos (padrão: 300)
M2M_CREDENTIAL_CACHE_TTL_SEC=300
A IAM role do serviço precisa da permissão secretsmanager:GetSecretValue para o caminho tenants/{env}/{tenantOrgID}/matcher/m2m/fetcher/credentials.

​
Todas as variáveis de ambiente

​
Infraestrutura multi-tenant

VariávelTipoPadrãoObrigatórioDescrição
MULTI_TENANT_ENABLEDboolfalseNãoChave mestra para o modo multi-tenant.
MULTI_TENANT_URLstring—Sim (quando habilitado)URL base do serviço Tenant Manager.
MULTI_TENANT_SERVICE_API_KEYstring—Sim (quando habilitado)Chave de API para autenticação com o Tenant Manager.
MULTI_TENANT_ENVIRONMENTstring—NãoLabel de ambiente para resolução de tenant.
MULTI_TENANT_MAX_TENANT_POOLSint100NãoMáximo de pools de conexão de tenants simultâneos.
MULTI_TENANT_IDLE_TIMEOUT_SECint300NãoSegundos antes de um pool de tenant ocioso ser removido.
MULTI_TENANT_TIMEOUTint30NãoTimeout HTTP (segundos) para chamadas à API do Tenant Manager.
MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLDint5NãoFalhas consecutivas antes do circuit breaker ativar.
MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SECint30NãoSegundos que o circuit breaker permanece ativo.
MULTI_TENANT_CACHE_TTL_SECint120NãoTTL do cache (segundos) para configurações de tenants.
MULTI_TENANT_CONNECTIONS_CHECK_INTERVAL_SECint30NãoIntervalo (segundos) para verificações de saúde dos pools de conexão.
MULTI_TENANT_REDIS_HOSTstring—NãoHost Redis para descoberta de tenant orientada a eventos.
MULTI_TENANT_REDIS_PORTstring6379NãoPorta Redis para descoberta de tenant.
MULTI_TENANT_REDIS_PASSWORDstring—NãoSenha Redis para descoberta de tenant.
MULTI_TENANT_REDIS_TLSboolfalseNãoHabilitar TLS para Redis de descoberta de tenant.

​
Tenant padrão

VariávelTipoPadrãoDescrição
DEFAULT_TENANT_IDstring11111111-1111-1111-1111-111111111111UUID do tenant padrão (fallback). Usado no modo single-tenant.
DEFAULT_TENANT_SLUGstringdefaultSlug do tenant padrão.

​
Credenciais M2M (Fetcher)

VariávelTipoPadrãoObrigatórioDescrição
M2M_TARGET_SERVICEstringfetcherNãoNome do serviço de destino para busca de credenciais.
M2M_CREDENTIAL_CACHE_TTL_SECint300NãoTTL do cache Redis (segundos) para credenciais M2M.
AWS_REGIONstring—Sim (se M2M)Região AWS para Secrets Manager.

​
Verificando o modo multi-tenant

Após ativar o modo multi-tenant, verifique se tudo está funcionando:
  1. Verifique os logs de inicialização. Procure por mensagens confirmando que a infraestrutura multi-tenant foi inicializada com sucesso.
  2. Teste com um JWT de tenant. Envie uma requisição de API (por exemplo, listar contextos) usando um JWT que contenha uma claim tenant_id. A requisição deve ter sucesso e retornar dados para aquele tenant específico.
  3. Verifique o isolamento. Faça a mesma chamada de API com JWTs para dois tenants diferentes. Confirme que dados criados sob um tenant não são visíveis para o outro.
  4. Verifique métricas (se telemetria estiver habilitada). A métrica tenant_connections_total deve incrementar conforme novos pools de tenants são criados.
  5. Verifique credenciais M2M (se usando Fetcher). Verifique os logs para busca bem-sucedida de credenciais quando o Matcher chama o Fetcher para um tenant.

​
Desativando o modo multi-tenant

Para retornar ao modo single-tenant:
  1. Defina MULTI_TENANT_ENABLED=false na sua configuração de ambiente (ou remova a variável completamente).
  2. Reinicie o serviço Matcher.
O serviço operará com um único banco de dados compartilhado e a identidade do tenant padrão será aplicada a todas as requisições.

​
Considerações de deployment

Ao mudar do modo single-tenant para multi-tenant, as chaves Redis mudam de formato. Chaves no formato antigo são tratadas como cache misses até que seu TTL expire. Isso é auto-corrigível e tipicamente se resolve em 1-5 minutos.
Objetos existentes criados antes da ativação multi-tenant permanecem em seus caminhos originais. Novos objetos recebem o prefixo do tenant automaticamente. Se dados históricos devem ser acessíveis por tenant, um script de migração único pode ser necessário.
Planeje o max_connections do seu PostgreSQL baseado no número máximo de pools de tenants multiplicado por conexões por pool. Use MULTI_TENANT_IDLE_TIMEOUT_SEC para recuperar pools de tenants inativos.
Enquanto o circuit breaker está ativo, requisições de novos tenants falham rapidamente, mas pools de tenants existentes continuam funcionando. Planeje alta disponibilidade do Tenant Manager em produção.

​
Próximos passos

Configuração em tempo de execução

Altere configurações do Matcher em runtime sem reinicializações.

Guia de instalação

Configure o Matcher do zero.

Segurança

Autenticação, autorização e proteção de dados.

Discovery (Fetcher)

Descoberta automática de sources através do Fetcher.