diff --git a/source/command-logging-and-monitoring/command-logging-and-monitoring.rst b/source/command-logging-and-monitoring/command-logging-and-monitoring.rst index 7baf69358e..e6fe074160 100644 --- a/source/command-logging-and-monitoring/command-logging-and-monitoring.rst +++ b/source/command-logging-and-monitoring/command-logging-and-monitoring.rst @@ -190,7 +190,7 @@ into account. See the previously mentioned MongoDB Handshake spec for details. Events API ---------- -See the `Load Balancer Specification <../load-balancers/load-balancers.rst#events>`__ for details on the ``serviceId`` field. +See the `Load Balancer Specification <../load-balancers/load-balancers.md#events>`__ for details on the ``serviceId`` field. .. code:: typescript diff --git a/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.md b/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.md index 6b11fba7c3..ba372e7cd8 100644 --- a/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.md +++ b/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.md @@ -717,7 +717,7 @@ MUST remove the entry for a `serviceId` once the connection count reaches 0. Onc connection MUST get the generation number that applies to its `serviceId` from the map and update the map to increment the connection count for this `serviceId`. -See the [Load Balancer Specification](../load-balancers/load-balancers.rst#connection-pooling) for details. +See the [Load Balancer Specification](../load-balancers/load-balancers.md#connection-pooling) for details. #### Forking @@ -777,7 +777,7 @@ driver. #### Events -See the [Load Balancer Specification](../load-balancers/load-balancers.rst#events) for details on the `serviceId` field. +See the [Load Balancer Specification](../load-balancers/load-balancers.md#events) for details on the `serviceId` field. ```typescript /** diff --git a/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.rst b/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.rst index ac1e2b12fa..86bfd3de4c 100644 --- a/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.rst +++ b/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.rst @@ -782,7 +782,7 @@ Once the MongoDB handshake is done, the connection MUST get the generation number that applies to its ``serviceId`` from the map and update the map to increment the connection count for this ``serviceId``. -See the `Load Balancer Specification <../load-balancers/load-balancers.rst#connection-pooling>`__ for details. +See the `Load Balancer Specification <../load-balancers/load-balancers.md#connection-pooling>`__ for details. Forking @@ -842,7 +842,7 @@ All drivers that implement a connection pool MUST provide an API that allows use Events ------ -See the `Load Balancer Specification <../load-balancers/load-balancers.rst#events>`__ for details on the ``serviceId`` field. +See the `Load Balancer Specification <../load-balancers/load-balancers.md#events>`__ for details on the ``serviceId`` field. .. code:: typescript diff --git a/source/index.md b/source/index.md index 58fdf270a9..91ab9ad69e 100644 --- a/source/index.md +++ b/source/index.md @@ -18,6 +18,7 @@ - [Handling of DBRefs](./dbref.md) - [Index Management](index-management/index-management.md) - [Initial DNS Seedlist Discovery](initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md) +- [Load Balancer Support](load-balancers/load-balancers.md) - [MongoDB Driver Performance Benchmarking](benchmarking/benchmarking.md) - [Server Selection](server-selection/server-selection.md) - [Server Selection Test Plan](server-selection/server-selection-tests.md) diff --git a/source/load-balancers/tests/README.md b/source/load-balancers/tests/README.md new file mode 100644 index 0000000000..45f185caa6 --- /dev/null +++ b/source/load-balancers/tests/README.md @@ -0,0 +1,49 @@ +# Load Balancer Support Tests + +______________________________________________________________________ + +## Introduction + +This document describes how drivers should create load balanced clusters for testing and how tests should be executed +for such clusters. + +## Testing Requirements + +For each server version that supports load balanced clusters, drivers MUST add two Evergreen tasks: one with a sharded +cluster with both authentication and TLS enabled and one with a sharded cluster with authentication and TLS disabled. In +each task, the sharded cluster MUST be configured with two mongos nodes running on localhost ports 27017 and 27018. The +shard and config servers may run on any free ports. Each task MUST also start up two TCP load balancers operating in +round-robin mode: one fronting both mongos servers and one fronting a single mongos. + +### Load Balancer Configuration + +Drivers MUST use the `run-load-balancer.sh` script in `drivers-evergreen-tools` to start the TCP load balancers for +Evergreen tasks. This script MUST be run after the backing sharded cluster has already been started. The script writes +the URIs of the load balancers to a YAML expansions file, which can be read by drivers via the `expansions.update` +Evergreen command. This will store the URIs into the `SINGLE_MONGOS_LB_URI` and `MULTI_MONGOS_LB_URI` environment +variables. + +### Test Runner Configuration + +If the backing sharded cluster is configured with TLS enabled, drivers MUST add the relevant TLS options to both +`SINGLE_MONGOS_LB_URI` and `MULTI_MONGOS_LB_URI` to ensure that test clients can connect to the cluster. Drivers MUST +use the final URI stored in `SINGLE_MONGOS_LB_URI` (with additional TLS options if required) to configure internal +clients for test runners (e.g. the internal MongoClient described by the +[Unified Test Format spec](../../unified-test-format/unified-test-format.md)). + +In addition to modifying load balancer URIs, drivers MUST also mock server support for returning a `serviceId` field in +`hello` or legacy `hello` command responses when running tests against a load-balanced cluster. This can be done by +using the value of `topologyVersion.processId` to set `serviceId`. This MUST be done for all connections established by +the test runner, including those made by any internal clients. + +## Tests + +The YAML and JSON files in this directory contain platform-independent tests written in the +[Unified Test Format](../../unified-test-format/unified-test-format.md). Drivers MUST run the following test suites +against a load balanced cluster: + +1. All test suites written in the Unified Test Format +2. Retryable Reads +3. Retryable Writes +4. Change Streams +5. Initial DNS Seedlist Discovery diff --git a/source/load-balancers/tests/README.rst b/source/load-balancers/tests/README.rst deleted file mode 100644 index 0a3e223f26..0000000000 --- a/source/load-balancers/tests/README.rst +++ /dev/null @@ -1,68 +0,0 @@ -=========================== -Load Balancer Support Tests -=========================== - -.. contents:: - ----- - -Introduction -============ - -This document describes how drivers should create load balanced clusters for -testing and how tests should be executed for such clusters. - -Testing Requirements -==================== - -For each server version that supports load balanced clusters, drivers MUST -add two Evergreen tasks: one with a sharded cluster with both authentication -and TLS enabled and one with a sharded cluster with authentication and TLS -disabled. In each task, the sharded cluster MUST be configured with two -mongos nodes running on localhost ports 27017 and 27018. The shard and config -servers may run on any free ports. Each task MUST also start up two TCP load -balancers operating in round-robin mode: one fronting both mongos servers and -one fronting a single mongos. - -Load Balancer Configuration ---------------------------- - -Drivers MUST use the ``run-load-balancer.sh`` script in -``drivers-evergreen-tools`` to start the TCP load balancers for Evergreen -tasks. This script MUST be run after the backing sharded cluster has already -been started. The script writes the URIs of the load balancers to a YAML -expansions file, which can be read by drivers via the ``expansions.update`` -Evergreen command. This will store the URIs into the ``SINGLE_MONGOS_LB_URI`` -and ``MULTI_MONGOS_LB_URI`` environment variables. - -Test Runner Configuration -------------------------- - -If the backing sharded cluster is configured with TLS enabled, drivers MUST -add the relevant TLS options to both ``SINGLE_MONGOS_LB_URI`` and -``MULTI_MONGOS_LB_URI`` to ensure that test clients can connect to the -cluster. Drivers MUST use the final URI stored in ``SINGLE_MONGOS_LB_URI`` -(with additional TLS options if required) to configure internal clients for -test runners (e.g. the internal MongoClient described by the `Unified Test -Format spec <../../unified-test-format/unified-test-format.md>`__). - -In addition to modifying load balancer URIs, drivers MUST also mock server -support for returning a ``serviceId`` field in ``hello`` or legacy ``hello`` -command responses when running tests against a load-balanced cluster. This -can be done by using the value of ``topologyVersion.processId`` to set -``serviceId``. This MUST be done for all connections established by the test -runner, including those made by any internal clients. - -Tests -====== - -The YAML and JSON files in this directory contain platform-independent tests -written in the `Unified Test Format -<../../unified-test-format/unified-test-format.md>`_. Drivers MUST run the -following test suites against a load balanced cluster: - -#. All test suites written in the Unified Test Format -#. Retryable Reads -#. Retryable Writes -#. Change Streams -#. Initial DNS Seedlist Discovery diff --git a/source/run-command/run-command.rst b/source/run-command/run-command.rst index ab365366cc..2df404717c 100644 --- a/source/run-command/run-command.rst +++ b/source/run-command/run-command.rst @@ -287,7 +287,7 @@ Load Balancers When in ``loadBalanced`` mode, a driver MUST pin the connection used to execute the initial operation, and reuse it for subsequent ``getMore`` operations. -* See Load Balancer's section on `Behaviour With Cursors `_ +* See Load Balancer's section on `Behaviour With Cursors <../load-balancers/load-balancers.md#behaviour-with-cursors>`_ Iterating the Cursor """""""""""""""""""" diff --git a/source/server-discovery-and-monitoring/server-discovery-and-monitoring.rst b/source/server-discovery-and-monitoring/server-discovery-and-monitoring.rst index 76dbd13f10..621aaacef9 100644 --- a/source/server-discovery-and-monitoring/server-discovery-and-monitoring.rst +++ b/source/server-discovery-and-monitoring/server-discovery-and-monitoring.rst @@ -853,7 +853,7 @@ type Unknown. TopologyType LoadBalanced ````````````````````````` -See the `Load Balancer Specification <../load-balancers/load-balancers.rst#server-discovery-logging-and-monitoring>`__ for details. +See the `Load Balancer Specification <../load-balancers/load-balancers.md#server-discovery-logging-and-monitoring>`__ for details. Other TopologyTypes ``````````````````` diff --git a/source/server-selection/server-selection.md b/source/server-selection/server-selection.md index 0d6cfd381c..3f6a3284aa 100644 --- a/source/server-selection/server-selection.md +++ b/source/server-selection/server-selection.md @@ -778,7 +778,7 @@ The single server is always suitable for write operations if it is available. During command construction, drivers MUST add a $readPreference field to the command when required by [Passing read preference to mongos and load balancers](#passing-read-preference-to-mongos-and-load-balancers); see the -[Load Balancer Specification](../load-balancers/load-balancers.rst#server-selection) for details. +[Load Balancer Specification](../load-balancers/load-balancers.md#server-selection) for details. #### Topology types: ReplicaSetWithPrimary or ReplicaSetNoPrimary diff --git a/source/server-selection/server-selection.rst b/source/server-selection/server-selection.rst index b0063e586a..e5123102ef 100644 --- a/source/server-selection/server-selection.rst +++ b/source/server-selection/server-selection.rst @@ -1010,7 +1010,7 @@ Topology type: LoadBalanced During command construction, drivers MUST add a $readPreference field to the command when required by `Passing read preference to mongos and load balancers`_; -see the `Load Balancer Specification <../load-balancers/load-balancers.rst#server-selection>`__ +see the `Load Balancer Specification <../load-balancers/load-balancers.md#server-selection>`__ for details. diff --git a/source/serverless-testing/README.rst b/source/serverless-testing/README.rst index 166fbce56c..64bde8da02 100644 --- a/source/serverless-testing/README.rst +++ b/source/serverless-testing/README.rst @@ -53,7 +53,7 @@ In contrast to the `Load Balancer testing`_, which has separate URIs for load balancers fronting a single or multiple servers, there is only a single URI for Atlas Serverless testing (i.e. ``SERVERLESS_URI``). -.. _Load Balancer testing: ../load-balancers/tests/README.rst +.. _Load Balancer testing: ../load-balancers/tests/README.md The TXT record for ``SERVERLESS_URI`` already specifies ``loadBalanced=true`` so drivers need not add that. diff --git a/source/sessions/driver-sessions.rst b/source/sessions/driver-sessions.rst index 36f4a40858..493bcc8ff7 100644 --- a/source/sessions/driver-sessions.rst +++ b/source/sessions/driver-sessions.rst @@ -837,7 +837,7 @@ Algorithm to acquire a ServerSession instance from the server session pool * If it has at least one minute left before becoming stale use this ``ServerSession`` * If it has less than one minute left before becoming stale discard it (let it be garbage collected) and return to step 1. -See the `Load Balancer Specification <../load-balancers/load-balancers.rst#session-expiration>`__ +See the `Load Balancer Specification <../load-balancers/load-balancers.md#session-expiration>`__ for details on session expiration. diff --git a/source/transactions/transactions.md b/source/transactions/transactions.md index 171f239242..4fa5c6c7fc 100644 --- a/source/transactions/transactions.md +++ b/source/transactions/transactions.md @@ -652,7 +652,7 @@ called multiple times. #### Pinning in Load Balancer Mode -See the [Load Balancer Specification](../load-balancers/load-balancers.rst#connection-pooling) for details. +See the [Load Balancer Specification](../load-balancers/load-balancers.md#connection-pooling) for details. ### recoveryToken field diff --git a/source/transactions/transactions.rst b/source/transactions/transactions.rst index f7dc314e66..1178446360 100644 --- a/source/transactions/transactions.rst +++ b/source/transactions/transactions.rst @@ -842,7 +842,7 @@ the session as ``commitTransaction`` may be called multiple times. Pinning in Load Balancer Mode ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -See the `Load Balancer Specification <../load-balancers/load-balancers.rst#connection-pooling>`__ for details. +See the `Load Balancer Specification <../load-balancers/load-balancers.md#connection-pooling>`__ for details. recoveryToken field diff --git a/source/uri-options/uri-options.rst b/source/uri-options/uri-options.rst index 918d25bc08..4177a1c2dd 100644 --- a/source/uri-options/uri-options.rst +++ b/source/uri-options/uri-options.rst @@ -81,7 +81,7 @@ Load Balancer Mode For URI option validation in Load Balancer mode (i.e. ``loadBalanced=true``), please see the -`Load Balancer spec <../load-balancers/load-balancers.rst#uri-validation>`_ for +`Load Balancer spec <../load-balancers/load-balancers.md#uri-validation>`_ for details. @@ -186,7 +186,7 @@ pertaining to URI options apply here. * - loadBalanced - "true" or "false" - - defined in `Load Balancer spec <../load-balancers/load-balancers.rst#loadbalanced>`__ + - defined in `Load Balancer spec <../load-balancers/load-balancers.md#loadbalanced>`__ - no - Whether the driver is connecting to a load balancer.