gRPC#
Позволяет передавать запросы gRPC-серверу.
Важно
Для работы этого модуля необходим модуль HTTP2.
Пример конфигурации#
server {
listen 9000;
http2 on;
location / {
grpc_pass 127.0.0.1:9000;
}
}
Директивы#
grpc_bind#
Задает локальный IP-адрес с необязательным портом, который будет использоваться в исходящих соединениях с gRPC-сервером. В значении параметра допустимо использование переменных. Специальное значение off отменяет действие унаследованной с предыдущего уровня конфигурации директивы grpc_bind, позволяя системе самостоятельно выбирать локальный IP-адрес и порт.
Параметр transparent позволяет задать нелокальный IP-aдрес, который будет использоваться в исходящих соединениях с gRPC-сервером, например, реальный IP-адрес клиента:
grpc_bind $remote_addr transparent;
Для работы параметра обычно требуется запустить рабочие процессы Angie с привилегиями суперпользователя. В Linux это не требуется, так как если указан параметр transparent, то рабочие процессы наследуют capability CAP_NET_RAW из главного процесса.
Важно
Необходимо настроить таблицу маршрутизации ядра для перехвата сетевого трафика с gRPC-сервера.
grpc_buffer_size#
|
|
По умолчанию |
|
http, server, location |
Задает размер буфера, в который будет читаться первая часть ответа, получаемого от gRPC-сервера. Ответ синхронно передается клиенту сразу же по мере его поступления.
grpc_connect_timeout#
|
|
По умолчанию |
|
http, server, location |
Задает таймаут для установления соединения с gRPC-сервером. Необходимо иметь в виду, что этот таймаут обычно не может превышать 75 секунд.
grpc_connection_drop#
|
|
По умолчанию |
|
http, server, location |
Настраивает завершение всех соединений с проксируемым сервером,
если он был удален из группы или помечен как постоянно недоступный
в результате процесса reresolve
или команды API DELETE.
Соединение завершается, когда обрабатывается следующее событие чтения или записи для клиента или проксируемого сервера.
Установка времени включает таймаут до завершения соединения;
при выборе значения on соединения завершаются немедленно.
grpc_hide_header#
По умолчанию Angie не передает клиенту поля заголовка "Date", "Server" и "X-Accel-..." из ответа gRPC-сервера. Директива grpc_hide_header задает дополнительные поля, которые не будут передаваться. Если же передачу полей нужно разрешить, можно воспользоваться директивой grpc_pass_header.
grpc_ignore_headers#
Запрещает обработку некоторых полей заголовка из ответа gRPC-сервера. В директиве можно указать поля "X-Accel-Redirect" и "X-Accel-Charset".
Если не запрещено, обработка этих полей заголовка заключается в следующем:
"X-Accel-Redirect" производит внутреннее перенаправление на указанный URI;
"X-Accel-Charset" задает желаемую кодировку ответа.
grpc_intercept_errors#
|
|
По умолчанию |
|
http, server, location |
Определяет, передавать ли клиенту ответы gRPC-сервера с кодом больше либо равным 300, или же перехватывать их и перенаправлять на обработку Angie с помощью директивы error_page.
grpc_next_upstream#
|
|
По умолчанию |
|
http, server, location |
Определяет, в каких случаях запрос будет передан следующему в группе upstream серверу:
|
произошла ошибка соединения с сервером, передачи ему запроса или чтения заголовка ответа сервера; |
|
произошел таймаут во время соединения с сервером, передачи ему запроса или чтения заголовка ответа сервера; |
|
сервер вернул пустой или неверный ответ; |
|
сервер вернул ответ с кодом 500; |
|
сервер вернул ответ с кодом 502; |
|
сервер вернул ответ с кодом 503; |
|
сервер вернул ответ с кодом 504; |
|
сервер вернул ответ с кодом 403; |
|
сервер вернул ответ с кодом 404; |
|
сервер вернул ответ с кодом 429; |
|
обычно запросы с неидемпотентным методом (POST, LOCK, PATCH) не передаются на другой сервер, если запрос серверу группы уже был отправлен; включение параметра явно разрешает повторять подобные запросы; |
|
запрещает передачу запроса следующему серверу. |
Примечание
Необходимо понимать, что передача запроса следующему серверу возможна только при условии, что клиенту еще ничего не передавалось. То есть, если ошибка или таймаут возникли в середине передачи ответа клиенту, то действие директивы на такой запрос не распространяется.
Директива также определяет, что считается неудачной попыткой работы с сервером.
|
всегда считаются неудачными попытками, даже если они не указаны в директиве |
|
считаются неудачными попытками, только если они указаны в директиве |
|
никогда не считаются неудачными попытками |
Передача запроса следующему серверу может быть ограничена по количеству попыток и по времени.
grpc_next_upstream_timeout#
|
|
По умолчанию |
|
http, server, location |
Ограничивает время, в течение которого возможна передача запроса следующему серверу.
|
отключает это ограничение |
grpc_next_upstream_tries#
|
|
По умолчанию |
|
http, server, location |
Ограничивает число допустимых попыток для передачи запроса следующему серверу.
|
отключает это ограничение |
grpc_pass#
Задает адрес 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). Кроме того, в качестве адреса можно указать группу серверов.
В значении параметра можно использовать переменные. В этом случае, если адрес указан в виде доменного имени, имя ищется среди описанных групп серверов и если не найдено, то определяется с помощью resolver'а.
grpc_pass_header#
Разрешает передавать от gRPC-сервера клиенту запрещенные для передачи поля заголовка.
grpc_read_timeout#
|
|
По умолчанию |
|
http, server, location |
Задает таймаут при чтении ответа gRPC-сервера. Таймаут устанавливается не на всю передачу ответа, а только между двумя операциями чтения. Если по истечении этого времени gRPC-сервер ничего не передаст, соединение закрывается.
grpc_send_timeout#
|
|
По умолчанию |
|
http, server, location |
Задает таймаут при передаче запроса gRPC-серверу. Таймаут устанавливается не на всю передачу запроса, а только между двумя операциями записи. Если по истечении этого времени gRPC-сервер не примет новых данных, соединение закрывается.
grpc_set_header#
|
|
По умолчанию |
|
http, server, location |
Позволяет переопределять или добавлять поля заголовка запроса, передаваемые проксируемому серверу. В качестве значения можно использовать текст, переменные и их комбинации. Директивы наследуются с предыдущего уровня конфигурации при условии, что на данном уровне не описаны свои директивы grpc_set_header.
Если значение поля заголовка — пустая строка, то поле вообще не будет передаваться gRPC-серверу:
grpc_set_header Accept-Encoding "";
grpc_socket_keepalive#
|
|
По умолчанию |
|
http, server, location |
Конфигурирует поведение "TCP keepalive" для исходящих соединений к проксируемому серверу.
|
По умолчанию для сокета действуют настройки операционной системы. |
|
для сокета включается параметр SO_KEEPALIVE |
grpc_ssl_certificate#
Задает файл с сертификатом в формате PEM для аутентификации на gRPC SSL-сервере. В имени файла можно использовать переменные.
grpc_ssl_certificate_key#
Задает файл с секретным ключом в формате PEM для аутентификации на gRPC SSL-сервере.
Вместо файла можно указать значение "engine:имя:id", которое загружает ключ с указанным id из OpenSSL engine с заданным именем.
В имени файла можно использовать переменные.
grpc_ssl_ciphers#
|
|
По умолчанию |
|
http, server, location |
Описывает разрешенные шифры для запросов к gRPC SSL-серверу. Шифры задаются в формате, поддерживаемом библиотекой OpenSSL.
Полный список можно посмотреть с помощью команды "openssl ciphers".
grpc_ssl_conf_command#
Задает произвольные конфигурационные команды OpenSSL при установлении соединения с gRPC SSL-сервером.
Важно
Директива поддерживается при использовании OpenSSL 1.0.2 и выше.
На одном уровне может быть указано несколько директив grpc_ssl_conf_command. Директивы наследуются с предыдущего уровня конфигурации при условии, что на данном уровне не описаны свои директивы grpc_ssl_conf_command.
Осторожно
Следует учитывать, что изменение настроек OpenSSL напрямую может привести к неожиданному поведению.
grpc_ssl_crl#
Указывает файл с отозванными сертификатами (CRL) в формате PEM, используемыми при проверке сертификата gRPC SSL-сервера.
grpc_ssl_name#
|
|
По умолчанию |
|
http, server, location |
Позволяет переопределить имя сервера, используемое при проверке сертификата gRPC SSl-сервера, а также для передачи его через SNI при установлении соединения с gRPC SSL-сервером.
По умолчанию используется имя хоста из grpc_pass.
grpc_ssl_password_file#
Задает файл с паролями от секретных ключей, где каждый пароль указан на отдельной строке. Пароли применяются по очереди в момент загрузки ключа.
grpc_ssl_protocols#
|
|
По умолчанию |
|
http, server, location |
Изменено в версии 1.2.0: Параметр TLSv1.3 добавлен к используемым по умолчанию.
Разрешает указанные протоколы для запросов к gRPC SSL-серверу.
grpc_ssl_server_name#
|
|
По умолчанию |
|
http, server, location |
Разрешает или запрещает передачу имени сервера, заданного директивой grpc_ssl_name, через расширение Server Name Indication протокола TLS (SNI, RFC 6066) при установлении соединения с SSL-сервером gRPC.
grpc_ssl_session_reuse#
|
|
По умолчанию |
|
http, server, location |
Определяет, использовать ли повторно SSL-сессии при работе с gRPC-сервером. Если в логах появляются ошибки "SSL3_GET_FINISHED:digest check failed", то можно попробовать выключить повторное использование сессий.
grpc_ssl_trusted_certificate#
Задает файл с доверенными сертификатами CA в формате PEM, используемыми при проверке сертификата gRPC SSL-сервера.
grpc_ssl_verify#
|
|
По умолчанию |
|
http, server, location |
Разрешает или запрещает проверку сертификата gRPC SSL-сервера.
grpc_ssl_verify_depth#
|
|
По умолчанию |
|
http, server, location |
Устанавливает глубину проверки в цепочке сертификатов gRPC SSL-сервера.