gRPC#

Permite repassar requisições para um servidor gRPC.

Nota

Este módulo requer o módulo HTTP/2.

Exemplo de configuração#

server {
    listen 9000;

    http2 on;

    location / {
        grpc_pass 127.0.0.1:9000;
    }
}

Diretivas#

grpc_bind#

Sintaxe	`grpc_bind` endereço [`transparent`] \| `off`;
Padrão	—
Contexto	http, server, location

Faz com que conexões de saída para um servidor gRPC se originem do endereço IP local especificado com uma porta opcional. O valor do parâmetro pode conter variáveis. O valor especial off cancela o efeito da diretiva grpc_bind herdada do nível de configuração anterior, permitindo que o sistema atribua automaticamente o endereço IP e a porta locais.

O parâmetro transparent permite que conexões de saída para um servidor gRPC se originem de um endereço IP não local, por exemplo, do endereço IP real de um cliente:

grpc_bind $remote_addr transparent;

Para que este parâmetro funcione, geralmente é necessário executar processos worker do Angie com privilégios de superusuário. No Linux não é necessário, pois, se o parâmetro transparent for especificado, os processos worker herdam a capacidade CAP_NET_RAW do processo master.

Nota

É necessário configurar a tabela de rotas do kernel para interceptar tráfego de rede do servidor gRPC.

grpc_buffer_size#

Sintaxe	`grpc_buffer_size` tamanho;
Padrão	`grpc_buffer_size 4k\|8k;`
Contexto	http, server, location

Define o tamanho do buffer usado para ler a primeira parte da resposta recebida do servidor gRPC. A resposta é repassada ao cliente de forma síncrona, assim que é recebida.

grpc_connect_timeout#

Sintaxe	`grpc_connect_timeout` tempo;
Padrão	`grpc_connect_timeout 60s;`
Contexto	http, server, location

Define um tempo limite para estabelecer conexão com um servidor gRPC. Deve-se notar que este tempo limite geralmente não pode exceder 75 segundos.

Nota

Este timeout não rege as conexões ociosas: por quanto tempo uma conexão já aberta é mantida para reutilização é definido por keepalive_timeout em um bloco upstream cujas conexões são armazenadas em cache com keepalive.

grpc_connection_drop#

Sintaxe	`grpc_connection_drop` tempo \| `on` \| `off`;
Padrão	`grpc_connection_drop off;`
Contexto	http, server, location

Habilita a finalização de todas as conexões ativas com o servidor proxy após ele ter sido removido do grupo ou marcado como permanentemente indisponível por um processo reresolve ou pelo comando DELETE da API. As conexões ociosas no cache não são afetadas.

Uma conexão é finalizada quando o próximo evento de leitura ou escrita é processado, seja pelo cliente ou pelo servidor proxy.

Definir tempo habilita um timeout de finalização de conexão; com on, as conexões são encerradas imediatamente.

grpc_hide_header#

Sintaxe	`grpc_hide_header` campo;
Padrão	—
Contexto	http, server, location

Por padrão, o Angie não repassa os campos de cabeçalho Date, Server e X-Accel-... da resposta de um servidor gRPC para o cliente. A diretiva grpc_hide_header define campos adicionais que não serão repassados. Se, pelo contrário, for necessário permitir o repasse de campos, pode-se usar a diretiva grpc_pass_header.

grpc_ignore_headers#

Sintaxe	`grpc_ignore_headers` campo ...;
Padrão	—
Contexto	http, server, location

Desabilita o processamento de certos campos de cabeçalho de resposta do servidor gRPC. Os seguintes campos podem ser ignorados: X-Accel-Redirect e X-Accel-Charset.

Se não forem desabilitados, o processamento destes campos de cabeçalho tem o seguinte efeito:

X-Accel-Redirect executa um redirecionamento interno para o URI especificado;
X-Accel-Charset define o charset desejado de uma resposta.

grpc_intercept_errors#

Sintaxe	`grpc_intercept_errors` `on` \| `off`;
Padrão	`grpc_intercept_errors off;`
Contexto	http, server, location

Determina se respostas do servidor gRPC com códigos maiores ou iguais a 300 devem ser repassadas ao cliente ou interceptadas e redirecionadas para o Angie para processamento com a diretiva error_page.

grpc_next_upstream#

