Cross-Cluster Federation

Status: Unsupported in 0.2.0: dashboard manifest only. No canonical entitlement and no supported deployment contract.

:::danger Unsupported legacy concept

This page preserves a legacy dashboard concept. It has no canonical entitlement and no supported deployment contract. Do not infer a CRD, Operator reconciliation path, runtime implementation, or support commitment from the historical configuration and examples below.

:::

This page belongs to the immutable 0.2.0 Private Preview documentation.

At a glance

Property	Value
Pipeline phase	Router + Response
Category	Routing
Canonical minimum tier	No canonical entitlement
Legacy dashboard tier label	Enterprise
Legacy rendered name	Cross-Cluster Federation
Legacy rendered summary	Query multiple MongoDB clusters as one logical database with transparent routing.
Canonical entitlement	No
Supported deployment contract	No
Release status	Unsupported in 0.2.0: dashboard manifest only. No canonical entitlement and no supported deployment contract.

Release accuracy

• 0.2.0 Private Preview: Unsupported in 0.2.0: dashboard manifest only. No canonical entitlement and no supported deployment contract.

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.2ms
P95	<0.5ms
P99	<1ms

Legacy note: Simple routing adds minimal overhead; cross-cluster joins add significant latency

Overview

The Cross-Cluster Federation step presents multiple independent MongoDB clusters as a single unified namespace. Queries are routed to the correct cluster based on database name, collection, or shard key — completely transparent to the application.

Health checking and automatic failover ensure high availability. Optional cross-cluster aggregation enables $lookup operations that span clusters (with performance caveats).

When to use

• Merging data from multiple MongoDB deployments after M&A
• Distributing data across regions while presenting a unified API
• Scaling beyond single-cluster limits without application changes
• Implementing active-active multi-region architectures

How it works

1. Incoming query's target namespace is determined from the command
2. Namespace is mapped to the appropriate cluster
3. Query is forwarded to the target cluster
4. For cross-cluster aggregations: sub-queries fan out to multiple clusters and results are merged
5. Health checks monitor all clusters; failover activates on sustained failures

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
clusters	json	—	Not specified	Cluster topology: {name, address, databases[]}
routing_mode	select	database	Not specified	How to route queries to clusters
cross_cluster_joins	boolean	false	Not specified	Enable $lookup across clusters
health_check_interval	duration	10s	Not specified	Cluster health check frequency
failover_enabled	boolean	true	Not specified	Auto-failover on cluster failure
failover_threshold	number	5000	Not specified	Cluster down threshold (ms)

Settings reference

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

Examples

Multi-region federation

steps:
  - id: builtin:cross-cluster-federation
    config:
      routing_mode: database
      failover_enabled: true
      health_check_interval: 5s
      clusters:
        - name: us-east
          address: mongo-us-east:27017
          databases: [users, orders, inventory]
        - name: eu-west
          address: mongo-eu-west:27017
          databases: [users_eu, analytics]
        - name: apac
          address: mongo-apac:27017
          databases: [users_apac, logs]

Best practices

• Keep cross_cluster_joins disabled unless absolutely needed
• Use consistent database naming conventions for simple routing
• Monitor cluster health dashboard for latency drift between regions
• Test failover scenarios regularly with chaos engineering

Limitations

• Cross-cluster transactions are not supported
• Cross-cluster $lookup requires fetching all matching documents to the proxy
• Maximum 10 federated clusters (connection pool overhead)

Security and operational guidance

• This is a legacy dashboard concept, not a canonically entitled Nexo component.
• No supported deployment contract, CRD mapping, Operator reconciliation path, or runtime execution guarantee is published.
• Treat every configuration example and performance number below as historical design material only.

Related steps

• geo-routing
• intelligent-failover
• tenant-isolation

Release availability

• 0.2.0 Private Preview: Unsupported in 0.2.0: dashboard manifest only. No canonical entitlement and no supported deployment contract.

See the component catalog for the complete comparison matrix.