Модуль 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”.

Если не запрещено, обработка этих полей заголовка заключается в следующем:

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 серверу:

error

произошла ошибка соединения с сервером, передачи ему запроса или чтения заголовка ответа сервера;

timeout

произошёл таймаут во время соединения с сервером, передачи ему запроса или чтения заголовка ответа сервера;

invalid_header

сервер вернул пустой или неверный ответ;

http_500

сервер вернул ответ с кодом 500;

http_502

сервер вернул ответ с кодом 502;

http_503

сервер вернул ответ с кодом 503;

http_504

сервер вернул ответ с кодом 504;

http_403

сервер вернул ответ с кодом 403;

http_404

сервер вернул ответ с кодом 404;

http_429

сервер вернул ответ с кодом 429;

non_idempotent

обычно запросы с неидемпотентным методом (POST, LOCK, PATCH) не передаются на другой сервер, если запрос серверу группы уже был отправлен; включение параметра явно разрешает повторять подобные запросы;

off

запрещает передачу запроса следующему серверу.

Примечание

Необходимо понимать, что передача запроса следующему серверу возможна только при условии, что клиенту ещё ничего не передавалось. То есть, если ошибка или таймаут возникли в середине передачи ответа клиенту, то действие директивы на такой запрос не распространяется.

Директива также определяет, что считается неудачной попыткой работы с сервером.

error
timeout
invalid_header

всегда считаются неудачными попытками, даже если они не указаны в директиве

http_500
http_502
http_503
http_504
http_429

считаются неудачными попытками, только если они указаны в директиве

http_403
http_404

никогда не считаются неудачными попытками

Передача запроса следующему серверу может быть ограничена по количеству попыток и по времени.

grpc_next_upstream_timeout#

Синтаксис:

grpc_next_upstream_timeout время;

Умолчание:

grpc_next_upstream_timeout 0;

Контекст:

http, server, location

Ограничивает время, в течение которого возможна передача запроса следующему серверу.

0

отключает это ограничение

grpc_next_upstream_tries#

Синтаксис:

grpc_next_upstream_tries число;

Умолчание:

grpc_next_upstream_tries 0;

Контекст:

http, server, location

Ограничивает число допустимых попыток для передачи запроса следующему серверу.

0

отключает это ограничение

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” для исходящих соединений к проксируемому серверу.

""

По умолчанию для сокета действуют настройки операционной системы.

on

для сокета включается параметр 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-сервера.