Mercurial > hg > nginx-site
comparison xml/en/docs/http/ngx_http_upstream_hc_module.xml @ 1946:37df1535ea91
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 |