Sintaxe	`grpc_next_upstream` `error` \| `timeout` \| `invalid_header` \| `http_500` \| `http_502` \| `http_503` \| `http_504` \| `http_403` \| `http_404` \| `http_429` \| `non_idempotent` \| `off` ...;
Padrão	`grpc_next_upstream error timeout;`
Contexto	http, server, location

Especifica em quais casos uma requisição deve ser repassada para o próximo servidor no grupo upstream:

`error`	ocorreu um erro ao estabelecer conexão com o servidor, repassar a requisição ou ler o cabeçalho da resposta;
`timeout`	ocorreu timeout ao estabelecer conexão com o servidor, repassar a requisição ou ler o cabeçalho da resposta;
`invalid_header`	o servidor retornou uma resposta vazia ou inválida;
`http_500`	o servidor retornou resposta com código 500;
`http_502`	o servidor retornou resposta com código 502;
`http_503`	o servidor retornou resposta com código 503;
`http_504`	o servidor retornou resposta com código 504;
`http_403`	o servidor retornou resposta com código 403;
`http_404`	o servidor retornou resposta com código 404;
`http_429`	o servidor retornou resposta com código 429;
`non_idempotent`	normalmente, requisições com método não idempotente (`POST`, `LOCK`, `PATCH`) não são repassadas ao próximo servidor se uma requisição já tiver sido enviada a um servidor upstream; habilitar esta opção permite explicitamente tentar novamente tais requisições;
`off`	desabilita o repasse da requisição ao próximo servidor.

Nota

Deve-se ter em mente que repassar uma requisição ao próximo servidor só é possível se nada ainda tiver sido enviado ao cliente. Ou seja, se um erro ou timeout ocorrer no meio da transferência da resposta, não é possível corrigir.

A diretiva também define o que é considerado uma tentativa malsucedida de comunicação com um servidor.

`error`, `timeout`, `invalid_header`	sempre considerados tentativas malsucedidas, mesmo que não especificados na diretiva
`http_500`, `http_502`, `http_503`, `http_504`, `http_429`	considerados tentativas malsucedidas apenas se especificados na diretiva
`http_403`, `http_404`	nunca considerados tentativas malsucedidas

O repasse de uma requisição ao próximo servidor pode ser limitado pelo número de tentativas e pelo tempo.

grpc_next_upstream_timeout#

Sintaxe	`grpc_next_upstream_timeout` tempo;
Padrão	`grpc_next_upstream_timeout 0;`
Contexto	http, server, location

Limita o tempo durante o qual uma requisição pode ser repassada para o próximo servidor.

`0`	desativa esta limitação

grpc_next_upstream_tries#

Sintaxe	`grpc_next_upstream_tries` número;
Padrão	`grpc_next_upstream_tries 0;`
Contexto	http, server, location

Limita o número de tentativas possíveis para repassar uma requisição ao próximo servidor.

`0`	desativa esta limitação

grpc_pass#

Sintaxe	`grpc_pass` endereço;
Padrão	—
Contexto	location, if in location

Define o endereço do servidor gRPC. O endereço pode ser especificado como um nome de domínio ou endereço IP, e uma porta:

grpc_pass localhost:9000;

ou como um caminho de socket de domínio UNIX:

grpc_pass unix:/tmp/grpc.socket;

Alternativamente, pode-se usar o esquema grpc://:

grpc_pass grpc://127.0.0.1:9000;

Para usar gRPC sobre SSL, deve-se usar o esquema grpcs://:

grpc_pass grpcs://127.0.0.1:443;

Se um nome de domínio resolver para vários endereços, todos serão usados em round-robin. Além disso, um endereço pode ser especificado como um grupo de servidores.

O valor do parâmetro pode conter variáveis. Neste caso, se um endereço for especificado como nome de domínio, o nome será procurado entre os grupos de servidores descritos e, se não for encontrado, será determinado usando um resolver.

Nota

Se grpc_pass for especificado em um location com uma barra final no prefixo (por exemplo, location /name/), e a diretiva auto_redirect estiver definida como default, requisições sem barra final serão redirecionadas (/name -> /name/).

grpc_pass_header#

Sintaxe	`grpc_pass_header` campo;
Padrão	—
Contexto	http, server, location

Permite repassar campos de cabeçalho normalmente desabilitados de um servidor gRPC para um cliente.

