1===========================
2Load Balancer Support Tests
3===========================
4
5.. contents::
6
7----
8
9Introduction
10============
11
12This document describes how drivers should create load balanced clusters for
13testing and how tests should be executed for such clusters.
14
15Testing Requirements
16====================
17
18For each server version that supports load balanced clusters, drivers MUST
19add two Evergreen tasks: one with a sharded cluster with both authentication
20and TLS enabled and one with a sharded cluster with authentication and TLS
21disabled. In each task, the sharded cluster MUST be configured with two
22mongos nodes running on localhost ports 27017 and 27018. The shard and config
23servers may run on any free ports. Each task MUST also start up two TCP load
24balancers operating in round-robin mode: one fronting both mongos servers and
25one fronting a single mongos.
26
27Load Balancer Configuration
28---------------------------
29
30Drivers MUST use the ``run-load-balancer.sh`` script in
31``drivers-evergreen-tools`` to start the TCP load balancers for Evergreen
32tasks. This script MUST be run after the backing sharded cluster has already
33been started. The script writes the URIs of the load balancers to a YAML
34expansions file, which can be read by drivers via the ``expansions.update``
35Evergreen command. This will store the URIs into the ``SINGLE_MONGOS_LB_URI``
36and ``MULTI_MONGOS_LB_URI`` environment variables.
37
38Test Runner Configuration
39-------------------------
40
41If the backing sharded cluster is configured with TLS enabled, drivers MUST
42add the relevant TLS options to both ``SINGLE_MONGOS_LB_URI`` and
43``MULTI_MONGOS_LB_URI`` to ensure that test clients can connect to the
44cluster. Drivers MUST use the final URI stored in ``SINGLE_MONGOS_LB_URI``
45(with additional TLS options if required) to configure internal clients for
46test runners (e.g. the internal MongoClient described by the `Unified Test
47Format spec <../../unified-test-format/unified-test-format.rst>`__).
48
49In addition to modifying load balancer URIs, drivers MUST also mock server
50support for returning a ``serviceId`` field in ``hello`` or legacy ``hello``
51command responses when running tests against a load-balanced cluster. This
52can be done by using the value of ``topologyVersion.processId`` to set
53``serviceId``. This MUST be done for all connections established by the test
54runner, including those made by any internal clients.
55
56Tests
57======
58
59The YAML and JSON files in this directory contain platform-independent tests
60written in the `Unified Test Format
61<../../unified-test-format/unified-test-format.rst>`_. Drivers MUST run the
62following test suites against a load balanced cluster:
63
64#. All test suites written in the Unified Test Format
65#. Retryable Reads
66#. Retryable Writes
67#. Change Streams
68#. Initial DNS Seedlist Discovery
View as plain text