mirror
/
mongo
mirror of https://github.com/mongodb/mongo
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

SERVER-95685 Documentation update for proxy protocol support (#34995) 

GitOrigin-RevId: e350ea005d647809ff3c27dc5e946e6ee52965b5
This commit is contained in:
Didier Nadeau 2025-04-25 14:40:56 -04:00 committed by MongoDB Bot
parent 28351fbf5d
commit fd88ee1223
1 changed files with 51 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

64
docs/load_balancer_support.md
View File

@ -1,24 +1,62 @@
# Load balancer support
# Proxy protocol support
`mongos` has built-in support for connections made via L4 load balancers. However, placing `mongos`
endpoints behind load balancers requires proper configuration of the load balancers, `mongos`, and
any drivers or shells used to connect to the database. Three conditions must be fulfilled for
`mongos` to be used behind a load balancer:
`mongod` and `mongos` have built-in support for connections made via L4 load balancers using
the [proxy protocol][proxy-protocol-url] header. Placing `mongos` or `mongod` behind load balancers
requires proper configuration of the load balancers, `mongos`, and `mongod`.
# Configuring mongod
To use `mongod` with a L4 load balancer (or reverse proxy) it _must_ be configured with the
`proxyPort` config option whose value can be specified at program start in any of the ways
mentioned in the server config documentation. This config option opens a new port to which the
L4 load balancer _must_ connect.
The L4 load balancer (or reverse proxy) _must_ emit a [proxy protocol][proxy-protocol-url] header
at the start of its connection stream. `mongod` supports both version 1 and version 2 of the proxy
standard.
# Reverse proxy vs load balancer
Sharded clusters might be configured to work with either a L4 load balancer or a reverse proxy. In
both cases the proxy or load balancer _must_ connect to the `mongos`'s load-balancer port.
Placing `mongos` behind a reverse proxy does not hide the list of `mongos`. The driver will choose
a specific `mongos` to connect to via the reverse proxy.
Placing `mongos` behind an L4 load balancer hides the list of `mongos`. The driver only sees the
load balancer and, the connections it makes are routed by the load balancer to a `mongos`. There is
no guarantee that all connections from a driver target the same `mongos` : generally we can expect
that connections from a driver are distributed among multiple `mongos`.
# Configuring mongos with a reverse proxy
When a sharded cluster is deployed with a reverse proxy, there are two conditions that must be
fulfilled :
- `mongos` must be configured with the [MongoDB Server Parameter](https://docs.mongodb.com/manual/reference/parameters/) `loadBalancerPort` whose value can be specified at program start in any of the ways mentioned in the server parameter documentation.
This option causes `mongos` to open a second port that expects _only_ load balanced connections. All connections made from load
balancers _must_ be made over this port, and no regular connections may be made over this port.
This option causes `mongos` to open a second port. All connections made from reverse proxy _must_ be made over this port, and no regular connections (without HAProxy protocol header) may be made over this port.
- The reverse proxy _must_ be configured to emit a [proxy protocol][proxy-protocol-url] header
at the [start of its connection stream](https://github.com/mongodb/mongo/commit/3a18d295d22b377cc7bc4c97bd3b6884d065bb85). `mongos` [supports](https://github.com/mongodb/mongo/commit/786482da93c3e5e58b1c690cb060f00c60864f69) both version 1 and version 2 of the proxy
protocol standard.
The driver does not require any configuration change compared to a cluster without a reverse proxy.
# Configuring mongos with a load balancer
When a sharded cluster is deployed with an L4 load balancer there are three conditions that must be
fulfilled :
- `mongos` must be configured with the [MongoDB Server Parameter](https://docs.mongodb.com/manual/reference/parameters/) `loadBalancerPort` whose value can be specified at program start in any of the ways mentioned in the server parameter documentation.
This option causes `mongos` to open a second port. All connections made from load
balancers _must_ be made over this port, and no regular connections (without HAProxy protocol header) may be made over this port.
- The L4 load balancer _must_ be configured to emit a [proxy protocol][proxy-protocol-url] header
at the [start of its connection stream](https://github.com/mongodb/mongo/commit/3a18d295d22b377cc7bc4c97bd3b6884d065bb85). `mongos` [supports](https://github.com/mongodb/mongo/commit/786482da93c3e5e58b1c690cb060f00c60864f69) both version 1 and version 2 of the proxy
protocol standard.
- The connection string used to establish the `mongos` connection must set the `loadBalanced` option,
e.g., when connecting to a local `mongos` instance, if the `loadBalancerPort` server parameter was set to 20100, the
- Clients (drivers or shells) connecting to a `mongos` through the load balancer must set the `loadBalanced` option,
e.g., when connecting to a local `mongos` instance through the load balancer, if the `loadBalancerPort` server parameter was set to 20100, the
connection string must be of the form `"mongodb://localhost:20100/?loadBalanced=true"`.
`mongos` will emit appropiate error messages on connection attempts if these requirements are not
met.
There are some subtle behavioral differences that these configuration options enable, chief of
There are some subtle behavioral differences that the load balancer options enable, chief of
which is how `mongos` deals with open cursors on client disconnection. Over a normal connection,
`mongos` will keep open cursors alive for a short while after client disconnection in case the
client reconnects and continues to request more from the given cursor. Since client reconnections