gRPC#

Позволяет передавать запросы gRPC-серверу.

Важно

Для работы этого модуля необходим модуль HTTP2.

Пример конфигурации#

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_connection_drop#

Синтаксис

grpc_connection_drop время | on | off;

По умолчанию

grpc_connection_drop off;

Контекст

http, server, location

Настраивает завершение всех соединений с проксируемым сервером, если он был удален из группы или помечен как постоянно недоступный в результате процесса reresolve или команды API DELETE.

Соединение завершается, когда обрабатывается следующее событие чтения или записи для клиента или проксируемого сервера.

Установка времени включает таймаут до завершения соединения; при выборе значения on соединения завершаются немедленно.

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

Разрешает или запрещает передачу имени сервера, заданного директивой grpc_ssl_name, через расширение Server Name Indication протокола TLS (SNI, RFC 6066) при установлении соединения с SSL-сервером gRPC.

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-сервера.