Mercurial > hg > nginx-site
comparison xml/ru/docs/http/ngx_http_grpc_module.xml @ 2114:b7dd3e8ee9c2
Documented the gRPC proxy module.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Fri, 16 Mar 2018 21:46:19 +0300 |
parents | xml/ru/docs/http/ngx_http_memcached_module.xml@a9a9a052b5bd |
children | ca7568f67dee |
comparison
equal
deleted
inserted
replaced
2113:180269c4a220 | 2114:b7dd3e8ee9c2 |
---|---|
1 <?xml version="1.0"?> | |
2 | |
3 <!-- | |
4 Copyright (C) Igor Sysoev | |
5 Copyright (C) Nginx, Inc. | |
6 --> | |
7 | |
8 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> | |
9 | |
10 <module name="Модуль ngx_http_grpc_module" | |
11 link="/ru/docs/http/ngx_http_grpc_module.html" | |
12 lang="ru" | |
13 rev="1"> | |
14 | |
15 <section id="summary"> | |
16 | |
17 <para> | |
18 Модуль <literal>ngx_http_grpc_module</literal> позволяет передавать запросы | |
19 gRPC-серверу (1.13.10). | |
20 Для работы этого модуля необходим | |
21 модуль <link doc="ngx_http_v2_module.xml">ngx_http_v2_module</link>. | |
22 </para> | |
23 | |
24 </section> | |
25 | |
26 | |
27 <section id="example" name="Пример конфигурации"> | |
28 | |
29 <para> | |
30 <example> | |
31 server { | |
32 listen 9000 http2; | |
33 | |
34 location / { | |
35 grpc_pass 127.0.0.1:9000; | |
36 } | |
37 } | |
38 </example> | |
39 </para> | |
40 | |
41 </section> | |
42 | |
43 | |
44 <section id="directives" name="Директивы"> | |
45 | |
46 <directive name="grpc_bind"> | |
47 <syntax> | |
48 <value>адрес</value> | |
49 [<literal>transparent </literal>] | | |
50 <literal>off</literal></syntax> | |
51 <default/> | |
52 <context>http</context> | |
53 <context>server</context> | |
54 <context>location</context> | |
55 | |
56 <para> | |
57 Задаёт локальный IP-адрес с необязательным портом, | |
58 который будет использоваться в исходящих соединениях с gRPC-сервером. | |
59 В значении параметра допустимо использование переменных. | |
60 Специальное значение <literal>off</literal> отменяет действие | |
61 унаследованной с предыдущего уровня конфигурации | |
62 директивы <literal>grpc_bind</literal>, позволяя системе | |
63 самостоятельно выбирать локальный IP-адрес и порт. | |
64 </para> | |
65 | |
66 <para id="grpc_bind_transparent"> | |
67 Параметр <literal>transparent</literal> позволяет | |
68 задать нелокальный IP-aдрес, который будет использоваться в | |
69 исходящих соединениях с gRPC-сервером, | |
70 например, реальный IP-адрес клиента: | |
71 <example> | |
72 grpc_bind $remote_addr transparent; | |
73 </example> | |
74 Для работы параметра | |
75 обычно требуется | |
76 запустить рабочие процессы nginx с привилегиями | |
77 <link doc="../ngx_core_module.xml" id="user">суперпользователя</link>. | |
78 В Linux этого не требуется, так как если | |
79 указан параметр <literal>transparent</literal>, то рабочие процессы | |
80 наследуют capability <literal>CAP_NET_RAW</literal> из главного процесса. | |
81 Также необходимо настроить таблицу маршрутизации ядра | |
82 для перехвата сетевого трафика с gRPC-сервера. | |
83 </para> | |
84 | |
85 </directive> | |
86 | |
87 | |
88 <directive name="grpc_buffer_size"> | |
89 <syntax><value>размер</value></syntax> | |
90 <default>4k|8k</default> | |
91 <context>http</context> | |
92 <context>server</context> | |
93 <context>location</context> | |
94 | |
95 <para> | |
96 Задаёт <value>размер</value> буфера, в который будет читаться ответ, | |
97 получаемый от gRPC-сервера. | |
98 Ответ синхронно передаётся клиенту сразу же по мере его поступления. | |
99 </para> | |
100 | |
101 </directive> | |
102 | |
103 | |
104 <directive name="grpc_connect_timeout"> | |
105 <syntax><value>время</value></syntax> | |
106 <default>60s</default> | |
107 <context>http</context> | |
108 <context>server</context> | |
109 <context>location</context> | |
110 | |
111 <para> | |
112 Задаёт таймаут для установления соединения с gRPC-сервером. | |
113 Необходимо иметь в виду, что этот таймаут обычно не может превышать 75 секунд. | |
114 </para> | |
115 | |
116 </directive> | |
117 | |
118 | |
119 <directive name="grpc_hide_header"> | |
120 <syntax><value>поле</value></syntax> | |
121 <default/> | |
122 <context>http</context> | |
123 <context>server</context> | |
124 <context>location</context> | |
125 | |
126 <para> | |
127 По умолчанию | |
128 nginx не передаёт клиенту поля заголовка <header>Date</header>, | |
129 <header>Server</header> и | |
130 <header>X-Accel-...</header> из ответа gRPC-сервера. | |
131 Директива <literal>grpc_hide_header</literal> задаёт дополнительные поля, | |
132 которые не будут передаваться. | |
133 Если же передачу полей нужно разрешить, можно воспользоваться | |
134 директивой <link id="grpc_pass_header"/>. | |
135 </para> | |
136 | |
137 </directive> | |
138 | |
139 | |
140 <directive name="grpc_ignore_headers"> | |
141 <syntax><value>поле</value> ...</syntax> | |
142 <default/> | |
143 <context>http</context> | |
144 <context>server</context> | |
145 <context>location</context> | |
146 | |
147 <para> | |
148 Запрещает обработку некоторых полей заголовка из ответа gRPC-сервера. | |
149 В директиве можно указать поля <header>X-Accel-Redirect</header> | |
150 и <header>X-Accel-Charset</header>. | |
151 </para> | |
152 | |
153 <para> | |
154 Если не запрещено, обработка этих полей заголовка заключается в следующем: | |
155 <list type="bullet" compact="no"> | |
156 | |
157 <listitem> | |
158 <header>X-Accel-Redirect</header> производит | |
159 <link doc="ngx_http_core_module.xml" id="internal">внутреннее | |
160 перенаправление</link> на указанный URI; | |
161 </listitem> | |
162 | |
163 <listitem> | |
164 <header>X-Accel-Charset</header> задаёт желаемую | |
165 <link doc="ngx_http_charset_module.xml" id="charset">кодировку</link> | |
166 ответа. | |
167 </listitem> | |
168 | |
169 </list> | |
170 </para> | |
171 | |
172 </directive> | |
173 | |
174 | |
175 <directive name="grpc_intercept_errors"> | |
176 <syntax><literal>on</literal> | <literal>off</literal></syntax> | |
177 <default>off</default> | |
178 <context>http</context> | |
179 <context>server</context> | |
180 <context>location</context> | |
181 | |
182 <para> | |
183 Определяет, передавать ли клиенту ответы gRPC-сервера с кодом | |
184 больше либо равным 300, | |
185 или же перехватывать их и перенаправлять на обработку nginx’у с помощью | |
186 директивы <link doc="ngx_http_core_module.xml" id="error_page"/>. | |
187 </para> | |
188 | |
189 </directive> | |
190 | |
191 | |
192 <directive name="grpc_next_upstream"> | |
193 <syntax> | |
194 <literal>error</literal> | | |
195 <literal>timeout</literal> | | |
196 <literal>invalid_header</literal> | | |
197 <literal>http_500</literal> | | |
198 <literal>http_502</literal> | | |
199 <literal>http_503</literal> | | |
200 <literal>http_504</literal> | | |
201 <literal>http_403</literal> | | |
202 <literal>http_404</literal> | | |
203 <literal>http_429</literal> | | |
204 <literal>non_idempotent</literal> | | |
205 <literal>off</literal> | |
206 ...</syntax> | |
207 <default>error timeout</default> | |
208 <context>http</context> | |
209 <context>server</context> | |
210 <context>location</context> | |
211 | |
212 <para> | |
213 Определяет, в каких случаях запрос будет передан следующему серверу: | |
214 <list type="tag"> | |
215 | |
216 <tag-name><literal>error</literal></tag-name> | |
217 <tag-desc>произошла ошибка соединения с сервером, передачи ему запроса или | |
218 чтения заголовка ответа сервера;</tag-desc> | |
219 | |
220 <tag-name><literal>timeout</literal></tag-name> | |
221 <tag-desc>произошёл таймаут во время соединения с сервером, | |
222 передачи ему запроса или чтения заголовка ответа сервера;</tag-desc> | |
223 | |
224 <tag-name><literal>invalid_header</literal></tag-name> | |
225 <tag-desc>сервер вернул пустой или неверный ответ;</tag-desc> | |
226 | |
227 <tag-name><literal>http_500</literal></tag-name> | |
228 <tag-desc>сервер вернул ответ с кодом 500;</tag-desc> | |
229 | |
230 <tag-name><literal>http_502</literal></tag-name> | |
231 <tag-desc>сервер вернул ответ с кодом 502;</tag-desc> | |
232 | |
233 <tag-name><literal>http_503</literal></tag-name> | |
234 <tag-desc>сервер вернул ответ с кодом 503;</tag-desc> | |
235 | |
236 <tag-name><literal>http_504</literal></tag-name> | |
237 <tag-desc>сервер вернул ответ с кодом 504;</tag-desc> | |
238 | |
239 <tag-name><literal>http_403</literal></tag-name> | |
240 <tag-desc>сервер вернул ответ с кодом 403;</tag-desc> | |
241 | |
242 <tag-name><literal>http_404</literal></tag-name> | |
243 <tag-desc>сервер вернул ответ с кодом 404;</tag-desc> | |
244 | |
245 <tag-name><literal>http_429</literal></tag-name> | |
246 <tag-desc>сервер вернул ответ с кодом 429;</tag-desc> | |
247 | |
248 <tag-name id="non_idempotent"><literal>non_idempotent</literal></tag-name> | |
249 <tag-desc>обычно запросы с | |
250 <link url="https://tools.ietf.org/html/rfc7231#section-4.2.2">неидемпотентным</link> | |
251 методом | |
252 (<literal>POST</literal>, <literal>LOCK</literal>, <literal>PATCH</literal>) | |
253 не передаются на другой сервер, | |
254 если запрос серверу группы уже был отправлен; | |
255 включение параметра явно разрешает повторять подобные запросы; | |
256 </tag-desc> | |
257 | |
258 | |
259 <tag-name><literal>off</literal></tag-name> | |
260 <tag-desc>запрещает передачу запроса следующему серверу.</tag-desc> | |
261 | |
262 </list> | |
263 </para> | |
264 | |
265 <para> | |
266 Необходимо понимать, что передача запроса следующему серверу возможна | |
267 только при условии, что клиенту ещё ничего не передавалось. | |
268 То есть, если ошибка или таймаут возникли в середине передачи ответа, | |
269 то исправить это уже невозможно. | |
270 </para> | |
271 | |
272 <para> | |
273 Директива также определяет, что считается | |
274 <link doc="ngx_http_upstream_module.xml" id="max_fails">неудачной | |
275 попыткой</link> работы с сервером. | |
276 Случаи <literal>error</literal>, <literal>timeout</literal> и | |
277 <literal>invalid_header</literal> | |
278 всегда считаются неудачными попытками, даже если они не указаны в директиве. | |
279 Случаи <literal>http_500</literal>, <literal>http_502</literal>, | |
280 <literal>http_503</literal>, <literal>http_504</literal> | |
281 и <literal>http_429</literal> | |
282 считаются неудачными попытками, только если они указаны в директиве. | |
283 Случаи <literal>http_403</literal> и <literal>http_404</literal> | |
284 никогда не считаются неудачными попытками. | |
285 </para> | |
286 | |
287 <para> | |
288 Передача запроса следующему серверу может быть ограничена по | |
289 <link id="grpc_next_upstream_tries">количеству попыток</link> | |
290 и по <link id="grpc_next_upstream_timeout">времени</link>. | |
291 </para> | |
292 | |
293 </directive> | |
294 | |
295 | |
296 <directive name="grpc_next_upstream_timeout"> | |
297 <syntax><value>время</value></syntax> | |
298 <default>0</default> | |
299 <context>http</context> | |
300 <context>server</context> | |
301 <context>location</context> | |
302 | |
303 <para> | |
304 Ограничивает время, в течение которого возможна передача запроса | |
305 <link id="grpc_next_upstream">следующему серверу</link>. | |
306 Значение <literal>0</literal> отключает это ограничение. | |
307 </para> | |
308 | |
309 </directive> | |
310 | |
311 | |
312 <directive name="grpc_next_upstream_tries"> | |
313 <syntax><value>число</value></syntax> | |
314 <default>0</default> | |
315 <context>http</context> | |
316 <context>server</context> | |
317 <context>location</context> | |
318 | |
319 <para> | |
320 Ограничивает число допустимых попыток для передачи запроса | |
321 <link id="grpc_next_upstream">следующему серверу</link>. | |
322 Значение <literal>0</literal> отключает это ограничение. | |
323 </para> | |
324 | |
325 </directive> | |
326 | |
327 | |
328 <directive name="grpc_pass"> | |
329 <syntax><value>адрес</value></syntax> | |
330 <default/> | |
331 <context>location</context> | |
332 <context>if в location</context> | |
333 | |
334 <para> | |
335 Задаёт адрес gRPC-сервера. | |
336 Адрес может быть указан в виде доменного имени или IP-адреса, | |
337 и порта: | |
338 <example> | |
339 grpc_pass localhost:9000; | |
340 </example> | |
341 или в виде пути UNIX-сокета: | |
342 <example> | |
343 grpc_pass unix:/tmp/grpc.socket; | |
344 </example> | |
345 Также может использоваться схема “<literal>grpc://</literal>”: | |
346 <example> | |
347 grpc_pass grpc://127.0.0.1:9000; | |
348 </example> | |
349 Для использования gRPC по SSL необходимо использовать схему | |
350 “<literal>grpcs://</literal>”: | |
351 <example> | |
352 grpc_pass grpcs://127.0.0.1:443; | |
353 </example> | |
354 </para> | |
355 | |
356 <para> | |
357 Если доменному имени соответствует несколько адресов, то все они будут | |
358 использоваться по очереди (round-robin). | |
359 И, кроме того, адрес может быть | |
360 <link doc="ngx_http_upstream_module.xml">группой серверов</link>. | |
361 </para> | |
362 | |
363 </directive> | |
364 | |
365 | |
366 <directive name="grpc_pass_header"> | |
367 <syntax><value>поле</value></syntax> | |
368 <default/> | |
369 <context>http</context> | |
370 <context>server</context> | |
371 <context>location</context> | |
372 | |
373 <para> | |
374 Разрешает передавать от gRPC-сервера клиенту | |
375 <link id="grpc_hide_header">запрещённые для передачи</link> поля заголовка. | |
376 </para> | |
377 | |
378 </directive> | |
379 | |
380 | |
381 <directive name="grpc_read_timeout"> | |
382 <syntax><value>время</value></syntax> | |
383 <default>60s</default> | |
384 <context>http</context> | |
385 <context>server</context> | |
386 <context>location</context> | |
387 | |
388 <para> | |
389 Задаёт таймаут при чтении ответа gRPC-сервера. | |
390 Таймаут устанавливается не на всю передачу ответа, | |
391 а только между двумя операциями чтения. | |
392 Если по истечении этого времени gRPC-сервер ничего не передаст, | |
393 соединение закрывается. | |
394 </para> | |
395 | |
396 </directive> | |
397 | |
398 | |
399 <directive name="grpc_send_timeout"> | |
400 <syntax><value>время</value></syntax> | |
401 <default>60s</default> | |
402 <context>http</context> | |
403 <context>server</context> | |
404 <context>location</context> | |
405 | |
406 <para> | |
407 Задаёт таймаут при передаче запроса gRPC-серверу. | |
408 Таймаут устанавливается не на всю передачу запроса, | |
409 а только между двумя операциями записи. | |
410 Если по истечении этого времени gRPC-сервер не примет новых данных, | |
411 соединение закрывается. | |
412 </para> | |
413 | |
414 </directive> | |
415 | |
416 | |
417 <directive name="grpc_set_header"> | |
418 <syntax><value>поле</value> <value>значение</value></syntax> | |
419 <default>Content-Length $content_length</default> | |
420 <context>http</context> | |
421 <context>server</context> | |
422 <context>location</context> | |
423 | |
424 <para> | |
425 Позволяет переопределять или добавлять поля заголовка запроса, | |
426 <link id="proxy_pass_request_headers">передаваемые</link> gRPC-серверу. | |
427 В качестве значения можно использовать текст, переменные и их комбинации. | |
428 Директивы наследуются с предыдущего уровня при условии, что на данном | |
429 уровне не описаны свои директивы <literal>grpc_set_header</literal>. | |
430 </para> | |
431 | |
432 <para> | |
433 Если значение поля заголовка — пустая строка, то поле вообще | |
434 не будет передаваться gRPC-серверу: | |
435 <example> | |
436 grpc_set_header Accept-Encoding ""; | |
437 </example> | |
438 </para> | |
439 | |
440 </directive> | |
441 | |
442 | |
443 <directive name="grpc_ssl_certificate"> | |
444 <syntax><value>файл</value></syntax> | |
445 <default/> | |
446 <context>http</context> | |
447 <context>server</context> | |
448 <context>location</context> | |
449 | |
450 <para> | |
451 Задаёт <value>файл</value> с сертификатом в формате PEM | |
452 для аутентификации на gRPC SSL-сервере. | |
453 </para> | |
454 | |
455 </directive> | |
456 | |
457 | |
458 <directive name="grpc_ssl_certificate_key"> | |
459 <syntax><value>файл</value></syntax> | |
460 <default/> | |
461 <context>http</context> | |
462 <context>server</context> | |
463 <context>location</context> | |
464 | |
465 <para> | |
466 Задаёт <value>файл</value> с секретным ключом в формате PEM | |
467 для аутентификации на gRPC SSL-сервере. | |
468 </para> | |
469 | |
470 <para> | |
471 Вместо <value>файла</value> можно указать значение | |
472 <literal>engine</literal>:<value>имя</value>:<value>id</value>, | |
473 которое загружает ключ с указанным <value>id</value> | |
474 из OpenSSL engine с заданным <value>именем</value>. | |
475 </para> | |
476 | |
477 </directive> | |
478 | |
479 | |
480 <directive name="grpc_ssl_ciphers"> | |
481 <syntax><value>шифры</value></syntax> | |
482 <default>DEFAULT</default> | |
483 <context>http</context> | |
484 <context>server</context> | |
485 <context>location</context> | |
486 | |
487 <para> | |
488 Описывает разрешённые шифры для запросов к gRPC SSL-серверу. | |
489 Шифры задаются в формате, поддерживаемом библиотекой OpenSSL. | |
490 </para> | |
491 | |
492 <para> | |
493 Полный список можно посмотреть с помощью команды | |
494 “<command>openssl ciphers</command>”. | |
495 </para> | |
496 | |
497 </directive> | |
498 | |
499 | |
500 <directive name="grpc_ssl_crl"> | |
501 <syntax><value>файл</value></syntax> | |
502 <default/> | |
503 <context>http</context> | |
504 <context>server</context> | |
505 <context>location</context> | |
506 | |
507 <para> | |
508 Указывает <value>файл</value> с отозванными сертификатами (CRL) | |
509 в формате PEM, используемыми при <link id="proxy_ssl_verify">проверке</link> | |
510 сертификата gRPC SSL-сервера. | |
511 </para> | |
512 | |
513 </directive> | |
514 | |
515 | |
516 <directive name="grpc_ssl_name"> | |
517 <syntax><value>имя</value></syntax> | |
518 <default>имя хоста из grpc_pass</default> | |
519 <context>http</context> | |
520 <context>server</context> | |
521 <context>location</context> | |
522 | |
523 <para> | |
524 Позволяет переопределить имя сервера, используемое при | |
525 <link id="grpc_ssl_verify">проверке</link> | |
526 сертификата gRPC SSL-сервера, а также для | |
527 <link id="grpc_ssl_server_name">передачи его через SNI</link> | |
528 при установлении соединения с gRPC SSL-сервером. | |
529 </para> | |
530 | |
531 <para> | |
532 По умолчанию используется имя хоста из <link id="grpc_pass"/>. | |
533 </para> | |
534 | |
535 </directive> | |
536 | |
537 | |
538 <directive name="grpc_ssl_password_file"> | |
539 <syntax><value>файл</value></syntax> | |
540 <default/> | |
541 <context>http</context> | |
542 <context>server</context> | |
543 <context>location</context> | |
544 | |
545 <para> | |
546 Задаёт <value>файл</value> с паролями от | |
547 <link id="grpc_ssl_certificate_key">секретных ключей</link>, | |
548 где каждый пароль указан на отдельной строке. | |
549 Пароли применяются по очереди в момент загрузки ключа. | |
550 </para> | |
551 | |
552 </directive> | |
553 | |
554 | |
555 <directive name="grpc_ssl_server_name"> | |
556 <syntax><literal>on</literal> | <literal>off</literal></syntax> | |
557 <default>off</default> | |
558 <context>http</context> | |
559 <context>server</context> | |
560 <context>location</context> | |
561 | |
562 <para> | |
563 Разрешает или запрещает передачу имени сервера через | |
564 <link url="http://en.wikipedia.org/wiki/Server_Name_Indication">расширение | |
565 Server Name Indication протокола TLS</link> (SNI, RFC 6066) | |
566 при установлении соединения с gRPC SSL-сервером. | |
567 </para> | |
568 | |
569 </directive> | |
570 | |
571 | |
572 <directive name="grpc_ssl_session_reuse"> | |
573 <syntax><literal>on</literal> | <literal>off</literal></syntax> | |
574 <default>on</default> | |
575 <context>http</context> | |
576 <context>server</context> | |
577 <context>location</context> | |
578 | |
579 <para> | |
580 Определяет, использовать ли повторно SSL-сессии при | |
581 работе с gRPC-сервером. | |
582 Если в логах появляются ошибки | |
583 “<literal>SSL3_GET_FINISHED:digest check failed</literal>”, | |
584 то можно попробовать выключить | |
585 повторное использование сессий. | |
586 </para> | |
587 | |
588 </directive> | |
589 | |
590 | |
591 <directive name="grpc_ssl_protocols"> | |
592 <syntax> | |
593 [<literal>SSLv2</literal>] | |
594 [<literal>SSLv3</literal>] | |
595 [<literal>TLSv1</literal>] | |
596 [<literal>TLSv1.1</literal>] | |
597 [<literal>TLSv1.2</literal>] | |
598 [<literal>TLSv1.3</literal>]</syntax> | |
599 <default>TLSv1 TLSv1.1 TLSv1.2</default> | |
600 <context>http</context> | |
601 <context>server</context> | |
602 <context>location</context> | |
603 | |
604 <para> | |
605 Разрешает указанные протоколы для запросов к gRPC SSL-серверу. | |
606 </para> | |
607 | |
608 </directive> | |
609 | |
610 | |
611 <directive name="grpc_ssl_trusted_certificate"> | |
612 <syntax><value>файл</value></syntax> | |
613 <default/> | |
614 <context>http</context> | |
615 <context>server</context> | |
616 <context>location</context> | |
617 | |
618 <para> | |
619 Задаёт <value>файл</value> с доверенными сертификатами CA в формате PEM, | |
620 используемыми при <link id="grpc_ssl_verify">проверке</link> | |
621 сертификата gRPC SSL-сервера. | |
622 </para> | |
623 | |
624 </directive> | |
625 | |
626 | |
627 <directive name="grpc_ssl_verify"> | |
628 <syntax><literal>on</literal> | <literal>off</literal></syntax> | |
629 <default>off</default> | |
630 <context>http</context> | |
631 <context>server</context> | |
632 <context>location</context> | |
633 | |
634 <para> | |
635 Разрешает или запрещает проверку сертификата gRPC SSL-сервера. | |
636 </para> | |
637 | |
638 </directive> | |
639 | |
640 | |
641 <directive name="grpc_ssl_verify_depth"> | |
642 <syntax><value>число</value></syntax> | |
643 <default>1</default> | |
644 <context>http</context> | |
645 <context>server</context> | |
646 <context>location</context> | |
647 | |
648 <para> | |
649 Устанавливает глубину проверки в цепочке сертификатов | |
650 gRPC SSL-сервера. | |
651 </para> | |
652 | |
653 </directive> | |
654 | |
655 </section> | |
656 | |
657 </module> |