Модуль ngx_http_grpc_module

Пример конфигурации
Директивы
     grpc_bind
     grpc_buffer_size
     grpc_connect_timeout
     grpc_hide_header
     grpc_ignore_headers
     grpc_intercept_errors
     grpc_next_upstream
     grpc_next_upstream_timeout
     grpc_next_upstream_tries
     grpc_pass
     grpc_pass_header
     grpc_read_timeout
     grpc_send_timeout
     grpc_set_header
     grpc_socket_keepalive
     grpc_ssl_certificate
     grpc_ssl_certificate_key
     grpc_ssl_ciphers
     grpc_ssl_conf_command
     grpc_ssl_crl
     grpc_ssl_name
     grpc_ssl_password_file
     grpc_ssl_protocols
     grpc_ssl_server_name
     grpc_ssl_session_reuse
     grpc_ssl_trusted_certificate
     grpc_ssl_verify
     grpc_ssl_verify_depth

Модуль ngx_http_grpc_module позволяет передавать запросы gRPC-серверу (1.13.10). Для работы этого модуля необходим модуль ngx_http_v2_module.

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

server {
    listen 9000;

    http2 on;

    location / {
        grpc_pass 127.0.0.1:9000;
    }
}

Директивы

Синтаксис: grpc_bind адрес [transparent ] | off;
Умолчание:
Контекст: http, server, location

Задаёт локальный IP-адрес с необязательным портом, который будет использоваться в исходящих соединениях с gRPC-сервером. В значении параметра допустимо использование переменных. Специальное значение off отменяет действие унаследованной с предыдущего уровня конфигурации директивы grpc_bind, позволяя системе самостоятельно выбирать локальный IP-адрес и порт.

Параметр transparent позволяет задать нелокальный IP-aдрес, который будет использоваться в исходящих соединениях с gRPC-сервером, например, реальный IP-адрес клиента:

grpc_bind $remote_addr transparent;

Для работы параметра обычно требуется запустить рабочие процессы nginx с привилегиями суперпользователя. В Linux этого не требуется, так как если указан параметр transparent, то рабочие процессы наследуют capability CAP_NET_RAW из главного процесса. Также необходимо настроить таблицу маршрутизации ядра для перехвата сетевого трафика с gRPC-сервера.

Синтаксис: grpc_buffer_size размер;
Умолчание:
grpc_buffer_size 4k|8k;
Контекст: http, server, location

Задаёт размер буфера, в который будет читаться ответ, получаемый от gRPC-сервера. Ответ синхронно передаётся клиенту сразу же по мере его поступления.

Синтаксис: grpc_connect_timeout время;
Умолчание:
grpc_connect_timeout 60s;
Контекст: http, server, location

Задаёт таймаут для установления соединения с gRPC-сервером. Необходимо иметь в виду, что этот таймаут обычно не может превышать 75 секунд.

Синтаксис: grpc_hide_header поле;
Умолчание:
Контекст: http, server, location

По умолчанию nginx не передаёт клиенту поля заголовка “Date”, “Server” и “X-Accel-...” из ответа gRPC-сервера. Директива grpc_hide_header задаёт дополнительные поля, которые не будут передаваться. Если же передачу полей нужно разрешить, можно воспользоваться директивой grpc_pass_header.

Синтаксис: grpc_ignore_headers поле ...;
Умолчание:
Контекст: http, server, location

Запрещает обработку некоторых полей заголовка из ответа gRPC-сервера. В директиве можно указать поля “X-Accel-Redirect” и “X-Accel-Charset”.

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

Синтаксис: grpc_intercept_errors on | off;
Умолчание:
grpc_intercept_errors off;
Контекст: http, server, location

Определяет, передавать ли клиенту ответы gRPC-сервера с кодом больше либо равным 300, или же перехватывать их и перенаправлять на обработку nginx’у с помощью директивы error_page.

Синтаксис: 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

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

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 0;
Контекст: http, server, location

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

Синтаксис: grpc_next_upstream_tries число;
Умолчание:
grpc_next_upstream_tries 0;
Контекст: http, server, location

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

Синтаксис: 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). И, кроме того, адрес может быть группой серверов.

В значении параметра можно использовать переменные (1.17.8). В этом случае, если адрес указан в виде доменного имени, имя ищется среди описанных групп серверов и если не найдено, то определяется с помощью resolver’а.

Синтаксис: grpc_pass_header поле;
Умолчание:
Контекст: http, server, location

Разрешает передавать от gRPC-сервера клиенту запрещённые для передачи поля заголовка.

Синтаксис: grpc_read_timeout время;
Умолчание:
grpc_read_timeout 60s;
Контекст: http, server, location

Задаёт таймаут при чтении ответа gRPC-сервера. Таймаут устанавливается не на всю передачу ответа, а только между двумя операциями чтения. Если по истечении этого времени gRPC-сервер ничего не передаст, соединение закрывается.

Синтаксис: grpc_send_timeout время;
Умолчание:
grpc_send_timeout 60s;
Контекст: http, server, location

