Mercurial > hg > nginx-site

comparison xml/en/docs/dev/development_guide.xml @ 1939:c1b0169e8f54

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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>