Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_upstream_hc_module.xml @ 1945:88477c5d2751

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Moved "health_check" and "match" to ngx_http_upstream_hc_module.
author Yaroslav Zhuravlev <yar@nginx.com>
date Thu, 30 Mar 2017 21:26:44 +0300
parents xml/en/docs/http/ngx_http_upstream_module.xml@a58b35cc0823
children 37df1535ea91
comparison
equal deleted inserted replaced
1944:dbf6f05f0808 1945:88477c5d2751
1 <?xml version="1.0"?>
2
3 <!--
4 Copyright (C) Nginx, Inc.
5 -->
6
7 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
8
9 <module name="Module ngx_http_upstream_hc_module"
10 link="/en/docs/http/ngx_http_upstream_hc_module.html"
11 lang="en"
12 rev="1">
13
14 <section id="summary">
15
16 <para>
17 The <literal>ngx_http_upstream_hc_module</literal> module
18 allows enabling periodic health checks of the servers in a
19 <link doc="ngx_http_upstream_module.xml" id="upstream">group</link>
20 referenced in the surrounding location.
21 </para>
22
23 <para>
24 <note>
25 This module is available as part of our
26 <commercial_version>commercial subscription</commercial_version>.
27 </note>
28 </para>
29
30 </section>
31
32
33 <section id="example" name="Example Configuration">
34
35 <para>
36 <example>
37 upstream dynamic {
38 zone upstream_dynamic 64k;
39
40 server backend1.example.com weight=5;
41 server backend2.example.com:8080 fail_timeout=5s slow_start=30s;
42 server 192.0.2.1 max_fails=3;
43
44 server backup1.example.com:8080 backup;
45 server backup2.example.com:8080 backup;
46 }
47
48 server {
49 location / {
50 proxy_pass http://dynamic;
51 health_check;
52 }
53 }
54 </example>
55 </para>
56
57 </section>
58
59
60 <section id="directives" name="Directives">
61
62 <directive name="health_check">
63 <syntax>[<value>parameters</value>]</syntax>
64 <default/>
65 <context>location</context>
66
67 <para>
68 Enables periodic health checks of the servers in a
69 <link doc="ngx_http_upstream_module.xml" id="upstream">group</link>
70 referenced in the surrounding location.
71 </para>
72
73 <para>
74 The following optional parameters are supported:
75 <list type="tag">
76
77 <tag-name id="interval">
78 <literal>interval</literal>=<value>time</value>
79 </tag-name>
80 <tag-desc>
81 sets the interval between two consecutive health checks,
82 by default, 5 seconds.
83 </tag-desc>
84
85 <tag-name id="health_check_jitter">
86 <literal>jitter</literal>=<value>time</value>
87 </tag-name>
88 <tag-desc>
89 sets the time within which
90 each health check will be randomly delayed,
91 by default, there is no delay.
92 </tag-desc>
93
94 <tag-name id="fails">
95 <literal>fails</literal>=<value>number</value>
96 </tag-name>
97 <tag-desc>
98 sets the number of consecutive failed health checks of a particular server
99 after which this server will be considered unhealthy,
100 by default, 1.
101 </tag-desc>
102
103 <tag-name id="passes">
104 <literal>passes</literal>=<value>number</value>
105 </tag-name>
106 <tag-desc>
107 sets the number of consecutive passed health checks of a particular server
108 after which the server will be considered healthy,
109 by default, 1.
110 </tag-desc>
111
112 <tag-name id="uri">
113 <literal>uri</literal>=<value>uri</value>
114 </tag-name>
115 <tag-desc>
116 defines the URI used in health check requests,
117 by default, “<literal>/</literal>”.
118 </tag-desc>
119
120 <tag-name id="health_check_mandatory">
121 <literal>mandatory</literal>
122 </tag-name>
123 <tag-desc>
124 sets the initial “checking” state for a server
125 until the first health check is completed (1.11.7).
126 If the parameter is not specified,
127 the server will be initially considered healthy.
128 </tag-desc>
129
130 <tag-name id="hc_match">
131 <literal>match</literal>=<value>name</value>
132 </tag-name>
133 <tag-desc>
134 specifies the <literal>match</literal> block configuring the tests that a
135 response should pass in order for a health check to pass.
136 By default, the response should have status code 2xx or 3xx.
137 </tag-desc>
138
139 <tag-name id="health_check_port">
140 <literal>port</literal>=<value>number</value>
141 </tag-name>
142 <tag-desc>
143 defines the port used when connecting to a server
144 to perform a health check (1.9.7).
145 By default, equals the
146 <link doc="ngx_http_upstream_module.xml" id="server"/> port.
147 </tag-desc>
148
149 </list>
150 </para>
151
152 <para>
153 For example,
154 <example>
155 location / {
156 proxy_pass http://backend;
157 health_check;
158 }
159 </example>
160 will send “<literal>/</literal>” requests to each
161 server in the <literal>backend</literal> group every five seconds.
162 If any communication error or timeout occurs, or a
163 proxied server responds with the status code other than
164 2xx or 3xx, the health check will fail, and the server will
165 be considered unhealthy.
166 Client requests are not passed to unhealthy servers
167 and servers in the “checking” state.
168 </para>
169
170 <para>
171 Health checks can be configured to test the status code of a response,
172 presence of certain header fields and their values,
173 and the body contents.
174 Tests are configured separately using the <link id="match"/> directive
175 and referenced in the <literal>match</literal> parameter.
176 For example:
177 <example>
178 http {
179 server {
180 ...
181 location / {
182 proxy_pass http://backend;
183 health_check match=welcome;
184 }
185 }
186
187 match welcome {
188 status 200;
189 header Content-Type = text/html;
190 body ~ "Welcome to nginx!";
191 }
192 }
193 </example>
194 This configuration shows that in order for a health check to pass, the response
195 to a health check request should succeed,
196 have status 200, content type “<literal>text/html</literal>”,
197 and contain “<literal>Welcome to nginx!</literal>” in the body.
198 </para>
199
200 <para>
201 The server group must reside in the
202 <link doc="ngx_http_upstream_module.xml" id="zone">shared memory</link>.
203 </para>
204
205 <para>
206 If several health checks are defined for the same group of servers,
207 a single failure of any check will make the corresponding server be
208 considered unhealthy.
209 </para>
210
211 <para>
212 <note>
213 Please note that most of the variables will have empty values
214 when used with health checks.
215 </note>
216 </para>
217
218 </directive>
219
220
221 <directive name="match">
222 <syntax block="yes"><value>name</value></syntax>
223 <default/>
224 <context>http</context>
225
226 <para>
227 Defines the named test set used to verify responses to health check requests.
228 </para>
229
230 <para>
231 The following items can be tested in a response:
232 <list type="tag">
233
234 <tag-name><literal>status 200;</literal></tag-name>
235 <tag-desc>status is 200</tag-desc>
236
237 <tag-name><literal>status ! 500;</literal></tag-name>
238 <tag-desc>status is not 500</tag-desc>
239
240 <tag-name><literal>status 200 204;</literal></tag-name>
241 <tag-desc>status is 200 or 204</tag-desc>
242
243 <tag-name><literal>status ! 301 302;</literal></tag-name>
244 <tag-desc>status is neither 301 nor 302</tag-desc>
245
246 <tag-name><literal>status 200-399;</literal></tag-name>
247 <tag-desc>status is in the range from 200 to 399</tag-desc>
248
249 <tag-name><literal>status ! 400-599;</literal></tag-name>
250 <tag-desc>status is not in the range from 400 to 599</tag-desc>
251
252 <tag-name><literal>status 301-303 307;</literal></tag-name>
253 <tag-desc>status is either 301, 302, 303, or 307</tag-desc>
254
255 </list>
256
257 <list type="tag">
258
259 <tag-name><literal>header Content-Type = text/html;</literal></tag-name>
260 <tag-desc>
261 header contains <header>Content-Type</header>
262 with value <literal>text/html</literal>
263 </tag-desc>
264
265 <tag-name><literal>header Content-Type != text/html;</literal></tag-name>
266 <tag-desc>
267 header contains <header>Content-Type</header>
268 with value other than <literal>text/html</literal>
269 </tag-desc>
270
271 <tag-name><literal>header Connection ~ close;</literal></tag-name>
272 <tag-desc>
273 header contains <header>Connection</header>
274 with value matching regular expression <literal>close</literal>
275 </tag-desc>
276
277 <tag-name><literal>header Connection !~ close;</literal></tag-name>
278 <tag-desc>
279 header contains <header>Connection</header>
280 with value not matching regular expression <literal>close</literal>
281 </tag-desc>
282
283 <tag-name><literal>header Host;</literal></tag-name>
284 <tag-desc>header contains <header>Host</header></tag-desc>
285
286 <tag-name><literal>header ! X-Accel-Redirect;</literal></tag-name>
287 <tag-desc>header lacks <header>X-Accel-Redirect</header></tag-desc>
288
289 </list>
290
291 <list type="tag">
292
293 <tag-name><literal>body ~ "Welcome to nginx!";</literal></tag-name>
294 <tag-desc>
295 body matches regular expression “<literal>Welcome to nginx!</literal>”
296 </tag-desc>
297
298 <tag-name><literal>body !~ "Welcome to nginx!";</literal></tag-name>
299 <tag-desc>
300 body does not match regular expression “<literal>Welcome to nginx!</literal>”
301 </tag-desc>
302
303 </list>
304 </para>
305
306 <para>
307 If several tests are specified,
308 the response matches only if it matches all tests.
309 <note>
310 Only the first 256k of the response body are examined.
311 </note>
312 </para>
313
314 <para>
315 Examples:
316 <example>
317 # status is 200, content type is "text/html",
318 # and body contains "Welcome to nginx!"
319 match welcome {
320 status 200;
321 header Content-Type = text/html;
322 body ~ "Welcome to nginx!";
323 }
324 </example>
325
326 <example>
327 # status is not one of 301, 302, 303, or 307, and header does not have "Refresh:"
328 match not_redirect {
329 status ! 301-303 307;
330 header ! Refresh;
331 }
332 </example>
333
334 <example>
335 # status ok and not in maintenance mode
336 match server_ok {
337 status 200-399;
338 body !~ "maintenance mode";
339 }
340 </example>
341
342 </para>
343
344 </directive>
345
346 </section>
347
348 </module>