gRPC#

Позволяет передавать запросы gRPC-серверу.

Примечание

Для работы этого модуля необходим модуль HTTP2.

При сборке из исходного кода модуль собирается по умолчанию; его можно отключить с помощью параметра сборки --without-http_grpc_module.

В пакетах и образах из наших репозиториев модуль включен в сборку.

Пример конфигурации#

server {
    listen 9000;

    http2 on;

    location / {
        grpc_pass 127.0.0.1:9000;
    }
}

Директивы#

grpc_bind#

Синтаксис	`grpc_bind` адрес [`transparent`] \| `off`;
По умолчанию	—
Контекст	http, server, location

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

По умолчанию это значение вычисляется один раз при инициализации запроса, до выбора gRPC-сервера. В Angie PRO вычисление происходит после каждого выбора gRPC-сервера (в том числе при повторных попытках), поэтому адрес привязки может зависеть от выбранного сервера; например, с помощью переменной $upstream_current_addr. Если вычисленное значение пусто, привязка не выполняется.

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

grpc_bind $remote_addr transparent;

Для работы параметра обычно требуется запустить рабочие процессы Angie с привилегиями суперпользователя. В Linux это не требуется, так как если указан параметр transparent, то рабочие процессы наследуют capability CAP_NET_RAW из главного процесса.

Примечание

Необходимо настроить таблицу маршрутизации ядра для перехвата сетевого трафика с gRPC-сервера.

grpc_buffer_size#

Синтаксис	`grpc_buffer_size` размер;
По умолчанию	`grpc_buffer_size 4k\|8k;`
Контекст	http, server, location

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

grpc_connect_timeout#

Синтаксис	`grpc_connect_timeout` время;
По умолчанию	`grpc_connect_timeout 60s;`
Контекст	http, server, location

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

grpc_connection_drop#

Синтаксис	`grpc_connection_drop` время \| `on` \| `off`;
По умолчанию	`grpc_connection_drop off;`
Контекст	http, server, location

Настраивает завершение всех соединений с проксируемым сервером, если он был удален из группы или помечен как постоянно недоступный в результате процесса reresolve или команды API DELETE.

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

Установка времени включает таймаут до завершения соединения; при выборе значения on соединения завершаются немедленно.

grpc_hide_header#

Синтаксис	`grpc_hide_header` поле;
По умолчанию	—
Контекст	http, server, location

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

grpc_ignore_headers#

Синтаксис	`grpc_ignore_headers` поле ...;
По умолчанию	—
Контекст	http, server, location

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

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

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

grpc_intercept_errors#

Синтаксис	`grpc_intercept_errors` `on` \| `off`;
По умолчанию	`grpc_intercept_errors off;`
Контекст	http, server, location

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

grpc_next_upstream#

Синтаксис	`grpc_next_upstream` `error` \| `timeout` \| `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

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

`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#

Синтаксис	`grpc_next_upstream_timeout` время;
По умолчанию	`grpc_next_upstream_timeout 0;`
Контекст	http, server, location

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

`0`	отключает это ограничение

grpc_next_upstream_tries#

Синтаксис	`grpc_next_upstream_tries` число;
По умолчанию	`grpc_next_upstream_tries 0;`
Контекст	http, server, location

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

`0`	отключает это ограничение

grpc_pass#

