Модуль ngx_http_grpc_module

Модуль 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;
    }
}

Задаёт локальный 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 4k|8k;

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

grpc_connect_timeout 60s;

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

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

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

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

• “X-Accel-Redirect” производит внутреннее перенаправление на указанный URI;
• “X-Accel-Charset” задаёт желаемую кодировку ответа.

grpc_intercept_errors off;

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

grpc_next_upstream error timeout;

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

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 0;

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

grpc_next_upstream_tries 0;

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

Задаёт адрес 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-сервера клиенту запрещённые для передачи поля заголовка.

grpc_read_timeout 60s;

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

grpc_send_timeout 60s;

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

grpc_set_header Content-Length $content_length;

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

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

grpc_set_header Accept-Encoding "";

grpc_socket_keepalive off;

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

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

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

grpc_ssl_certificate_cache off;

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

У директивы есть следующие параметры:

max

задаёт максимальное число элементов в кэше; при переполнении кэша удаляются наименее востребованные элементы (LRU);

inactive

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

valid

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

off

запрещает кэш.

Пример:

grpc_ssl_certificate       $grpc_ssl_server_name.crt;
grpc_ssl_certificate_key   $grpc_ssl_server_name.key;
grpc_ssl_certificate_cache max=1000 inactive=20s valid=1m;

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

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

Вместо файла можно указать значение store:схема:id (1.29.0), которое используется для загрузки ключа с указанным id и зарегистрированной провайдером OpenSSL схемой URI, такой как pkcs11.

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

grpc_ssl_ciphers DEFAULT;

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

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

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

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

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

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

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

Включает логирование SSL-ключей соединений с gRPC SSL-сервером и указывает путь к лог-файлу ключей. Ключи записываются в формате SSLKEYLOGFILE совместимом с Wireshark.

Директива доступна как часть коммерческой подписки.

grpc_ssl_name имя хоста из grpc_pass;

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

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

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

grpc_ssl_protocols TLSv1.2 TLSv1.3;

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

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

grpc_ssl_server_name off;

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

grpc_ssl_session_reuse on;

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

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

grpc_ssl_verify off;

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

grpc_ssl_verify_depth 1;

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