Mercurial > hg > nginx-site
annotate xml/en/docs/http/load_balancing.xml @ 3083:3b5594157fab
Documented max_headers directive.
author | Maxim Dounin <mdounin@mdounin.ru> |
---|---|
date | Fri, 24 May 2024 01:16:29 +0300 |
parents | 2be49a02a2e3 |
children |
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" | |
3046
2be49a02a2e3
Free nginx: various marketing links removed.
Maxim Dounin <mdounin@mdounin.ru>
parents:
2134
diff
changeset
|
12 rev="6"> |
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 </section> | |
294 | |
295 </article> |