Задаёт таймаут при передаче запроса gRPC-серверу. Таймаут устанавливается не на всю передачу запроса, а только между двумя операциями записи. Если по истечении этого времени gRPC-сервер не примет новых данных, соединение закрывается.

Синтаксис: grpc_set_header поле значение;
Умолчание:
grpc_set_header Content-Length $content_length;
Контекст: http, server, location

Позволяет переопределять или добавлять поля заголовка запроса, передаваемые gRPC-серверу. В качестве значения можно использовать текст, переменные и их комбинации. Директивы наследуются с предыдущего уровня конфигурации при условии, что на данном уровне не описаны свои директивы grpc_set_header.

Если значение поля заголовка — пустая строка, то поле вообще не будет передаваться gRPC-серверу:

grpc_set_header Accept-Encoding "";

Синтаксис: grpc_socket_keepalive on | off;
Умолчание:
grpc_socket_keepalive off;
Контекст: http, server, location

Эта директива появилась в версии 1.15.6.

Конфигурирует поведение “TCP keepalive” для исходящих соединений к gRPC-серверу. По умолчанию для сокета действуют настройки операционной системы. Если указано значение “on”, то для сокета включается параметр SO_KEEPALIVE.

Синтаксис: grpc_ssl_certificate файл;
Умолчание:
Контекст: http, server, location

Задаёт файл с сертификатом в формате PEM для аутентификации на gRPC SSL-сервере.

Начиная с версии 1.21.0 в имени файла можно использовать переменные.

Синтаксис: grpc_ssl_certificate_key файл;
Умолчание:
Контекст: http, server, location

Задаёт файл с секретным ключом в формате PEM для аутентификации на gRPC SSL-сервере.

Вместо файла можно указать значение engine:имя:id, которое загружает ключ с указанным id из OpenSSL engine с заданным именем.

Начиная с версии 1.21.0 в имени файла можно использовать переменные.

Синтаксис: grpc_ssl_ciphers шифры;
Умолчание:
grpc_ssl_ciphers DEFAULT;
Контекст: http, server, location

Описывает разрешённые шифры для запросов к gRPC SSL-серверу. Шифры задаются в формате, поддерживаемом библиотекой OpenSSL.

Полный список можно посмотреть с помощью команды “openssl ciphers”.

Синтаксис: grpc_ssl_conf_command имя значение;
Умолчание:
Контекст: http, server, location

Эта директива появилась в версии 1.19.4.

Задаёт произвольные конфигурационные команды OpenSSL при установлении соединения с gRPC SSL-сервером.

Директива поддерживается при использовании OpenSSL 1.0.2 и выше.

На одном уровне может быть указано несколько директив grpc_ssl_conf_command. Директивы наследуются с предыдущего уровня конфигурации при условии, что на данном уровне не описаны свои директивы grpc_ssl_conf_command.

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

Синтаксис: grpc_ssl_crl файл;
Умолчание:
Контекст: http, server, location

Указывает файл с отозванными сертификатами (CRL) в формате PEM, используемыми при проверке сертификата gRPC SSL-сервера.

Синтаксис: grpc_ssl_name имя;
Умолчание:
grpc_ssl_name имя хоста из grpc_pass;
Контекст: http, server, location

Позволяет переопределить имя сервера, используемое при проверке сертификата gRPC SSL-сервера, а также для передачи его через SNI при установлении соединения с gRPC SSL-сервером.

По умолчанию используется имя хоста из grpc_pass.

Синтаксис: grpc_ssl_password_file файл;
Умолчание:
Контекст: http, server, location

Задаёт файл с паролями от секретных ключей, где каждый пароль указан на отдельной строке. Пароли применяются по очереди в момент загрузки ключа.

Синтаксис: 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

Разрешает указанные протоколы для запросов к gRPC SSL-серверу.

Параметр TLSv1.3 используется по умолчанию начиная с 1.23.4.

Синтаксис: 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 on | off;
Умолчание:
grpc_ssl_session_reuse on;
Контекст: http, server, location

Определяет, использовать ли повторно SSL-сессии при работе с gRPC-сервером. Если в логах появляются ошибки “SSL3_GET_FINISHED:digest check failed”, то можно попробовать выключить повторное использование сессий.

Синтаксис: grpc_ssl_trusted_certificate файл;
Умолчание:
Контекст: http, server, location

Задаёт файл с доверенными сертификатами CA в формате PEM, используемыми при проверке сертификата gRPC SSL-сервера.

Синтаксис: grpc_ssl_verify on | off;
Умолчание:
grpc_ssl_verify off;
Контекст: http, server, location

Разрешает или запрещает проверку сертификата gRPC SSL-сервера.

Синтаксис: grpc_ssl_verify_depth число;
Умолчание:
grpc_ssl_verify_depth 1;
Контекст: http, server, location

Устанавливает глубину проверки в цепочке сертификатов gRPC SSL-сервера.