mongo/docs/load_balancer_support.md

Proxy protocol support

mongod and mongos have built-in support for connections made via L4 load balancers using the proxy protocol 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 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 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 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 header at the start of its connection stream. mongos supports 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 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 header at the start of its connection stream. mongos supports both version 1 and version 2 of the proxy protocol standard.
• 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".

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 aren't expected behind a load balancer (as the load balancer will likely redirect a given client to a different mongos instance upon reconnection), we eagerly close cursors on load balanced client disconnects. We also abort any in-progress transactions that were initiated by the load balanced client.