gRPC#
Permite repassar requisições para um servidor gRPC.
Nota
Este módulo requer o módulo HTTP2.
Exemplo de Configuração#
server {
listen 9000;
http2 on;
location / {
grpc_pass 127.0.0.1:9000;
}
}
Diretivas#
grpc_bind#
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#
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#
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.
grpc_connection_drop#
| |
Padrão |
|
http, server, location |
Habilita a finalização de todas as conexões 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 da API DELETE.
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#
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#
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:
grpc_intercept_errors#
| |
Padrão |
|
http, server, location |
Determina se respostas 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#
| |
Padrão |
|
http, server, location |
Especifica em quais casos uma requisição deve ser repassada para o próximo servidor no pool upstream:
| ocorreu um erro ao estabelecer conexão com o servidor, repassar a requisição ou ler o cabeçalho da resposta; |
| ocorreu timeout ao estabelecer conexão com o servidor, repassar a requisição ou ler o cabeçalho da resposta; |
| o servidor retornou uma resposta vazia ou inválida; |
| o servidor retornou resposta com código 500; |
| o servidor retornou resposta com código 502; |
| o servidor retornou resposta com código 503; |
| o servidor retornou resposta com código 504; |
| o servidor retornou resposta com código 403; |
| o servidor retornou resposta com código 404; |
| o servidor retornou resposta com código 429; |
| normalmente, requisições com método não idempotente
( |
| 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.
| sempre considerados tentativas malsucedidas, mesmo que não especificados na diretiva |
| considerados tentativas malsucedidas apenas se especificados na diretiva |
| 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#
| |
Padrão |
|
http, server, location |
Limita o tempo durante o qual uma requisição pode ser repassada para o próximo servidor.
| desativa esta limitação |
grpc_next_upstream_tries#
| |
Padrão |
|
http, server, location |
Limita o número de tentativas possíveis de repassar uma requisição para o próximo servidor.
| desativa esta limitação |
grpc_pass#
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.
grpc_pass_header#
Permite repassar campos de cabeçalho normalmente desabilitados de um servidor gRPC para um cliente.
grpc_read_timeout#
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#
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#
| |
Padrão |
|
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 a um servidor gRPC:
grpc_set_header Accept-Encoding "";
grpc_socket_keepalive#
| |
Padrão |
|
http, server, location |
Configura o comportamento de "TCP keepalive" para conexões de saída a um servidor gRPC.
| Por padrão, as configurações do sistema operacional estão em efeito para o socket. |
| A opção de socket SO_KEEPALIVE é ativada para o socket. |
grpc_ssl_certificate#
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#
| |
Padrão |
|
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. 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#
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.
Variáveis podem ser usadas no nome do arquivo.
grpc_ssl_ciphers#
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#
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#
Especifica um arquivo com certificados revogados (CRL) no formato PEM usado para verificar o certificado do servidor gRPC SSL.
grpc_ssl_name#
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.
Por padrão, é usada a parte de host da URL do grpc_pass.
grpc_ssl_password_file#
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#
| |
Padrão |
|
http, server, location |
Alterado na versão 1.2.0: Parâmetro TLSv1.3 adicionado ao conjunto padrão.
Habilita os protocolos especificados para requisições a um servidor gRPC SSL.
grpc_ssl_server_name#
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#
| |
Padrão |
|
http, server, location |
Determina se sessões SSL podem ser reutilizadas ao trabalhar com o servidor gRPC. Se erros "SSL3_GET_FINISHED:digest check failed" aparecerem nos logs, tente desabilitar a reutilização de sessão.
grpc_ssl_trusted_certificate#
Especifica um arquivo com certificados de CA confiáveis no formato PEM usado para verificar o certificado do servidor gRPC SSL.
grpc_ssl_verify#
Habilita ou desabilita a verificação do certificado do servidor gRPC SSL.
grpc_ssl_verify_depth#
Define a profundidade de verificação na cadeia de certificados do servidor gRPC SSL.
Conteúdo