grpc_read_timeout#

Sintaxe	`grpc_read_timeout` tempo;
Padrão	`grpc_read_timeout 60s;`
Contexto	http, server, location

Define um tempo limite para leitura de resposta do servidor gRPC. O tempo limite é definido apenas entre duas operações de leitura sucessivas, não para a transmissão da resposta inteira. Se o servidor gRPC não transmitir nada dentro desse tempo, a conexão é fechada.

grpc_send_timeout#

Sintaxe	`grpc_send_timeout` tempo;
Padrão	`grpc_send_timeout 60s;`
Contexto	http, server, location

Define um tempo limite para transmitir uma requisição ao servidor gRPC. O tempo limite é definido apenas entre duas operações de escrita sucessivas, não para a transmissão da requisição inteira. Se o servidor gRPC não receber nada dentro desse tempo, a conexão é fechada.

grpc_set_header#

Sintaxe	`grpc_set_header` campo valor;
Padrão	`grpc_set_header Content-Length $content_length;`
Contexto	http, server, location

Permite redefinir ou adicionar campos ao cabeçalho da requisição repassado para o servidor gRPC. O valor pode conter texto, variáveis e suas combinações. Essas diretivas são herdadas do nível de configuração anterior se e somente se não houver diretivas grpc_set_header definidas no nível atual.

Se o valor de um campo de cabeçalho for uma string vazia, então esse campo não será repassado ao servidor gRPC:

grpc_set_header Accept-Encoding "";

grpc_socket_keepalive#

Sintaxe	`grpc_socket_keepalive` `on` \| `off`;
Padrão	`grpc_socket_keepalive off;`
Contexto	http, server, location

Configura o comportamento de "TCP keepalive" para conexões de saída a um servidor gRPC.

`off`	Por padrão, as configurações do sistema operacional estão em efeito para o socket.
`on`	A opção de socket SO_KEEPALIVE é ativada para o socket.

grpc_ssl_certificate#

Sintaxe	`grpc_ssl_certificate` arquivo;
Padrão	—
Contexto	http, server, location

Especifica um arquivo com o certificado no formato PEM usado para autenticação em um servidor gRPC SSL. Variáveis podem ser usadas no nome do arquivo.

grpc_ssl_certificate_cache#

Sintaxe

grpc_ssl_certificate_cache off;

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

Padrão

grpc_ssl_certificate_cache off;

Contexto

http, server, location

Define um cache que armazena certificados SSL e chaves secretas especificados usando variáveis.

A diretiva suporta os seguintes parâmetros:

max — define o número máximo de elementos no cache. Quando o cache está cheio, os elementos menos usados recentemente (LRU) são removidos.
inactive — define o tempo após o qual um elemento é removido se não tiver sido acessado durante esse tempo, mesmo que ainda esteja dentro de seu período valid; cada acesso reinicia este temporizador. O padrão é 10 segundos.
valid — define o tempo durante o qual um elemento em cache é considerado válido e pode ser reutilizado. O padrão é 60 segundos. Após esse período, os certificados são recarregados ou revalidados.
off — desativa o cache.

Exemplo:

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#

Sintaxe	`grpc_ssl_certificate_key` arquivo;
Padrão	—
Contexto	http, server, location

Especifica um arquivo com a chave secreta no formato PEM usada para autenticação em um servidor gRPC SSL.

O valor engine:nome:id pode ser especificado em vez do arquivo, carregando uma chave secreta com o id especificado do motor OpenSSL nome.

O valor store:esquema:id pode ser especificado em vez do arquivo, sendo usado para carregar uma chave secreta com o id especificado e o URI esquema registrado no provedor OpenSSL, como pkcs11.

Variáveis podem ser usadas no nome do arquivo.

grpc_ssl_ciphers#

Sintaxe	`grpc_ssl_ciphers` ciphers;
Padrão	`grpc_ssl_ciphers DEFAULT;`
Contexto	http, server, location

Especifica as cifras habilitadas para requisições a um servidor gRPC SSL. As cifras são especificadas no formato compreendido pela biblioteca OpenSSL.

A lista de cifras depende da versão do OpenSSL instalada. A lista completa pode ser visualizada usando o comando openssl ciphers.

Aviso

