Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_upstream_hc_module.xml @ 1946:37df1535ea91

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Moved info from http "health_check" and "match" to intro.
author Yaroslav Zhuravlev <yar@nginx.com>
date Thu, 30 Mar 2017 21:26:44 +0300
parents 88477c5d2751
children 8f9c685dfabd
comparison
equal deleted inserted replaced
1945:88477c5d2751 1946:37df1535ea91
7 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> 7 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
8 8
9 <module name="Module ngx_http_upstream_hc_module" 9 <module name="Module ngx_http_upstream_hc_module"
10 link="/en/docs/http/ngx_http_upstream_hc_module.html" 10 link="/en/docs/http/ngx_http_upstream_hc_module.html"
11 lang="en" 11 lang="en"
12 rev="1"> 12 rev="2">
13 13
14 <section id="summary"> 14 <section id="summary">
15 15
16 <para> 16 <para>
17 The <literal>ngx_http_upstream_hc_module</literal> module 17 The <literal>ngx_http_upstream_hc_module</literal> module
18 allows enabling periodic health checks of the servers in a 18 allows enabling periodic health checks of the servers in a
19 <link doc="ngx_http_upstream_module.xml" id="upstream">group</link> 19 <link doc="ngx_http_upstream_module.xml" id="upstream">group</link>
20 referenced in the surrounding location. 20 referenced in the surrounding location.
21 The server group must reside in the
22 <link doc="ngx_http_upstream_module.xml" id="zone">shared memory</link>.
23 </para>
24
25 <para>
26 If a health check fails,
27 the server will be considered unhealthy.
28 If several health checks are defined for the same group of servers,
29 a single failure of any check will make the corresponding server be
30 considered unhealthy.
31 Client requests are not passed to unhealthy servers
32 and servers in the “checking” state.
33 </para>
34
35 <para>
36 <note>
37 Please note that most of the variables will have empty values
38 when used with health checks.
39 </note>
21 </para> 40 </para>
22 41
23 <para> 42 <para>
24 <note> 43 <note>
25 This module is available as part of our 44 This module is available as part of our
50 proxy_pass http://dynamic; 69 proxy_pass http://dynamic;
51 health_check; 70 health_check;
52 } 71 }
53 } 72 }
54 </example> 73 </example>
55 </para> 74 With this configuration, nginx will send “<literal>/</literal>” requests to each
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. 75 server in the <literal>backend</literal> group every five seconds.
162 If any communication error or timeout occurs, or a 76 If any communication error or timeout occurs, or a
163 proxied server responds with the status code other than 77 proxied server responds with the status code other than
164 2xx or 3xx, the health check will fail, and the server will 78 2xx or 3xx, the health check will fail, and the server will
165 be considered unhealthy. 79 be considered unhealthy.
166 Client requests are not passed to unhealthy servers
167 and servers in the “checking” state.
168 </para> 80 </para>
169 81
170 <para> 82 <para>
171 Health checks can be configured to test the status code of a response, 83 Health checks can be configured to test the status code of a response,
172 presence of certain header fields and their values, 84 presence of certain header fields and their values,
173 and the body contents. 85 and the body contents.
174 Tests are configured separately using the <link id="match"/> directive 86 Tests are configured separately using the <link id="match"/> directive
175 and referenced in the <literal>match</literal> parameter. 87 and referenced in the <literal>match</literal> parameter
176 For example: 88 of the <link id="health_check"/> directive:
177 <example> 89 <example>
178 http { 90 http {
179 server { 91 server {
180 ... 92 ...
181 location / { 93 location / {
190 body ~ "Welcome to nginx!"; 102 body ~ "Welcome to nginx!";
191 } 103 }
192 } 104 }
193 </example> 105 </example>
194 This configuration shows that in order for a health check to pass, the response 106 This configuration shows that in order for a health check to pass, the response
195 to a health check request should succeed, 107 to a health check request should succeed, have status 200,
196 have status 200, content type “<literal>text/html</literal>”,
197 and contain “<literal>Welcome to nginx!</literal>” in the body. 108 and contain “<literal>Welcome to nginx!</literal>” in the body.
198 </para> 109 </para>
199 110
200 <para> 111 </section>
201 The server group must reside in the 112
202 <link doc="ngx_http_upstream_module.xml" id="zone">shared memory</link>. 113
203 </para> 114 <section id="directives" name="Directives">
204 115
205 <para> 116 <directive name="health_check">
206 If several health checks are defined for the same group of servers, 117 <syntax>[<value>parameters</value>]</syntax>
207 a single failure of any check will make the corresponding server be 118 <default/>
208 considered unhealthy. 119 <context>location</context>
209 </para> 120
210 121 <para>
211 <para> 122 Enables periodic health checks of the servers in a
212 <note> 123 <link doc="ngx_http_upstream_module.xml" id="upstream">group</link>
213 Please note that most of the variables will have empty values 124 referenced in the surrounding location.
214 when used with health checks. 125 </para>
215 </note> 126
127 <para>
128 The following optional parameters are supported:
129 <list type="tag">
130
131 <tag-name id="interval">
132 <literal>interval</literal>=<value>time</value>
133 </tag-name>
134 <tag-desc>
135 sets the interval between two consecutive health checks,
136 by default, 5 seconds.
137 </tag-desc>
138
139 <tag-name id="health_check_jitter">
140 <literal>jitter</literal>=<value>time</value>
141 </tag-name>
142 <tag-desc>
143 sets the time within which
144 each health check will be randomly delayed,
145 by default, there is no delay.
146 </tag-desc>
147
148 <tag-name id="fails">
149 <literal>fails</literal>=<value>number</value>
150 </tag-name>
151 <tag-desc>
152 sets the number of consecutive failed health checks of a particular server
153 after which this server will be considered unhealthy,
154 by default, 1.
155 </tag-desc>
156
157 <tag-name id="passes">
158 <literal>passes</literal>=<value>number</value>
159 </tag-name>
160 <tag-desc>
161 sets the number of consecutive passed health checks of a particular server
162 after which the server will be considered healthy,
163 by default, 1.
164 </tag-desc>
165
166 <tag-name id="uri">
167 <literal>uri</literal>=<value>uri</value>
168 </tag-name>
169 <tag-desc>
170 defines the URI used in health check requests,
171 by default, “<literal>/</literal>”.
172 </tag-desc>
173
174 <tag-name id="health_check_mandatory">
175 <literal>mandatory</literal>
176 </tag-name>
177 <tag-desc>
178 sets the initial “checking” state for a server
179 until the first health check is completed (1.11.7).
180 If the parameter is not specified,
181 the server will be initially considered healthy.
182 </tag-desc>
183
184 <tag-name id="hc_match">
185 <literal>match</literal>=<value>name</value>
186 </tag-name>
187 <tag-desc>
188 specifies the <literal>match</literal> block configuring the tests that a
189 response should pass in order for a health check to pass.
190 By default, the response should have status code 2xx or 3xx.
191 </tag-desc>
192
193 <tag-name id="health_check_port">
194 <literal>port</literal>=<value>number</value>
195 </tag-name>
196 <tag-desc>
197 defines the port used when connecting to a server
198 to perform a health check (1.9.7).
199 By default, equals the
200 <link doc="ngx_http_upstream_module.xml" id="server"/> port.
201 </tag-desc>
202
203 </list>
216 </para> 204 </para>
217 205
218 </directive> 206 </directive>
219 207
220 208