Mercurial > hg > nginx-site
annotate xml/en/docs/http/load_balancing.xml @ 3011:55d49eb065ac
Fixed example in the js_periodic directive.
| author | Yaroslav Zhuravlev <yar@nginx.com> |
|---|---|
| date | Thu, 14 Sep 2023 16:38:00 +0100 |
| parents | 4cafd82e5007 |
| children | 2be49a02a2e3 |
| rev | line source |
|---|---|
| 1076 | 1 <?xml version="1.0"?> |
| 2 | |
| 3 <!-- | |
| 4 Copyright (C) Nginx, Inc. | |
| 5 --> | |
| 6 | |
| 7 <!DOCTYPE article SYSTEM "../../../../dtd/article.dtd"> | |
| 8 | |
| 9 <article name="Using nginx as HTTP load balancer" | |
| 10 link="/en/docs/http/load_balancing.html" | |
| 11 lang="en" | |
|
2134
4cafd82e5007
Added info about gRPC to various modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1527
diff
changeset
|
12 rev="5"> |
| 1076 | 13 |
| 14 <section name="Introduction"> | |
| 15 | |
| 16 <para> | |
| 17 Load balancing across multiple application instances is a commonly used | |
| 18 technique for optimizing resource utilization, maximizing throughput, | |
| 19 reducing latency, and ensuring fault-tolerant configurations. | |
| 20 </para> | |
| 21 | |
| 22 <para> | |
| 23 It is possible to use nginx as a very efficient HTTP load balancer to | |
| 24 distribute traffic to several application servers and to improve | |
| 25 performance, scalability and reliability of web applications with nginx. | |
| 26 </para> | |
| 27 | |
| 28 </section> | |
| 29 | |
| 30 | |
| 31 <section id="nginx_load_balancing_methods" | |
| 32 name="Load balancing methods"> | |
| 33 | |
| 34 <para> | |
| 35 The following load balancing mechanisms (or methods) are supported in | |
| 36 nginx: | |
| 37 <list type="bullet" compact="no"> | |
| 38 | |
| 39 <listitem> | |
| 40 round-robin — requests to the application servers are distributed | |
| 41 in a round-robin fashion, | |
| 42 </listitem> | |
| 43 | |
| 44 <listitem> | |
| 45 least-connected — next request is assigned to the server with the | |
| 46 least number of active connections, | |
| 47 </listitem> | |
| 48 | |
| 49 <listitem> | |
| 50 ip-hash — a hash-function is used to determine what server should | |
| 51 be selected for the next request (based on the client’s IP address). | |
| 52 </listitem> | |
| 53 | |
| 54 </list> | |
| 55 </para> | |
| 56 | |
| 57 </section> | |
| 58 | |
| 59 | |
| 60 <section id="nginx_load_balancing_configuration" | |
| 61 name="Default load balancing configuration"> | |
| 62 | |
| 63 <para> | |
| 64 The simplest configuration for load balancing with nginx may look | |
| 65 like the following: | |
| 66 <programlisting> | |
| 67 http { | |
| 68 upstream myapp1 { | |
| 69 server srv1.example.com; | |
| 70 server srv2.example.com; | |
| 71 server srv3.example.com; | |
| 72 } | |
| 73 | |
| 74 server { | |
| 75 listen 80; | |
| 76 | |
| 77 location / { | |
| 78 proxy_pass http://myapp1; | |
| 79 } | |
| 80 } | |
| 81 } | |
| 82 </programlisting> | |
| 83 </para> | |
| 84 | |
| 85 <para> | |
| 86 In the example above, there are 3 instances of the same application | |
| 87 running on srv1-srv3. | |
| 88 When the load balancing method is not specifically configured, | |
| 89 it defaults to round-robin. | |
| 90 All requests are | |
| 91 <link doc="ngx_http_proxy_module.xml" id="proxy_pass"> | |
| 92 proxied</link> to the server group myapp1, and nginx applies HTTP load | |
| 93 balancing to distribute the requests. | |
| 94 </para> | |
| 95 | |
| 96 <para> | |
| 97 Reverse proxy implementation in nginx includes load balancing for HTTP, | |
|
2134
4cafd82e5007
Added info about gRPC to various modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1527
diff
changeset
|
98 HTTPS, FastCGI, uwsgi, SCGI, memcached, and gRPC. |
| 1076 | 99 </para> |
| 100 | |
| 101 <para> | |
| 102 To configure load balancing for HTTPS instead of HTTP, just use “https” | |
| 103 as the protocol. | |
| 104 </para> | |
| 105 | |
| 106 <para> | |
|
2134
4cafd82e5007
Added info about gRPC to various modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1527
diff
changeset
|
107 When setting up load balancing for FastCGI, uwsgi, SCGI, memcached, or gRPC, use |
| 1076 | 108 <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_pass"/>, |
| 1194 | 109 <link doc="ngx_http_uwsgi_module.xml" id="uwsgi_pass"/>, |
|
2134
4cafd82e5007
Added info about gRPC to various modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1527
diff
changeset
|
110 <link doc="ngx_http_scgi_module.xml" id="scgi_pass"/>, |
|
4cafd82e5007
Added info about gRPC to various modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1527
diff
changeset
|
111 <link doc="ngx_http_memcached_module.xml" id="memcached_pass"/>, and |
|
4cafd82e5007
Added info about gRPC to various modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1527
diff
changeset
|
112 <link doc="ngx_http_grpc_module.xml" id="grpc_pass"/> |
| 1076 | 113 directives respectively. |
| 114 </para> | |
| 115 | |
| 116 </section> | |
| 117 | |
| 118 | |
| 119 <section id="nginx_load_balancing_with_least_connected" | |
| 120 name="Least connected load balancing"> | |
| 121 | |
| 122 <para> | |
| 123 Another load balancing discipline is least-connected. | |
| 124 Least-connected allows controlling the load on application | |
| 125 instances more fairly in a situation when some of the requests | |
| 126 take longer to complete. | |
| 127 </para> | |
| 128 | |
| 129 <para> | |
| 130 With the least-connected load balancing, nginx will try not to overload a | |
| 131 busy application server with excessive requests, distributing the new | |
| 132 requests to a less busy server instead. | |
| 133 </para> | |
| 134 | |
| 135 <para> | |
| 136 Least-connected load balancing in nginx is activated when the | |
| 137 <link doc="ngx_http_upstream_module.xml" id="least_conn"> | |
| 138 least_conn</link> directive is used as part of the server group configuration: | |
| 139 <programlisting> | |
| 140 upstream myapp1 { | |
| 141 least_conn; | |
| 142 server srv1.example.com; | |
| 143 server srv2.example.com; | |
| 144 server srv3.example.com; | |
| 145 } | |
| 146 </programlisting> | |
| 147 </para> | |
| 148 | |
| 149 </section> | |
| 150 | |
| 151 | |
| 152 <section id="nginx_load_balancing_with_ip_hash" | |
| 153 name="Session persistence"> | |
| 154 | |
| 155 <para> | |
| 156 Please note that with round-robin or least-connected load | |
| 157 balancing, each subsequent client’s request can be potentially | |
| 158 distributed to a different server. | |
| 159 There is no guarantee that the same client will be always | |
| 160 directed to the same server. | |
| 161 </para> | |
| 162 | |
| 163 <para> | |
| 164 If there is the need to tie a client to a particular application server — | |
| 165 in other words, make the client’s session “sticky” or “persistent” in | |
| 166 terms of always trying to select a particular server — the ip-hash load | |
| 167 balancing mechanism can be used. | |
| 168 </para> | |
| 169 | |
| 170 <para> | |
| 171 With ip-hash, the client’s IP address is used as a hashing key to | |
| 172 determine what server in a server group should be selected for the | |
| 173 client’s requests. | |
| 174 This method ensures that the requests from the same client | |
| 175 will always be directed to the same server | |
| 176 except when this server is unavailable. | |
| 177 </para> | |
| 178 | |
| 179 <para> | |
| 180 To configure ip-hash load balancing, just add the | |
| 181 <link doc="ngx_http_upstream_module.xml" id="ip_hash"/> | |
| 182 directive to the server (upstream) group configuration: | |
| 183 <programlisting> | |
| 184 upstream myapp1 { | |
| 185 ip_hash; | |
| 186 server srv1.example.com; | |
| 187 server srv2.example.com; | |
| 188 server srv3.example.com; | |
| 189 } | |
| 190 </programlisting> | |
| 191 </para> | |
| 192 | |
| 193 </section> | |
| 194 | |
| 195 | |
| 196 <section id="nginx_weighted_load_balancing" | |
| 197 name="Weighted load balancing"> | |
| 198 | |
| 199 <para> | |
| 200 It is also possible to influence nginx load balancing algorithms even | |
| 201 further by using server weights. | |
| 202 </para> | |
| 203 | |
| 204 <para> | |
| 205 In the examples above, the server weights are not configured which means | |
| 206 that all specified servers are treated as equally qualified for a | |
| 207 particular load balancing method. | |
| 208 </para> | |
| 209 | |
| 210 <para> | |
| 211 With the round-robin in particular it also means a more or less equal | |
| 212 distribution of requests across the servers — provided there are enough | |
| 213 requests, and when the requests are processed in a uniform manner and | |
| 214 completed fast enough. | |
| 215 </para> | |
| 216 | |
| 217 <para> | |
| 218 When the | |
| 219 <link doc="ngx_http_upstream_module.xml" id="server">weight</link> | |
| 220 parameter is specified for a server, the weight is accounted as part | |
| 221 of the load balancing decision. | |
| 222 <programlisting> | |
| 223 upstream myapp1 { | |
| 224 server srv1.example.com weight=3; | |
| 225 server srv2.example.com; | |
| 226 server srv3.example.com; | |
| 227 } | |
| 228 </programlisting> | |
| 229 </para> | |
| 230 | |
| 231 <para> | |
| 232 With this configuration, every 5 new requests will be distributed across | |
| 233 the application instances as the following: 3 requests will be directed | |
| 234 to srv1, one request will go to srv2, and another one — to srv3. | |
| 235 </para> | |
| 236 | |
| 237 <para> | |
| 238 It is similarly possible to use weights with the least-connected and | |
| 239 ip-hash load balancing in the recent versions of nginx. | |
| 240 </para> | |
| 241 | |
| 242 </section> | |
| 243 | |
| 244 | |
| 245 <section id="nginx_load_balancing_health_checks" | |
| 246 name="Health checks"> | |
| 247 | |
| 248 <para> | |
| 249 Reverse proxy implementation in nginx includes in-band (or passive) | |
| 250 server health checks. | |
| 251 If the response from a particular server fails with an error, | |
| 252 nginx will mark this server as failed, and will try to | |
| 253 avoid selecting this server for subsequent inbound requests for a while. | |
| 254 </para> | |
| 255 | |
| 256 <para> | |
| 257 The | |
| 258 <link doc="ngx_http_upstream_module.xml" id="server">max_fails</link> | |
| 259 directive sets the number of consecutive unsuccessful attempts to | |
| 260 communicate with the server that should happen during | |
| 261 <link doc="ngx_http_upstream_module.xml" id="server">fail_timeout</link>. | |
| 262 By default, | |
| 263 <link doc="ngx_http_upstream_module.xml" id="server">max_fails</link> | |
| 264 is set to 1. | |
| 265 When it is set to 0, health checks are disabled for this server. | |
| 266 The | |
| 267 <link doc="ngx_http_upstream_module.xml" id="server">fail_timeout</link> | |
| 268 parameter also defines how long the server will be marked as failed. | |
| 269 After | |
| 270 <link doc="ngx_http_upstream_module.xml" id="server">fail_timeout</link> | |
| 271 interval following the server failure, nginx will start to gracefully | |
| 272 probe the server with the live client’s requests. | |
| 273 If the probes have been successful, the server is marked as a live one. | |
| 274 </para> | |
| 275 | |
| 276 </section> | |
| 277 | |
| 278 | |
| 279 <section id="nginx_load_balancing_additional_information" | |
| 280 name="Further reading"> | |
| 281 | |
| 282 <para> | |
| 283 In addition, there are more directives and parameters that control server | |
| 284 load balancing in nginx, e.g. | |
| 285 <link doc="ngx_http_proxy_module.xml" id="proxy_next_upstream"/>, | |
| 286 <link doc="ngx_http_upstream_module.xml" id="server">backup</link>, | |
| 287 <link doc="ngx_http_upstream_module.xml" id="server">down</link>, and | |
| 288 <link doc="ngx_http_upstream_module.xml" id="keepalive"/>. | |
|
1177
e33858baaecd
Links to the nginx reference docs and lb blogposts added.
Maxim Konovalov <maxim@nginx.com>
parents:
1165
diff
changeset
|
289 For more information please check our |
|
1178
52747e115aba
A relative URL instead of absolute one used.
Maxim Konovalov <maxim@nginx.com>
parents:
1177
diff
changeset
|
290 <link url="..">reference documentation</link>. |
| 1076 | 291 </para> |
| 292 | |
| 293 <para> | |
| 294 Last but not least, | |
|
1527
f9a138e5ab14
Updated links to nginx.com website.
Valentin Bartenev <vbart@nginx.com>
parents:
1194
diff
changeset
|
295 <link url="https://www.nginx.com/products/application-load-balancing/"> |
|
1165
0a441212ef0f
A link to nginx.com application load balancing product page fixed.
Maxim Konovalov <maxim@nginx.com>
parents:
1076
diff
changeset
|
296 application load balancing</link>, |
|
1527
f9a138e5ab14
Updated links to nginx.com website.
Valentin Bartenev <vbart@nginx.com>
parents:
1194
diff
changeset
|
297 <link url="https://www.nginx.com/products/application-health-checks/"> |
| 1076 | 298 application health checks</link>, |
|
1527
f9a138e5ab14
Updated links to nginx.com website.
Valentin Bartenev <vbart@nginx.com>
parents:
1194
diff
changeset
|
299 <link url="https://www.nginx.com/products/live-activity-monitoring/"> |
| 1076 | 300 activity monitoring</link> and |
|
1527
f9a138e5ab14
Updated links to nginx.com website.
Valentin Bartenev <vbart@nginx.com>
parents:
1194
diff
changeset
|
301 <link url="https://www.nginx.com/products/on-the-fly-reconfiguration/"> |
| 1076 | 302 on-the-fly reconfiguration</link> of server groups are available |
| 303 as part of our paid NGINX Plus subscriptions. | |
| 304 </para> | |
| 305 | |
|
1177
e33858baaecd
Links to the nginx reference docs and lb blogposts added.
Maxim Konovalov <maxim@nginx.com>
parents:
1165
diff
changeset
|
306 <para> |
|
e33858baaecd
Links to the nginx reference docs and lb blogposts added.
Maxim Konovalov <maxim@nginx.com>
parents:
1165
diff
changeset
|
307 The following articles describe load balancing with NGINX Plus |
|
e33858baaecd
Links to the nginx reference docs and lb blogposts added.
Maxim Konovalov <maxim@nginx.com>
parents:
1165
diff
changeset
|
308 in more detail: |
|
e33858baaecd
Links to the nginx reference docs and lb blogposts added.
Maxim Konovalov <maxim@nginx.com>
parents:
1165
diff
changeset
|
309 <list type="bullet" compact="no"> |
|
e33858baaecd
Links to the nginx reference docs and lb blogposts added.
Maxim Konovalov <maxim@nginx.com>
parents:
1165
diff
changeset
|
310 |
|
e33858baaecd
Links to the nginx reference docs and lb blogposts added.
Maxim Konovalov <maxim@nginx.com>
parents:
1165
diff
changeset
|
311 <listitem> |
|
1527
f9a138e5ab14
Updated links to nginx.com website.
Valentin Bartenev <vbart@nginx.com>
parents:
1194
diff
changeset
|
312 <link url="https://www.nginx.com/blog/load-balancing-with-nginx-plus/"> |
|
1177
e33858baaecd
Links to the nginx reference docs and lb blogposts added.
Maxim Konovalov <maxim@nginx.com>
parents:
1165
diff
changeset
|
313 Load Balancing with NGINX and NGINX Plus</link> |
|
e33858baaecd
Links to the nginx reference docs and lb blogposts added.
Maxim Konovalov <maxim@nginx.com>
parents:
1165
diff
changeset
|
314 </listitem> |
|
e33858baaecd
Links to the nginx reference docs and lb blogposts added.
Maxim Konovalov <maxim@nginx.com>
parents:
1165
diff
changeset
|
315 |
|
e33858baaecd
Links to the nginx reference docs and lb blogposts added.
Maxim Konovalov <maxim@nginx.com>
parents:
1165
diff
changeset
|
316 <listitem> |
|
1527
f9a138e5ab14
Updated links to nginx.com website.
Valentin Bartenev <vbart@nginx.com>
parents:
1194
diff
changeset
|
317 <link url="https://www.nginx.com/blog/load-balancing-with-nginx-plus-part2/"> |
|
1177
e33858baaecd
Links to the nginx reference docs and lb blogposts added.
Maxim Konovalov <maxim@nginx.com>
parents:
1165
diff
changeset
|
318 Load Balancing with NGINX and NGINX Plus part 2</link> |
|
e33858baaecd
Links to the nginx reference docs and lb blogposts added.
Maxim Konovalov <maxim@nginx.com>
parents:
1165
diff
changeset
|
319 </listitem> |
|
e33858baaecd
Links to the nginx reference docs and lb blogposts added.
Maxim Konovalov <maxim@nginx.com>
parents:
1165
diff
changeset
|
320 |
|
e33858baaecd
Links to the nginx reference docs and lb blogposts added.
Maxim Konovalov <maxim@nginx.com>
parents:
1165
diff
changeset
|
321 </list> |
|
e33858baaecd
Links to the nginx reference docs and lb blogposts added.
Maxim Konovalov <maxim@nginx.com>
parents:
1165
diff
changeset
|
322 </para> |
|
e33858baaecd
Links to the nginx reference docs and lb blogposts added.
Maxim Konovalov <maxim@nginx.com>
parents:
1165
diff
changeset
|
323 |
| 1076 | 324 </section> |
| 325 | |
| 326 </article> |