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

Директивы

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

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

grpc_bind $remote_addr transparent;

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

Устанавливает размер буфера для чтения ответа, полученного от сервера gRPC. Ответ передается клиенту синхронно, как только он получен.

Определяет таймаут для установления соединения с сервером 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 с кодами, большими или равными 300, передаваться клиенту или перехватываться и перенаправляться в nginx для обработки с помощью директивы error_page.

Указывает в каких случаях запрос должен быть передан следующему серверу:

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) не передаются следующему серверу, если запрос был отправлен серверу upstream; включение этого параметра явно разрешает повторную отправку таких запросов;

off

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

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

Директива также определяет, что считается неудачной попыткой связи с сервером. Случаи error, timeout и invalid_header всегда считаются неудачными попытками, даже если они не указаны в директиве. Случаи http_500, http_502, http_503, http_504, и http_429 считаются неудачными попытками только если они указаны в директиве. Случаи http_403 и http_404 никогда не считаются неудачными попытками.

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

Ограничивает время, в течение которого запрос может быть передан следующему серверу. Значение 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;

Если доменное имя разрешается в несколько адресов, все они будут использоваться в циклическом порядке. Кроме того, адрес может быть указан как группа серверов.

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

Разрешает передачу полей заголовков с gRPC-сервера клиенту, которые в противном случае были бы отключены.

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

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

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

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

grpc_set_header Accept-Encoding "";

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

Указывает file с сертификатом в формате PEM, используемым для аутентификации на gRPC-SSL-сервере.

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

Указывает file с закрытым ключом в формате PEM, используемым для аутентификации на gRPC-SSL-сервере.

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

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

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

Полный список можно просмотреть, используя команду «openssl ciphers».

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

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

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

Обратите внимание, что настройка OpenSSL напрямую может привести к неожиданному поведению.

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

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

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

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

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

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

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

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

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

Включает или отключает проверку сертификата gRPC-SSL-сервера.

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