Синтаксис	`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). Кроме того, в качестве адреса можно указать группу серверов.

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

Примечание

Если grpc_pass стоит в location с косой чертой в конце префикса (например, location /name/), и при этом в директиве auto_redirect указано default, запросы без косой черты в конце будут перенаправляться (/name -> /name/).

grpc_pass_header#

Синтаксис	`grpc_pass_header` поле;
По умолчанию	—
Контекст	http, server, location

Разрешает передавать от gRPC-сервера клиенту запрещенные для передачи поля заголовка.

grpc_read_timeout#

Синтаксис	`grpc_read_timeout` время;
По умолчанию	`grpc_read_timeout 60s;`
Контекст	http, server, location

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

grpc_send_timeout#

Синтаксис	`grpc_send_timeout` время;
По умолчанию	`grpc_send_timeout 60s;`
Контекст	http, server, location

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

grpc_set_header#

Синтаксис	`grpc_set_header` поле значение;
По умолчанию	`grpc_set_header Content-Length $content_length;`
Контекст	http, server, location

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

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

grpc_set_header Accept-Encoding "";

grpc_socket_keepalive#

Синтаксис	`grpc_socket_keepalive` `on` \| `off`;
По умолчанию	`grpc_socket_keepalive off;`
Контекст	http, server, location

Конфигурирует поведение "TCP keepalive" для исходящих соединений к проксируемому серверу.

`""`	По умолчанию для сокета действуют настройки операционной системы.
`on`	для сокета включается параметр SO_KEEPALIVE

grpc_ssl_certificate#

Синтаксис	`grpc_ssl_certificate` файл;
По умолчанию	—
Контекст	http, server, location

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

grpc_ssl_certificate_cache#

Синтаксис

grpc_ssl_certificate_cache off;

grpc_ssl_certificate_cache max=N [inactive=time] [valid=time];

Значение по умолчанию

grpc_ssl_certificate_cache off;

Контекст

http, server, location

Определяет кэш для хранения SSL-сертификатов и секретных ключей, заданных через переменные.

Директива поддерживает следующие параметры:

max — устанавливает максимальное количество элементов в кэше. При переполнении кэша удаляются наименее недавно использованные (LRU) элементы.
inactive — определяет время, после которого элемент будет удален, если к нему не было обращений в течение этого времени, даже если он еще находится в пределах своего периода valid; каждое обращение сбрасывает этот таймер. Значение по умолчанию — 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#

Синтаксис	`grpc_ssl_certificate_key` файл;
По умолчанию	—
Контекст	http, server, location

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

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

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

В имени файла можно использовать переменные.

grpc_ssl_ciphers#

Синтаксис	`grpc_ssl_ciphers` шифры;
По умолчанию	`grpc_ssl_ciphers DEFAULT;`
Контекст	http, server, location

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

Список шифров зависит от установленной версии OpenSSL. Полный список можно посмотреть с помощью команды openssl ciphers.

Предупреждение

Директива grpc_ssl_ciphers не настраивает шифры для TLS 1.3 при использовании OpenSSL. Для настройки шифров TLS 1.3 в OpenSSL используйте директиву grpc_ssl_conf_command, добавленную для расширенной конфигурации SSL.

В LibreSSL шифры TLS 1.3 можно настраивать с помощью grpc_ssl_ciphers.
В BoringSSL шифры TLS 1.3 настроить невозможно.

grpc_ssl_conf_command#

Синтаксис	`grpc_ssl_conf_command` имя значение;
По умолчанию	—
Контекст	http, server, location

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

Примечание

Директива поддерживается при использовании OpenSSL 1.0.2 и выше. Чтобы настроить шифры TLS 1.3 в OpenSSL, используйте команду ciphersuites.

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

Предупреждение

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

grpc_ssl_crl#

Синтаксис	`grpc_ssl_crl` файл;
По умолчанию	—
Контекст	http, server, location

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

grpc_ssl_name#

Синтаксис	`grpc_ssl_name` имя;
По умолчанию	grpc_ssl_name `имя хоста из grpc_pass;`
Контекст	http, server, location

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

Имя сервера также можно задать с помощью переменных.

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

grpc_ssl_password_file#

Синтаксис	`grpc_ssl_password_file` файл;
По умолчанию	—
Контекст	http, server, location

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

grpc_ssl_protocols#

Синтаксис	`grpc_ssl_protocols` [`SSLv2`] [`SSLv3`] [`TLSv1`] [`TLSv1.1`] [`TLSv1.2`] [`TLSv1.3`];
По умолчанию	`grpc_ssl_protocols TLSv1.2 TLSv1.3;`
Контекст	http, server, location

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

grpc_ssl_server_name#

Синтаксис	`grpc_ssl_server_name` `on` \| `off`;
По умолчанию	`grpc_ssl_server_name off;`
Контекст	http, server, location

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

grpc_ssl_session_reuse#

Синтаксис	`grpc_ssl_session_reuse` `on` \| `off`;
По умолчанию	`grpc_ssl_session_reuse on;`
Контекст	http, server, location

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

grpc_ssl_trusted_certificate#

Синтаксис	`grpc_ssl_trusted_certificate` файл;
По умолчанию	—
Контекст	http, server, location

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

grpc_ssl_verify#

Синтаксис	`grpc_ssl_verify` `on` \| `off`;
По умолчанию	`grpc_ssl_verify off;`
Контекст	http, server, location

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

grpc_ssl_verify_depth#

Синтаксис	`grpc_ssl_verify_depth` число;
По умолчанию	`grpc_ssl_verify_depth 1;`
Контекст	http, server, location

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