Tenant Isolation

Status: Ineffective: the resource is reconciled, but the pinned Proxy does not execute the router phase. Edits also require owning-NexoProxy reconciliation.

:::caution No supported deployment contract

This capability is documented for catalog completeness, but the selected release does not publish a supported end-to-end deployment contract.

:::

This page belongs to the immutable 0.2.0 Private Preview documentation.

At a glance

Property	Value
Pipeline phase	Router
Category	Routing
Canonical minimum tier	Business
Legacy dashboard tier label	Business
Legacy rendered name	Tenant Isolation
Legacy rendered summary	Multi-tenant enforcement at the proxy layer with Free, Pro, and Enterprise controls for identification, quotas, routing, residency, and breach response.
Canonical entitlement	Yes
Supported deployment contract	No
Release status	Ineffective: the resource is reconciled, but the pinned Proxy does not execute the router phase. Edits also require owning-NexoProxy reconciliation.

Release accuracy

• 0.2.0 Private Preview: Ineffective: the resource is reconciled, but the pinned Proxy does not execute the router phase. Edits also require owning-NexoProxy reconciliation.

The detailed material below preserves every section rendered by the legacy dashboard. Where it conflicts with the release status above, the release status is authoritative. Legacy field names and examples are not a substitute for the selected bundle's CRD and runtime contract. Unsafe legacy wording is retained in metadata for traceability but is corrected in the rendered guidance.

Release-aware feature flow. The diagram is explanatory; the release status on this page is authoritative.

Diagram resources: Open the SVG full screen · Download the editable Excalidraw source

Performance impact

:::warning Legacy, unverified performance claims

These numbers are preserved for documentation parity with the legacy dashboard. They are not current benchmarks or service guarantees and have not been verified by the current test suite.

:::

Percentile	Legacy claim
P50	0.10ms
P95	0.28ms
P99	0.55ms

Legacy note: Identity lookup and local policy evaluation are in-memory. Enterprise routing, residency checks, and quotas add modest overhead but remain sub-millisecond on typical configs.

Overview

The Tenant Isolation step establishes a hard tenant boundary before MongoDB ever sees the request. Nexo identifies the tenant, verifies that the request belongs to that tenant, enforces per-tenant quotas and policy lists, and can then route the request to a tenant-specific backend or region.

The feature is intentionally tiered:

• Free: field-path or header extraction, fail-closed handling for missing tenant context, and basic violation logging.
• Pro: JWT/connection-metadata extraction, audit-or-block cross-tenant detection, per-tenant quotas, allow/deny controls, and tenant-level audit evidence.
• Enterprise: premium routing rules, region-aware data residency, dedicated pools per tenant, real-time breach alerting, and the foundations needed for tenant chargeback and performance isolation.

Use it when you operate a shared MongoDB proxy tier for many customers and need stronger guarantees than application code alone can provide.

When to use

• Enforcing a single tenant context on every query before it reaches MongoDB
• Giving premium tenants dedicated backends, regions, or warm connection pools
• Protecting shared proxy capacity with per-tenant request and connection quotas
• Blocking or auditing cross-tenant access attempts for compliance programs
• Keeping tenant traffic inside approved regions for sovereignty or residency requirements

How it works

1. Identification: the proxy extracts tenant identity from a field path, request header, JWT claim, or connection metadata.
2. Admission control: unidentified requests are rejected, warned, or routed to a default backend based on policy. Allowlist/denylist checks run before forwarding.
3. Isolation enforcement: Pro cross-tenant inspection can run in strict mode (hard block) or audit mode (log and continue). Per-tenant quotas throttle noisy tenants before they affect neighbors.
4. Routing & placement: Enterprise rules map tenant ids or patterns to backend targets, regions, and dedicated pools so premium or regulated tenants can be isolated from the shared fleet.
5. Breach handling: violations are logged, optionally emitted to an audit trail, and can trigger enterprise alerting hooks for real-time response.

Configuration

The table preserves the legacy dashboard field reference. “Not specified” means the legacy source did not declare required semantics.