A diretiva grpc_ssl_ciphers não configura cifras para TLS 1.3 ao usar OpenSSL. Para ajustar cifras TLS 1.3 com OpenSSL, use a diretiva grpc_ssl_conf_command, que foi adicionada para suportar configuração SSL avançada.

No LibreSSL, cifras TLS 1.3 podem ser configuradas usando grpc_ssl_ciphers.
No BoringSSL, cifras TLS 1.3 não podem ser configuradas de forma alguma.

grpc_ssl_conf_command#

Sintaxe	`grpc_ssl_conf_command` nome valor;
Padrão	—
Contexto	http, server, location

Define comandos de configuração arbitrários do OpenSSL ao estabelecer uma conexão com o servidor gRPC SSL.

Nota

A diretiva é suportada ao usar OpenSSL 1.0.2 ou superior. Para configurar cifras TLS 1.3 com OpenSSL, use o comando ciphersuites.

Várias diretivas grpc_ssl_conf_command podem ser especificadas no mesmo nível. Essas diretivas são herdadas do nível de configuração anterior se e somente se não houver diretivas grpc_ssl_conf_command definidas no nível atual.

Aviso

Note que configurar o OpenSSL diretamente pode resultar em comportamento inesperado.

grpc_ssl_crl#

Sintaxe	`grpc_ssl_crl` file;
Padrão	—
Contexto	http, server, location

Especifica um arquivo com certificados revogados (CRL) no formato PEM usado para verificar o certificado do servidor gRPC SSL.

grpc_ssl_name#

Sintaxe	`grpc_ssl_name` name;
Padrão	grpc_ssl_name `host name de grpc_pass;`
Contexto	http, server, location

Permite sobrescrever o nome do servidor usado para verificar o certificado do servidor gRPC SSL e para ser passado via SNI ao estabelecer uma conexão com o servidor gRPC SSL.

O nome do servidor também pode ser especificado com variáveis.

Por padrão, o host name do grpc_pass é usado.

grpc_ssl_password_file#

Sintaxe	`grpc_ssl_password_file` file;
Padrão	—
Contexto	http, server, location

Especifica um arquivo com senhas para chaves secretas, onde cada senha é especificada em uma linha separada. As senhas são testadas em sequência ao carregar a chave.

grpc_ssl_protocols#

Sintaxe	`grpc_ssl_protocols` [`SSLv2`] [`SSLv3`] [`TLSv1`] [`TLSv1.1`] [`TLSv1.2`] [`TLSv1.3`];
Padrão	`grpc_ssl_protocols TLSv1.2 TLSv1.3;`
Contexto	http, server, location

Habilita os protocolos especificados para solicitações a um servidor gRPC SSL.

grpc_ssl_server_name#

Sintaxe	`grpc_ssl_server_name` `on` \| `off`;
Padrão	`grpc_ssl_server_name off;`
Contexto	http, server, location

Habilita ou desabilita o envio do nome do servidor definido pela diretiva grpc_ssl_name via a extensão TLS Server Name Indication (SNI, RFC 6066) ao estabelecer uma conexão com o servidor gRPC SSL.

grpc_ssl_session_reuse#

Sintaxe	`grpc_ssl_session_reuse` `on` \| `off`;
Padrão	`grpc_ssl_session_reuse on;`
Contexto	http, server, location

Determina se sessões SSL podem ser reutilizadas ao trabalhar com o servidor gRPC. Se os erros "SSL3_GET_FINISHED:digest check failed" aparecerem nos logs, tente desabilitar a reutilização de sessão.

grpc_ssl_trusted_certificate#

Sintaxe	`grpc_ssl_trusted_certificate` file;
Padrão	—
Contexto	http, server, location

Especifica um arquivo com certificados de CA confiáveis no formato PEM usado para verificar o certificado do servidor gRPC SSL.

grpc_ssl_verify#

Sintaxe	`grpc_ssl_verify` `on` \| `off`;
Padrão	`grpc_ssl_verify off;`
Contexto	http, server, location

Habilita ou desabilita a verificação do certificado do servidor gRPC SSL.

grpc_ssl_verify_depth#

Sintaxe	`grpc_ssl_verify_depth` number;
Padrão	`grpc_ssl_verify_depth 1;`
Contexto	http, server, location

Define a profundidade de verificação na cadeia de certificados do servidor gRPC SSL.