Модуль ngx_http_grpc_module

• Пример конфигурации
• Директивы
• grpc_allow_upstream
• grpc_bind
• grpc_bind_dynamic
• 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_request_dynamic
• grpc_send_timeout
• grpc_set_header
• grpc_socket_keepalive
• grpc_ssl_certificate
• grpc_ssl_certificate_cache
• grpc_ssl_certificate_key
• grpc_ssl_ciphers
• grpc_ssl_conf_command
• grpc_ssl_crl
• grpc_ssl_key_log
• 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 разрешён или запрещён. Если все строковые параметры не пусты и не равны «0», доступ разрешён. Условия проверяются каждый раз перед установлением соединения с сервером gRPC. Значения параметров могут содержать переменные:

geo $upstream_last_addr $allow {
    volatile;
    10.10.0.0/24        1;
}

server {
    listen 127.0.0.1:8080;
    http2 on;

    location / {
        grpc_pass           localhost:9000;
        grpc_allow_upstream $allow;
        ...
    }
}

Эта директива доступна в рамках нашей коммерческой подписки.

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

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

grpc_bind $remote_addr transparent;

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

Если директива включена, операция bind выполняется при каждой попытке установить соединение.

Эта директива доступна в рамках нашей коммерческой подписки.

Задаёт size буфера, используемого для чтения ответа, полученного от сервера gRPC. Первая часть ответа обычно содержит небольшой заголовок; если он превышает размер буфера, ответ считается недопустимым. Ответ передаётся клиенту синхронно, сразу после получения. По умолчанию размер буфера равен размеру одной страницы памяти. В зависимости от платформы он составляет 4K или 8K. При необходимости его можно уменьшить.

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

По умолчанию nginx не передаёт клиенту из ответа сервера gRPC поля заголовка «Date», «Server» и «X-Accel-...». Директива 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

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

denied

сервер отказал в соединении (1.29.3);

Этот параметр доступен в рамках нашей коммерческой подписки.

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, denied и 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 используется один запрос. Если эта возможность включена, создаётся отдельный экземпляр запроса, что позволяет настраивать запросы для каждого сервера. Например, можно задать поле заголовка запроса «Host» для конкретного сервера:

grpc_request_dynamic on;
grpc_set_header      Host $upstream_last_server_name;

Эта директива доступна в рамках нашей коммерческой подписки.

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

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

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

grpc_set_header Accept-Encoding "";

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

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

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

Определяет кэш для хранения 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;

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

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

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

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

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

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

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

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

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

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

Задаёт file со списком отозванных сертификатов (CRL) в формате PEM, используемый для проверки сертификата SSL-сервера gRPC. При использовании промежуточных сертификатов их CRL следует указать в том же файле.

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

Эта директива доступна в рамках нашей коммерческой подписки.

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

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

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

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

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

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

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

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

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

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