Field	Legacy UI type	Legacy default	Required	Description
identificationStrategy	select	header	Yes	How the tenant is identified: field, header, jwt, or connection
fieldPath	string	tenantId	No	MongoDB field path used when identificationStrategy is field
headerName	string	X-Tenant-ID	No	HTTP or proxy header used when identificationStrategy is header
jwtClaimPath	string	claims.tenant_id	No	Dot-path into verified JWT/OIDC claims when identificationStrategy is jwt
connectionMetadataKey	string	auth.user	No	Connection metadata key used when identificationStrategy is connection
unidentifiedRequestBehavior	select	reject	No	What to do when tenant context is missing: reject, allow_warning, or route_default
rejectUnidentified	bool	true	No	Boolean fail-closed switch for environments that always reject missing tenant context
logViolations	bool	true	No	Emit isolation violations to logs / audit pipelines
crossTenantBlocking	select	strict	No	Cross-tenant enforcement mode: strict, audit, or disabled
perTenantRateLimit	object	{"requestsPerSecond":250,"maxConnections":100}	No	{ requestsPerSecond, maxConnections } tenant quota object (Pro)
allowlist	string[]	—	No	Explicit list of tenant ids or patterns allowed to execute through the proxy (Pro)
denylist	string[]	—	No	Tenant ids or patterns denied immediately (Pro)
tenantRouting	object[]	—	No	Array of { tenantId, target } mappings for enterprise tenant-aware routing
defaultTarget	string	—	No	Fallback backend used when unidentifiedRequestBehavior is route_default
dedicatedPools	object	{"enabled":false,"poolSize":25}	No	{ enabled, poolSize } to reserve warm connections per tenant (Enterprise)
dataResidency	object[]	—	No	Array of { tenantPattern, allowedRegions[] } rules for residency enforcement (Enterprise)
breachAlerting	object	—	No	{ enabled, webhookUrl } real-time isolation alerting configuration (Enterprise)

Settings reference

The legacy page did not render an additional anchored settings reference.

Examples

Free tier: header-based fail-closed isolation

router:
  name: builtin:tenant-isolation
  config:
    identificationStrategy: header
    headerName: X-Tenant-ID
    unidentifiedRequestBehavior: reject
    rejectUnidentified: true
    logViolations: true

Pro tier: JWT-based isolation with quotas and audit-only cross-tenant detection

router:
  name: builtin:tenant-isolation
  config:
    identificationStrategy: jwt
    jwtClaimPath: claims.tenant_id
    crossTenantBlocking: audit
    perTenantRateLimit:
      requestsPerSecond: 500
      maxConnections: 150
    allowlist: [acme, globex, premium-*]
    denylist: [suspended-*]
    logViolations: true

Enterprise tier: premium routing, residency, dedicated pools, and alerts

router:
  name: builtin:tenant-isolation
  config:
    identificationStrategy: connection
    connectionMetadataKey: auth.user
    unidentifiedRequestBehavior: route_default
    defaultTarget: shared-mongo.internal:27017
    tenantRouting:
      - tenantId: acme-enterprise
        target: mongo-acme-us.internal:27017
      - tenantId: globex-eu
        target: mongo-globex-eu.internal:27017
    dedicatedPools:
      enabled: true
      poolSize: 40
    dataResidency:
      - tenantPattern: globex-*
        allowedRegions: [westeurope, northeurope]
    breachAlerting:
      enabled: true
      webhookUrl: https://hooks.example.net/tenant-isolation

Best practices

• Fail closed (unidentifiedRequestBehavior: reject) unless you have a well-defined shared fallback backend.
• Prefer header or JWT extraction for deterministic identity; use field-path extraction only when tenant identity truly lives inside the query payload.
• Use audit mode first for cross-tenant detection to learn your workload, then switch to strict mode once false positives are understood.
• Pair dedicated pools with per-tenant quotas so premium isolation does not become an unbounded cost center.
• Treat denylist, residency, and breach alerting rules as part of your compliance change-management process.

Limitations

• Field-path extraction depends on tenant identity being present in the query payload; malformed or encrypted payloads reduce visibility.
• Rate limits are evaluated per proxy instance unless backed by a shared limiter implementation.
• Residency enforcement validates configured targets/regions — it does not automatically move tenant data between regions.
• Enterprise analytics and chargeback require downstream metric collection even though this step emits the right tenant context.

Security and operational guidance

• Use authenticated, non-spoofable identity
• Fail closed when tenant identity is required
• The pinned Proxy controller does not watch NexoTenantIsolation directly
• Do not claim 0.2.0 data-path isolation

Related steps

• rate-limit
• filter
• traffic-split

Release availability

• 0.2.0 Private Preview: Ineffective: the resource is reconciled, but the pinned Proxy does not execute the router phase. Edits also require owning-NexoProxy reconciliation.

See the component catalog for the complete comparison matrix.