Mercurial > hg > nginx-site
comparison xml/en/docs/dev/development_guide.xml @ 1939:c1b0169e8f54
Added the "Load balancing" section of the development guide.
author | Vladimir Homutov <vl@nginx.com> |
---|---|
date | Fri, 24 Mar 2017 18:04:55 +0300 |
parents | 8f996938fe23 |
children | 95a7e6eb5270 |
comparison
equal
deleted
inserted
replaced
1938:fff0b5f3b913 | 1939:c1b0169e8f54 |
---|---|
4243 code, the denial code will become the finalization code. | 4243 code, the denial code will become the finalization code. |
4244 </para> | 4244 </para> |
4245 | 4245 |
4246 </section> | 4246 </section> |
4247 | 4247 |
4248 | |
4249 <section name="Load balancing" id="http_load_balancing"> | |
4250 | |
4251 <para> | |
4252 The | |
4253 <link doc="../http/ngx_http_upstream_module.xml">ngx_http_upstream_module</link> | |
4254 provides basic functionality to pass requests to remote servers. | |
4255 This functionality is used by modules that implement specific protocols, | |
4256 such as HTTP or FastCGI. | |
4257 The module also provides an interface for creating custom | |
4258 load balancing modules and implements a default round-robin balancing method. | |
4259 </para> | |
4260 | |
4261 <para> | |
4262 Examples of modules that implement alternative load balancing methods are | |
4263 <link doc="../http/ngx_http_upstream_module.xml" id="least_conn"/> | |
4264 and <link doc="../http/ngx_http_upstream_module.xml" id="hash"/>. | |
4265 Note that these modules are actually implemented as extensions of the upstream | |
4266 module and share a lot of code, such as representation of a server group. | |
4267 The <link doc="../http/ngx_http_upstream_module.xml" id="keepalive"/> module | |
4268 is an example of an independent module, extending upstream functionality. | |
4269 </para> | |
4270 | |
4271 <para> | |
4272 The | |
4273 <link doc="../http/ngx_http_upstream_module.xml">ngx_http_upstream_module</link> | |
4274 may be configured explicitly by placing the corresponding | |
4275 <link doc="../http/ngx_http_upstream_module.xml" id="upstream"/> block into | |
4276 the configuration file, or implicitly by using directives | |
4277 that accept a URL evaluated at some point to the list of servers, | |
4278 for example, | |
4279 <link doc="../http/ngx_http_proxy_module.xml" id="proxy_pass"/>. | |
4280 Only explicit configurations may use an alternative load balancing method. | |
4281 The upstream module configuration has its own directive context | |
4282 <literal>NGX_HTTP_UPS_CONF</literal>. | |
4283 The structure is defined as follows: | |
4284 <programlisting> | |
4285 struct ngx_http_upstream_srv_conf_s { | |
4286 ngx_http_upstream_peer_t peer; | |
4287 void **srv_conf; | |
4288 | |
4289 ngx_array_t *servers; /* ngx_http_upstream_server_t */ | |
4290 | |
4291 ngx_uint_t flags; | |
4292 ngx_str_t host; | |
4293 u_char *file_name; | |
4294 ngx_uint_t line; | |
4295 in_port_t port; | |
4296 ngx_uint_t no_port; /* unsigned no_port:1 */ | |
4297 | |
4298 #if (NGX_HTTP_UPSTREAM_ZONE) | |
4299 ngx_shm_zone_t *shm_zone; | |
4300 #endif | |
4301 }; | |
4302 </programlisting> | |
4303 | |
4304 <list type="bullet"> | |
4305 | |
4306 <listitem> | |
4307 <literal>srv_conf</literal> — configuration context of upstream modules | |
4308 </listitem> | |
4309 | |
4310 <listitem> | |
4311 <literal>servers</literal> — array of | |
4312 <literal>ngx_http_upstream_server_t</literal>, the result of parsing a set of | |
4313 <link doc="../http/ngx_http_upstream_module.xml" id="server"/> directives | |
4314 in the <literal>upstream</literal> block | |
4315 </listitem> | |
4316 | |
4317 <listitem> | |
4318 <literal>flags</literal> — flags that mostly mark which features | |
4319 (configured as parameters of | |
4320 the <link doc="../http/ngx_http_upstream_module.xml" id="server"/> directive) | |
4321 are supported by the particular load balancing method. | |
4322 | |
4323 <list type="bullet"> | |
4324 | |
4325 <listitem> | |
4326 <literal>NGX_HTTP_UPSTREAM_CREATE</literal> — used to distinguish explicitly | |
4327 defined upstreams from automatically created by | |
4328 <link doc="../http/ngx_http_proxy_module.xml" id="proxy_pass"/> and “friends” | |
4329 (FastCGI, SCGI, etc.) | |
4330 </listitem> | |
4331 | |
4332 <listitem> | |
4333 <literal>NGX_HTTP_UPSTREAM_WEIGHT</literal> — “<literal>weight</literal>” | |
4334 is supported | |
4335 </listitem> | |
4336 | |
4337 <listitem> | |
4338 <literal>NGX_HTTP_UPSTREAM_MAX_FAILS</literal> — “<literal>max_fails</literal>” | |
4339 is supported | |
4340 </listitem> | |
4341 | |
4342 <listitem> | |
4343 <literal>NGX_HTTP_UPSTREAM_FAIL_TIMEOUT</literal> — | |
4344 “<literal>fail_timeout</literal>” is supported | |
4345 </listitem> | |
4346 | |
4347 <listitem> | |
4348 <literal>NGX_HTTP_UPSTREAM_DOWN</literal> — “<literal>down</literal>” | |
4349 is supported | |
4350 </listitem> | |
4351 | |
4352 <listitem> | |
4353 <literal>NGX_HTTP_UPSTREAM_BACKUP</literal> — “<literal>backup</literal>” | |
4354 is supported | |
4355 </listitem> | |
4356 | |
4357 <listitem> | |
4358 <literal>NGX_HTTP_UPSTREAM_MAX_CONNS</literal> — “<literal>max_conns</literal>” | |
4359 is supported | |
4360 </listitem> | |
4361 | |
4362 </list> | |
4363 | |
4364 </listitem> | |
4365 | |
4366 <listitem> | |
4367 <literal>host</literal> — the name of an upstream | |
4368 </listitem> | |
4369 | |
4370 <listitem> | |
4371 <literal>file_name, line</literal> — the name of the configuration file | |
4372 and the line where the <literal>upstream</literal> block is located | |
4373 </listitem> | |
4374 | |
4375 <listitem> | |
4376 <literal>port</literal> and <literal>no_port</literal> — unused by explicit | |
4377 upstreams | |
4378 </listitem> | |
4379 | |
4380 <listitem> | |
4381 <literal>shm_zone</literal> — a shared memory zone used by this upstream, if any | |
4382 </listitem> | |
4383 | |
4384 <listitem> | |
4385 <literal>peer</literal> — an object that holds generic methods for | |
4386 initializing upstream configuration: | |
4387 | |
4388 <programlisting> | |
4389 typedef struct { | |
4390 ngx_http_upstream_init_pt init_upstream; | |
4391 ngx_http_upstream_init_peer_pt init; | |
4392 void *data; | |
4393 } ngx_http_upstream_peer_t; | |
4394 </programlisting> | |
4395 A module that implements a load balancing algorithm must set these | |
4396 methods and initialize private <literal>data</literal>. | |
4397 If <literal>init_upstream</literal> was not initialized during configuration | |
4398 parsing, <literal>ngx_http_upstream_module</literal> sets it to default | |
4399 <literal>ngx_http_upstream_init_round_robin</literal>. | |
4400 | |
4401 <list type="bullet"> | |
4402 <listitem> | |
4403 <literal>init_upstream(cf, us)</literal> — configuration-time | |
4404 method responsible for initializing a group of servers and | |
4405 initializing the <literal>init()</literal> method in case of success. | |
4406 A typical load balancing module uses a list of servers in the upstream block | |
4407 to create some efficient data structure that it uses and saves own | |
4408 configuration to the <literal>data</literal> field. | |
4409 </listitem> | |
4410 | |
4411 <listitem> | |
4412 <literal>init(r, us)</literal> — initializes per-request | |
4413 <literal>ngx_http_upstream_peer_t.peer</literal> (not to be confused with the | |
4414 <literal>ngx_http_upstream_srv_conf_t.peer</literal> described above which | |
4415 is per-upstream) structure that is used for load balancing. | |
4416 It will be passed as <literal>data</literal> argument to all callbacks that | |
4417 deal with server selection. | |
4418 </listitem> | |
4419 </list> | |
4420 | |
4421 </listitem> | |
4422 </list> | |
4423 </para> | |
4424 | |
4425 <para> | |
4426 When nginx has to pass a request to another host for processing, it uses | |
4427 a configured load balancing method to obtain an address to connect to. | |
4428 The method is taken from the | |
4429 <literal>ngx_http_upstream_peer_t.peer</literal> object | |
4430 of type <literal>ngx_peer_connection_t</literal>: | |
4431 <programlisting> | |
4432 struct ngx_peer_connection_s { | |
4433 [...] | |
4434 | |
4435 struct sockaddr *sockaddr; | |
4436 socklen_t socklen; | |
4437 ngx_str_t *name; | |
4438 | |
4439 ngx_uint_t tries; | |
4440 | |
4441 ngx_event_get_peer_pt get; | |
4442 ngx_event_free_peer_pt free; | |
4443 ngx_event_notify_peer_pt notify; | |
4444 void *data; | |
4445 | |
4446 #if (NGX_SSL || NGX_COMPAT) | |
4447 ngx_event_set_peer_session_pt set_session; | |
4448 ngx_event_save_peer_session_pt save_session; | |
4449 #endif | |
4450 | |
4451 [..] | |
4452 }; | |
4453 </programlisting> | |
4454 | |
4455 The structure has the following fields: | |
4456 | |
4457 <list type="bullet"> | |
4458 <listitem> | |
4459 <literal>sockaddr</literal>, <literal>socklen</literal>, | |
4460 <literal>name</literal> — address of an upstream server to connect to; | |
4461 this is the output parameter of a load balancing method | |
4462 </listitem> | |
4463 | |
4464 <listitem> | |
4465 <literal>data</literal> — per-request load balancing method data; keeps the | |
4466 state of selection algorithm and usually includes the link to upstream | |
4467 configuration. | |
4468 It will be passed as an argument to all methods that deal with server selection | |
4469 (see below) | |
4470 </listitem> | |
4471 | |
4472 <listitem> | |
4473 <literal>tries</literal> — allowed | |
4474 <link doc="../http/ngx_http_proxy_module.xml" id="proxy_next_upstream_tries">number</link> | |
4475 of attempts to connect to an upstream. | |
4476 </listitem> | |
4477 | |
4478 <listitem> | |
4479 <literal>get</literal>, <literal>free</literal>, <literal>notify</literal>, | |
4480 <literal>set_session</literal>, and <literal>save_session</literal> | |
4481 - methods of the load balancing module, see description below | |
4482 </listitem> | |
4483 | |
4484 </list> | |
4485 | |
4486 </para> | |
4487 | |
4488 <para> | |
4489 All methods accept at least two arguments: peer connection object | |
4490 <literal>pc</literal> and the <literal>data</literal> created by | |
4491 <literal>ngx_http_upstream_srv_conf_t.peer.init()</literal>. | |
4492 Note that in general case it may differ from <literal>pc.data</literal> due | |
4493 to “chaining” of load balancing modules. | |
4494 </para> | |
4495 | |
4496 <para> | |
4497 | |
4498 <list type="bullet"> | |
4499 <listitem> | |
4500 <literal>get(pc, data)</literal> — the method is called when the upstream | |
4501 module is ready to pass a request to an upstream server and needs to know | |
4502 its address. | |
4503 The method is responsible to fill in the <literal>sockaddr</literal>, | |
4504 <literal>socklen</literal>, and <literal>name</literal> fields of | |
4505 <literal>ngx_peer_connection_t</literal> structure. | |
4506 The return value may be one of: | |
4507 | |
4508 <list type="bullet"> | |
4509 | |
4510 <listitem> | |
4511 <literal>NGX_OK</literal> — server was selected | |
4512 </listitem> | |
4513 | |
4514 <listitem> | |
4515 <literal>NGX_ERROR</literal> — internal error occurred | |
4516 </listitem> | |
4517 | |
4518 <listitem> | |
4519 <literal>NGX_BUSY</literal> — there are no available servers at the moment. | |
4520 This can happen due to many reasons, such as: dynamic server group is empty, | |
4521 all servers in the group are in the failed state, | |
4522 all servers in the group are already | |
4523 handling the maximum number of connections or similar. | |
4524 </listitem> | |
4525 | |
4526 <listitem> | |
4527 <literal>NGX_DONE</literal> — this is set by the <literal>keepalive</literal> | |
4528 module to indicate that the underlying connection was reused and there is no | |
4529 need to create a new connection to the upstream server. | |
4530 </listitem> | |
4531 | |
4532 <!-- | |
4533 <listitem> | |
4534 <literal>NGX_ABORT</literal> — this is set by the <literal>queue</literal> | |
4535 module to indicate that the request was queued and the further processing | |
4536 of this request should be postponed. | |
4537 </listitem> | |
4538 --> | |
4539 | |
4540 </list> | |
4541 | |
4542 </listitem> | |
4543 | |
4544 <listitem> | |
4545 <literal>free(pc, data, state)</literal> — the method is called when an | |
4546 upstream module has finished work with a particular server. | |
4547 The <literal>state</literal> argument is the status of upstream connection | |
4548 completion. | |
4549 This is a bitmask, the following values may be set: | |
4550 <literal>NGX_PEER_FAILED</literal> — this attempt is considered | |
4551 <link doc="../http/ngx_http_upstream_module.xml" id="max_fails">unsuccessful</link>, | |
4552 <literal>NGX_PEER_NEXT</literal> — a special case with codes 403 and 404 | |
4553 (see link above), which are not considered a failure. | |
4554 <literal>NGX_PEER_KEEPALIVE</literal>. | |
4555 Also, <literal>tries</literal> counter is decremented by this method. | |
4556 </listitem> | |
4557 | |
4558 <listitem> | |
4559 <literal>notify(pc, data, type)</literal> — currently unused | |
4560 in the OSS version. | |
4561 </listitem> | |
4562 | |
4563 <listitem> | |
4564 <literal>set_session(pc, data)</literal> and | |
4565 <literal>save_session(pc, data)</literal> | |
4566 — SSL-specific methods that allow to cache sessions to upstream | |
4567 servers. | |
4568 The implementation is provided by the round-robin balancing method. | |
4569 </listitem> | |
4570 | |
4571 </list> | |
4572 | |
4573 </para> | |
4574 | |
4248 </section> | 4575 </section> |
4249 | 4576 |
4577 </section> | |
4250 | 4578 |
4251 </article> | 4579 </article> |