Модуль http_grpc
#
Позволяет передавать запросы gRPC-серверу.
Важно
Для работы этого модуля необходим модуль http_v2.
Пример конфигурации#
server {
listen 9000;
http2 on;
location / {
grpc_pass 127.0.0.1:9000;
}
}
Директивы#
grpc_bind#
- Синтаксис:
grpc_bind
адрес [transparent] | off;- Умолчание:
—
- Контекст:
http, server, location
Задаёт локальный IP-адрес с необязательным портом, который будет использоваться в исходящих соединениях с gRPC-сервером. В значении параметра допустимо использование переменных. Специальное значение off
отменяет действие унаследованной с предыдущего уровня конфигурации директивы grpc_bind, позволяя системе самостоятельно выбирать локальный IP-адрес и порт.
Параметр transparent
позволяет задать нелокальный IP-aдрес, который будет использоваться в исходящих соединениях с gRPC-сервером, например, реальный IP-адрес клиента:
grpc_bind $remote_addr transparent;
Для работы параметра обычно требуется запустить рабочие процессы Angie с привилегиями суперпользователя. В Linux это не требуется, так как если указан параметр transparent, то рабочие процессы наследуют capability CAP_NET_RAW из главного процесса.
Важно
Необходимо настроить таблицу маршрутизации ядра для перехвата сетевого трафика с gRPC-сервера.
grpc_buffer_size#
- Синтаксис:
grpc_buffer_size
размер;- Умолчание:
grpc_buffer_size 4k|8k;
- Контекст:
http, server, location
Задаёт размер буфера, в который будет читаться первая часть ответа, получаемого от gRPC-сервера. Ответ синхронно передаётся клиенту сразу же по мере его поступления.
grpc_connect_timeout#
- Синтаксис:
grpc_connect_timeout
время;- Умолчание:
grpc_connect_timeout 60s;
- Контекст:
http, server, location
Задаёт таймаут для установления соединения с gRPC-сервером. Необходимо иметь в виду, что этот таймаут обычно не может превышать 75 секунд.
grpc_hide_header#
- Синтаксис:
grpc_hide_header
поле;- Умолчание:
—
- Контекст:
http, server, location
По умолчанию Angie не передаёт клиенту поля заголовка “Date”, “Server” и “X-Accel-…” из ответа gRPC-сервера. Директива grpc_hide_header задаёт дополнительные поля, которые не будут передаваться. Если же передачу полей нужно разрешить, можно воспользоваться директивой grpc_pass_header.
grpc_ignore_headers#
- Синтаксис:
grpc_ignore_headers
поле …;- Умолчание:
—
- Контекст:
http, server, location
Запрещает обработку некоторых полей заголовка из ответа gRPC-сервера. В директиве можно указать поля “X-Accel-Redirect” и “X-Accel-Charset”.
Если не запрещено, обработка этих полей заголовка заключается в следующем:
“X-Accel-Redirect” производит внутреннее перенаправление на указанный URI;
“X-Accel-Charset” задаёт желаемую кодировку ответа.
grpc_intercept_errors#
- Синтаксис:
grpc_intercept_errors
on | off;- Умолчание:
grpc_intercept_errors off;
- Контекст:
http, server, location
Определяет, передавать ли клиенту ответы gRPC-сервера с кодом больше либо равным 300, или же перехватывать их и перенаправлять на обработку Angie с помощью директивы error_page.
grpc_next_upstream#
- Синтаксис:
grpc_next_upstream
error | timeout | invalid_header | http_500 | http_502 | http_503 | http_504 | http_403 | http_404 | http_429 | non_idempotent | off …;- Умолчание:
grpc_next_upstream error timeout;
- Контекст:
http, server, location
Определяет, в каких случаях запрос будет передан следующему в группе upstream серверу:
|
произошла ошибка соединения с сервером, передачи ему запроса или чтения заголовка ответа сервера; |
|
произошёл таймаут во время соединения с сервером, передачи ему запроса или чтения заголовка ответа сервера; |
|
сервер вернул пустой или неверный ответ; |
|
сервер вернул ответ с кодом 500; |
|
сервер вернул ответ с кодом 502; |
|
сервер вернул ответ с кодом 503; |
|
сервер вернул ответ с кодом 504; |
|
сервер вернул ответ с кодом 403; |
|
сервер вернул ответ с кодом 404; |
|
сервер вернул ответ с кодом 429; |
|
обычно запросы с неидемпотентным методом (POST, LOCK, PATCH) не передаются на другой сервер, если запрос серверу группы уже был отправлен; включение параметра явно разрешает повторять подобные запросы; |
|
запрещает передачу запроса следующему серверу. |
Примечание
Необходимо понимать, что передача запроса следующему серверу возможна только при условии, что клиенту ещё ничего не передавалось. То есть, если ошибка или таймаут возникли в середине передачи ответа клиенту, то действие директивы на такой запрос не распространяется.
Директива также определяет, что считается неудачной попыткой работы с сервером.
|
всегда считаются неудачными попытками, даже если они не указаны в директиве |
|
считаются неудачными попытками, только если они указаны в директиве |
|
никогда не считаются неудачными попытками |
Передача запроса следующему серверу может быть ограничена по количеству попыток и по времени.
grpc_next_upstream_timeout#
- Синтаксис:
grpc_next_upstream_timeout
время;- Умолчание:
grpc_next_upstream_timeout 0;
- Контекст:
http, server, location
Ограничивает время, в течение которого возможна передача запроса следующему серверу.
|
отключает это ограничение |
grpc_next_upstream_tries#
- Синтаксис:
grpc_next_upstream_tries
число;- Умолчание:
grpc_next_upstream_tries 0;
- Контекст:
http, server, location
Ограничивает число допустимых попыток для передачи запроса следующему серверу.
|
отключает это ограничение |
grpc_pass#
- Синтаксис:
grpc_pass
адрес;- Умолчание:
—
- Контекст:
location, if в location
Задаёт адрес gRPC-сервера. Адрес может быть указан в виде доменного имени или IP-адреса, и порта:
grpc_pass localhost:9000;
или в виде пути UNIX-сокета:
grpc_pass unix:/tmp/grpc.socket;
Также может использоваться схема “grpc://”:
grpc_pass grpc://127.0.0.1:9000;
Для использования gRPC по SSL необходимо использовать схему “grpcs://”:
grpc_pass grpcs://127.0.0.1:443;
Если доменному имени соответствует несколько адресов, то все они будут использоваться по очереди (round-robin). Кроме того, в качестве адреса можно указать группу серверов.
В значении параметра можно использовать переменные. В этом случае, если адрес указан в виде доменного имени, имя ищется среди описанных групп серверов и если не найдено, то определяется с помощью resolver’а.
grpc_pass_header#
- Синтаксис:
grpc_pass_header
поле;- Умолчание:
—
- Контекст:
http, server, location
Разрешает передавать от gRPC-сервера клиенту запрещённые для передачи поля заголовка.
grpc_read_timeout#
- Синтаксис:
grpc_read_timeout
время;- Умолчание:
grpc_read_timeout 60s;
- Контекст:
http, server, location
Задаёт таймаут при чтении ответа gRPC-сервера. Таймаут устанавливается не на всю передачу ответа, а только между двумя операциями чтения. Если по истечении этого времени gRPC-сервер ничего не передаст, соединение закрывается.
grpc_send_timeout#
- Синтаксис:
grpc_send_timeout
время;- Умолчание:
grpc_send_timeout 60s;
- Контекст:
http, server, location
Задаёт таймаут при передаче запроса gRPC-серверу. Таймаут устанавливается не на всю передачу запроса, а только между двумя операциями записи. Если по истечении этого времени gRPC-сервер не примет новых данных, соединение закрывается.
grpc_set_header#
- Синтаксис:
grpc_set_header
поле значение;- Умолчание:
grpc_set_header Content-Length $content_length;
- Контекст:
http, server, location
Позволяет переопределять или добавлять поля заголовка запроса, передаваемые проксируемому серверу. В качестве значения можно использовать текст, переменные и их комбинации. Директивы наследуются с предыдущего уровня конфигурации при условии, что на данном уровне не описаны свои директивы grpc_set_header.
Если значение поля заголовка — пустая строка, то поле вообще не будет передаваться gRPC-серверу:
grpc_set_header Accept-Encoding "";
grpc_socket_keepalive#
- Синтаксис:
grpc_socket_keepalive
on | off;- Умолчание:
grpc_socket_keepalive off;
- Контекст:
http, server, location
Конфигурирует поведение “TCP keepalive” для исходящих соединений к проксируемому серверу.
|
По умолчанию для сокета действуют настройки операционной системы. |
|
для сокета включается параметр SO_KEEPALIVE |
grpc_ssl_certificate#
- Синтаксис:
grpc_ssl_certificate
файл;- Умолчание:
—
- Контекст:
http, server, location
Задаёт файл с сертификатом в формате PEM для аутентификации на gRPC SSL-сервере. В имени файла можно использовать переменные.
grpc_ssl_certificate_key#
- Синтаксис:
grpc_ssl_certificate_key
файл;- Умолчание:
—
- Контекст:
http, server, location
Задаёт файл с секретным ключом в формате PEM для аутентификации на gRPC SSL-сервере.
Вместо файла можно указать значение “engine:имя:id“, которое загружает ключ с указанным id из OpenSSL engine с заданным именем.
В имени файла можно использовать переменные.
grpc_ssl_ciphers#
- Синтаксис:
grpc_ssl_ciphers
шифры;- Умолчание:
grpc_ssl_ciphers DEFAULT;
- Контекст:
http, server, location
Описывает разрешённые шифры для запросов к gRPC SSL-серверу. Шифры задаются в формате, поддерживаемом библиотекой OpenSSL.
Полный список можно посмотреть с помощью команды “openssl ciphers”.
grpc_ssl_conf_command#
- Синтаксис:
grpc_ssl_conf_command
имя значение;- Умолчание:
—
- Контекст:
http, server, location
Задаёт произвольные конфигурационные команды OpenSSL при установлении соединения с gRPC SSL-сервером.
Важно
Директива поддерживается при использовании OpenSSL 1.0.2 и выше.
На одном уровне может быть указано несколько директив grpc_ssl_conf_command. Директивы наследуются с предыдущего уровня конфигурации при условии, что на данном уровне не описаны свои директивы grpc_ssl_conf_command.
Осторожно
Следует учитывать, что изменение настроек OpenSSL напрямую может привести к неожиданному поведению.
grpc_ssl_crl#
- Синтаксис:
grpc_ssl_crl
файл;- Умолчание:
—
- Контекст:
http, server, location
Указывает файл с отозванными сертификатами (CRL) в формате PEM, используемыми при проверке сертификата gRPC SSL-сервера.
grpc_ssl_name#
- Синтаксис:
grpc_ssl_name
имя;- Умолчание:
grpc_ssl_name `имя хоста
из grpc_pass;`- Контекст:
http, server, location
Позволяет переопределить имя сервера, используемое при проверке сертификата gRPC SSl-сервера, а также для передачи его через SNI при установлении соединения с gRPC SSL-сервером.
По умолчанию используется имя хоста из grpc_pass.
grpc_ssl_password_file#
- Синтаксис:
grpc_ssl_password_file
файл;- Умолчание:
—
- Контекст:
http, server, location
Задаёт файл с паролями от секретных ключей, где каждый пароль указан на отдельной строке. Пароли применяются по очереди в момент загрузки ключа.
grpc_ssl_protocols#
- Синтаксис:
grpc_ssl_protocols
[SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];- Умолчание:
grpc_ssl_protocols TLSv1 TLSv1.1 TLSv1.2 TLSv1.3;
- Контекст:
http, server, location
Изменено в версии 1.2.0: Параметр TLSv1.3
добавлен к используемым по умолчанию.
Разрешает указанные протоколы для запросов к gRPC SSL-серверу.
grpc_ssl_server_name#
- Синтаксис:
grpc_ssl_server_name
on | off;- Умолчание:
grpc_ssl_server_name off;
- Контекст:
http, server, location
Разрешает или запрещает передачу имени сервера через расширение Server Name Indication протокола TLS (SNI, RFC 6066) при установлении соединения с gRPC SSL-сервером.
grpc_ssl_session_reuse#
- Синтаксис:
grpc_ssl_session_reuse
on | off;- Умолчание:
grpc_ssl_session_reuse on;
- Контекст:
http, server, location
Определяет, использовать ли повторно SSL-сессии при работе с gRPC-сервером. Если в логах появляются ошибки “SSL3_GET_FINISHED:digest check failed”, то можно попробовать выключить повторное использование сессий.
grpc_ssl_trusted_certificate#
- Синтаксис:
grpc_ssl_trusted_certificate
файл;- Умолчание:
—
- Контекст:
http, server, location
Задаёт файл с доверенными сертификатами CA в формате PEM, используемыми при проверке сертификата gRPC SSL-сервера.
grpc_ssl_verify#
- Синтаксис:
grpc_ssl_verify
on | off;- Умолчание:
grpc_ssl_verify off;
- Контекст:
http, server, location
Разрешает или запрещает проверку сертификата gRPC SSL-сервера.
grpc_ssl_verify_depth#
- Синтаксис:
grpc_ssl_verify_depth
число;- Умолчание:
grpc_ssl_verify_depth 1;
- Контекст:
http, server, location
Устанавливает глубину проверки в цепочке сертификатов gRPC SSL-сервера.