Модуль ngx_http_grpc_module
Join us for the first quarterly
NGINX Community Call
on July 22nd to connect and discuss NGINX development.
english
русский
новости [en]
об nginx
скачать
безопасность [en]
документация
faq
книги [en]
сообщество
компания
x.com
blog
njs
ingress controller
gateway fabric
Модуль 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_socket_rcvbuf
grpc_socket_sndbuf
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_allow_upstream строка ...;
Умолчание:
—
Контекст:
http, server, location
Эта директива появилась в версии 1.29.3.
Задаёт условия, при которых доступ к 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;
...
}
}
Директива доступна как часть
коммерческой подписки.
Синтаксис:
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_bind_dynamic on | off;
Умолчание:
grpc_bind_dynamic off;
Контекст:
http, server, location
Эта директива появилась в версии 1.29.3.
Если включено, операция bind осуществляется
при каждой попытке соединения.
Директива доступна как часть
коммерческой подписки.
Синтаксис:
grpc_buffer_size размер;
Умолчание:
grpc_buffer_size 4k|8k;
Контекст:
http, server, location
Задаёт размер буфера, в который будет читаться ответ,
получаемый от gRPC-сервера.
В первой части ответа находится, как правило, небольшой заголовок;
если его размер больше заданного, то такой ответ считается
неверным.
Ответ синхронно передаётся клиенту сразу же по мере его поступления.
По умолчанию размер одного буфера равен размеру страницы памяти.
В зависимости от платформы это или 4K, или 8K,
однако его можно сделать меньше.
Синтаксис:
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”.
Если не запрещено, обработка этих полей заголовка заключается в следующем:
“X-Accel-Redirect” производит
внутреннее
перенаправление на указанный URI;
“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 |
denied |
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
произошёл таймаут во время соединения с сервером,
передачи ему запроса или чтения заголовка ответа сервера;
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
никогда не считаются неудачными попытками.
Передача запроса следующему серверу может быть ограничена по
количеству попыток
и по времени.
Синтаксис:
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_request_dynamic on | off;
Умолчание:
grpc_request_dynamic off;
Контекст:
http, server, location
Эта директива появилась в версии 1.29.3.
Разрешает или запрещает создание отдельного экземпляра запроса
для каждого gRPC-сервера.
По умолчанию для всех gRPC-серверов используется единый запрос.
Если разрешено, то для каждого сервера создаётся отдельный экземпляр запроса,
что позволяет кастомизировать запрос для конкретного сервера.
Например каждому серверу можно назначить своё значение
поля “Host” в заголовке запроса:
grpc_request_dynamic on;
grpc_set_header      Host $upstream_last_server_name;
Директива доступна как часть
коммерческой подписки.
Синтаксис:
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_socket_rcvbuf size;
Умолчание:
—
Контекст:
http, server, location
Эта директива появилась в версии 1.31.3.
Задаёт размер буфера приёма
(параметр SO_RCVBUF)
для исходящих соединений к gRPC-серверу.
Специальное значение 0 отменяет действие
унаследованной с предыдущего уровня конфигурации
директивы grpc_socket_rcvbuf, позволяя
использовать настройки операционной системы.
Синтаксис:
grpc_socket_sndbuf size;
Умолчание:
—
Контекст:
http, server, location
Эта директива появилась в версии 1.31.3.
Задаёт размер буфера передачи
(параметр SO_SNDBUF)
для исходящих соединений к gRPC-серверу.
Специальное значение 0 отменяет действие
унаследованной с предыдущего уровня конфигурации
директивы grpc_socket_sndbuf, позволяя
использовать настройки операционной системы.
Синтаксис:
grpc_ssl_certificate файл;
Умолчание:
—
Контекст:
http, server, location
Задаёт файл с сертификатом в формате PEM
для аутентификации на gRPC SSL-сервере.
Начиная с версии 1.21.0 в имени файла можно использовать переменные.
Синтаксис:
grpc_ssl_certificate_cache off;
grpc_ssl_certificate_cache
max=N
[inactive=время]
[valid=время];
Умолчание:
grpc_ssl_certificate_cache off;
Контекст:
http, server, location
Эта директива появилась в версии 1.27.4.
Задаёт кэш, в котором могут храниться
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;
Синтаксис:
grpc_ssl_certificate_key файл;
Умолчание:
—
Контекст:
http, server, location
Задаёт файл с секретным ключом в формате PEM
для аутентификации на gRPC SSL-сервере.
Вместо файла можно указать значение
engine:имя:id,
которое загружает ключ с указанным id
из OpenSSL engine с заданным именем.
Вместо файла можно указать значение
store:схема:id (1.29.0),
которое используется для загрузки ключа с указанным id
и зарегистрированной провайдером OpenSSL схемой URI, такой как
pkcs11.
Начиная с версии 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-сервера.
Если используются промежуточные сертификаты,
их списки CRL должны находиться в этом же файле.
Синтаксис:
grpc_ssl_key_log путь;
Умолчание:
—
Контекст:
http, server, location
Эта директива появилась в версии 1.27.2.
Включает логирование SSL-ключей соединений с gRPC SSL-сервером
и указывает путь к лог-файлу ключей.
Ключи записываются в формате
SSLKEYLOGFILE
совместимом с Wireshark.
Директива доступна как часть
коммерческой подписки.
Синтаксис:
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.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-сервером.
Если в логах появляются ошибки
“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-сервера.