Mercurial > hg > nginx-site
diff 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 |
line wrap: on
line diff
--- a/xml/en/docs/dev/development_guide.xml +++ b/xml/en/docs/dev/development_guide.xml @@ -4245,7 +4245,335 @@ code, the denial code will become the fi </section> + +<section name="Load balancing" id="http_load_balancing"> + +<para> +The +<link doc="../http/ngx_http_upstream_module.xml">ngx_http_upstream_module</link> +provides basic functionality to pass requests to remote servers. +This functionality is used by modules that implement specific protocols, +such as HTTP or FastCGI. +The module also provides an interface for creating custom +load balancing modules and implements a default round-robin balancing method. +</para> + +<para> +Examples of modules that implement alternative load balancing methods are +<link doc="../http/ngx_http_upstream_module.xml" id="least_conn"/> +and <link doc="../http/ngx_http_upstream_module.xml" id="hash"/>. +Note that these modules are actually implemented as extensions of the upstream +module and share a lot of code, such as representation of a server group. +The <link doc="../http/ngx_http_upstream_module.xml" id="keepalive"/> module +is an example of an independent module, extending upstream functionality. +</para> + +<para> +The +<link doc="../http/ngx_http_upstream_module.xml">ngx_http_upstream_module</link> +may be configured explicitly by placing the corresponding +<link doc="../http/ngx_http_upstream_module.xml" id="upstream"/> block into +the configuration file, or implicitly by using directives +that accept a URL evaluated at some point to the list of servers, +for example, +<link doc="../http/ngx_http_proxy_module.xml" id="proxy_pass"/>. +Only explicit configurations may use an alternative load balancing method. +The upstream module configuration has its own directive context +<literal>NGX_HTTP_UPS_CONF</literal>. +The structure is defined as follows: +<programlisting> +struct ngx_http_upstream_srv_conf_s { + ngx_http_upstream_peer_t peer; + void **srv_conf; + + ngx_array_t *servers; /* ngx_http_upstream_server_t */ + + ngx_uint_t flags; + ngx_str_t host; + u_char *file_name; + ngx_uint_t line; + in_port_t port; + ngx_uint_t no_port; /* unsigned no_port:1 */ + +#if (NGX_HTTP_UPSTREAM_ZONE) + ngx_shm_zone_t *shm_zone; +#endif +}; +</programlisting> + +<list type="bullet"> + +<listitem> +<literal>srv_conf</literal> — configuration context of upstream modules +</listitem> + +<listitem> +<literal>servers</literal> — array of +<literal>ngx_http_upstream_server_t</literal>, the result of parsing a set of +<link doc="../http/ngx_http_upstream_module.xml" id="server"/> directives +in the <literal>upstream</literal> block +</listitem> + +<listitem> +<literal>flags</literal> — flags that mostly mark which features +(configured as parameters of +the <link doc="../http/ngx_http_upstream_module.xml" id="server"/> directive) +are supported by the particular load balancing method. + +<list type="bullet"> + +<listitem> +<literal>NGX_HTTP_UPSTREAM_CREATE</literal> — used to distinguish explicitly +defined upstreams from automatically created by +<link doc="../http/ngx_http_proxy_module.xml" id="proxy_pass"/> and “friends” +(FastCGI, SCGI, etc.) +</listitem> + +<listitem> +<literal>NGX_HTTP_UPSTREAM_WEIGHT</literal> — “<literal>weight</literal>” +is supported +</listitem> + +<listitem> +<literal>NGX_HTTP_UPSTREAM_MAX_FAILS</literal> — “<literal>max_fails</literal>” +is supported +</listitem> + +<listitem> +<literal>NGX_HTTP_UPSTREAM_FAIL_TIMEOUT</literal> — +“<literal>fail_timeout</literal>” is supported +</listitem> + +<listitem> +<literal>NGX_HTTP_UPSTREAM_DOWN</literal> — “<literal>down</literal>” +is supported +</listitem> + +<listitem> +<literal>NGX_HTTP_UPSTREAM_BACKUP</literal> — “<literal>backup</literal>” +is supported +</listitem> + +<listitem> +<literal>NGX_HTTP_UPSTREAM_MAX_CONNS</literal> — “<literal>max_conns</literal>” +is supported +</listitem> + +</list> + +</listitem> + +<listitem> +<literal>host</literal> — the name of an upstream +</listitem> + +<listitem> +<literal>file_name, line</literal> — the name of the configuration file +and the line where the <literal>upstream</literal> block is located +</listitem> + +<listitem> +<literal>port</literal> and <literal>no_port</literal> — unused by explicit +upstreams +</listitem> + +<listitem> +<literal>shm_zone</literal> — a shared memory zone used by this upstream, if any +</listitem> + +<listitem> +<literal>peer</literal> — an object that holds generic methods for +initializing upstream configuration: + +<programlisting> +typedef struct { + ngx_http_upstream_init_pt init_upstream; + ngx_http_upstream_init_peer_pt init; + void *data; +} ngx_http_upstream_peer_t; +</programlisting> +A module that implements a load balancing algorithm must set these +methods and initialize private <literal>data</literal>. +If <literal>init_upstream</literal> was not initialized during configuration +parsing, <literal>ngx_http_upstream_module</literal> sets it to default +<literal>ngx_http_upstream_init_round_robin</literal>. + +<list type="bullet"> +<listitem> +<literal>init_upstream(cf, us)</literal> — configuration-time +method responsible for initializing a group of servers and +initializing the <literal>init()</literal> method in case of success. +A typical load balancing module uses a list of servers in the upstream block +to create some efficient data structure that it uses and saves own +configuration to the <literal>data</literal> field. +</listitem> + +<listitem> +<literal>init(r, us)</literal> — initializes per-request +<literal>ngx_http_upstream_peer_t.peer</literal> (not to be confused with the +<literal>ngx_http_upstream_srv_conf_t.peer</literal> described above which +is per-upstream) structure that is used for load balancing. +It will be passed as <literal>data</literal> argument to all callbacks that +deal with server selection. +</listitem> +</list> + +</listitem> +</list> +</para> + +<para> +When nginx has to pass a request to another host for processing, it uses +a configured load balancing method to obtain an address to connect to. +The method is taken from the +<literal>ngx_http_upstream_peer_t.peer</literal> object +of type <literal>ngx_peer_connection_t</literal>: +<programlisting> +struct ngx_peer_connection_s { + [...] + + struct sockaddr *sockaddr; + socklen_t socklen; + ngx_str_t *name; + + ngx_uint_t tries; + + ngx_event_get_peer_pt get; + ngx_event_free_peer_pt free; + ngx_event_notify_peer_pt notify; + void *data; + +#if (NGX_SSL || NGX_COMPAT) + ngx_event_set_peer_session_pt set_session; + ngx_event_save_peer_session_pt save_session; +#endif + + [..] +}; +</programlisting> + +The structure has the following fields: + +<list type="bullet"> +<listitem> +<literal>sockaddr</literal>, <literal>socklen</literal>, +<literal>name</literal> — address of an upstream server to connect to; +this is the output parameter of a load balancing method +</listitem> + +<listitem> +<literal>data</literal> — per-request load balancing method data; keeps the +state of selection algorithm and usually includes the link to upstream +configuration. +It will be passed as an argument to all methods that deal with server selection +(see below) +</listitem> + +<listitem> +<literal>tries</literal> — allowed +<link doc="../http/ngx_http_proxy_module.xml" id="proxy_next_upstream_tries">number</link> +of attempts to connect to an upstream. +</listitem> + +<listitem> +<literal>get</literal>, <literal>free</literal>, <literal>notify</literal>, +<literal>set_session</literal>, and <literal>save_session</literal> +- methods of the load balancing module, see description below +</listitem> + +</list> + +</para> + +<para> +All methods accept at least two arguments: peer connection object +<literal>pc</literal> and the <literal>data</literal> created by +<literal>ngx_http_upstream_srv_conf_t.peer.init()</literal>. +Note that in general case it may differ from <literal>pc.data</literal> due +to “chaining” of load balancing modules. +</para> + +<para> + +<list type="bullet"> +<listitem> +<literal>get(pc, data)</literal> — the method is called when the upstream +module is ready to pass a request to an upstream server and needs to know +its address. +The method is responsible to fill in the <literal>sockaddr</literal>, +<literal>socklen</literal>, and <literal>name</literal> fields of +<literal>ngx_peer_connection_t</literal> structure. +The return value may be one of: + +<list type="bullet"> + +<listitem> +<literal>NGX_OK</literal> — server was selected +</listitem> + +<listitem> +<literal>NGX_ERROR</literal> — internal error occurred +</listitem> + +<listitem> +<literal>NGX_BUSY</literal> — there are no available servers at the moment. +This can happen due to many reasons, such as: dynamic server group is empty, +all servers in the group are in the failed state, +all servers in the group are already +handling the maximum number of connections or similar. +</listitem> + +<listitem> +<literal>NGX_DONE</literal> — this is set by the <literal>keepalive</literal> +module to indicate that the underlying connection was reused and there is no +need to create a new connection to the upstream server. +</listitem> + +<!-- +<listitem> +<literal>NGX_ABORT</literal> — this is set by the <literal>queue</literal> +module to indicate that the request was queued and the further processing +of this request should be postponed. +</listitem> +--> + +</list> + +</listitem> + +<listitem> +<literal>free(pc, data, state)</literal> — the method is called when an +upstream module has finished work with a particular server. +The <literal>state</literal> argument is the status of upstream connection +completion. +This is a bitmask, the following values may be set: +<literal>NGX_PEER_FAILED</literal> — this attempt is considered +<link doc="../http/ngx_http_upstream_module.xml" id="max_fails">unsuccessful</link>, +<literal>NGX_PEER_NEXT</literal> — a special case with codes 403 and 404 +(see link above), which are not considered a failure. +<literal>NGX_PEER_KEEPALIVE</literal>. +Also, <literal>tries</literal> counter is decremented by this method. +</listitem> + +<listitem> +<literal>notify(pc, data, type)</literal> — currently unused +in the OSS version. +</listitem> + +<listitem> +<literal>set_session(pc, data)</literal> and +<literal>save_session(pc, data)</literal> +— SSL-specific methods that allow to cache sessions to upstream +servers. +The implementation is provided by the round-robin balancing method. +</listitem> + +</list> + +</para> + </section> +</section> </article>