Implantando o NGINX como um API Gateway, Parte 3: Publicação de serviços gRPC

Esta é a terceira postagem do blog em nossa série sobre a implantação do NGINX Open Source e do NGINX Plus como um gateway de API.

• A Parte 1 fornece instruções detalhadas para vários casos de uso do NGINX Open Source e do NGINX Plus como gateway de API para APIs RESTful baseadas em HTTP.
• A Parte 2 amplia esses casos de uso e analisa uma série de salvaguardas que podem ser aplicadas para proteger e assegurar serviços de API de backend em produção.
• Esta postagem explica como implantar o NGINX Open Source e o NGINX Plus como um gateway de API para serviços gRPC. Originalmente publicado em 2018, o post foi atualizado para aproveitar o suporte introduzido em NGINX Plus versão 23 para o protocolo de verificação de integridade gRPC nativo. Consulte Implementando verificações de integridade .

Observação:  Exceto quando indicado, todas as informações nesta postagem se aplicam ao NGINX Plus e ao NGINX Open Source. Para facilitar a leitura, o restante do blog se refere simplesmente a “NGINX” quando a discussão se aplica a ambas as versões.

Os conceitos e benefícios das arquiteturas de aplicativos de microsserviços foram bem documentados nos últimos anos, e em nenhum lugar mais do que no blog do NGINX . No centro dos aplicativos de microsserviços está a API HTTP, e as duas primeiras postagens de blog desta série usam uma API REST hipotética para ilustrar como o NGINX aborda esse estilo de aplicativo.

Apesar da popularidade das APIs REST com formatos de mensagem JSON para aplicativos modernos, essa não é uma abordagem ideal para todos os cenários ou todas as organizações. Os desafios mais comuns são:

• Padrões de documentação – Sem uma boa disciplina do desenvolvedor ou requisitos de documentação obrigatórios, é muito fácil acabar com uma série de APIs REST que não têm uma definição precisa. A Open API Specification surgiu como uma linguagem de descrição de interface genérica para APIs REST, mas seu uso é opcional e requer forte governança dentro da organização de desenvolvimento.
• Eventos e conexões de longa duração – APIs REST e seu uso de HTTP como transporte, determinam em grande parte um padrão de solicitação-resposta para todas as chamadas de API. Quando o aplicativo requer eventos gerados pelo servidor, usar soluções como HTTP long polling e WebSocket pode ajudar, mas o uso dessas soluções requer, em última análise, a construção de uma API separada e adjacente.
• Transações complexas – APIs REST são construídas em torno do conceito de recursos exclusivos, cada um representado por um URI. Quando um evento de aplicativo solicita que vários recursos sejam atualizados, várias chamadas de API são necessárias, o que é ineficiente, ou uma transação complexa deve ser implementada no backend, o que contradiz o princípio central do REST.

Nos últimos anos, o gRPC surgiu como uma abordagem alternativa para a criação de aplicativos distribuídos, e aplicativos de microsserviços em particular. Originalmente desenvolvido no Google, o gRPC foi disponibilizado como código aberto em 2015 e agora é um projeto da Cloud Native Computing Foundation. Significativamente, o gRPC usa HTTP/2 como seu mecanismo de transporte, aproveitando seu formato de dados binários e recursos de streaming multiplexado.

Os principais benefícios do gRPC são:

• Linguagem de definição de interface fortemente acoplada ( buffers de protocolo )
• Suporte nativo para streaming de dados (em ambas as direções)
• Formato de dados binários eficiente
• Geração automatizada de código para muitas linguagens de programação, permitindo um verdadeiro ambiente de desenvolvimento poliglota sem introduzir problemas de interoperabilidade

Definindo o Gateway gRPC

As duas primeiras postagens desta série descreveram como diversas APIs podem ser entregues por meio de um único ponto de entrada (por exemplo, https://api.example.com ). O comportamento padrão e as características do tráfego gRPC nos levam a adotar a mesma abordagem quando o NGINX é implantado como um gateway gRPC. Embora seja possível compartilhar tráfego HTTP e gRPC no mesmo nome de host e porta, há uma série de razões pelas quais é preferível separá-los:

• Os clientes da API para aplicativos REST e gRPC esperam respostas de erro em formatos diferentes
• Os campos relevantes para logs de acesso variam entre REST e gRPC
• Como o gRPC nunca lida com navegadores da web legados, ele pode ter uma política TLS mais rigorosa

Para conseguir essa separação, colocamos a configuração do nosso gateway gRPC em seu próprio bloco server{} no arquivo de configuração principal do gRPC, grpc_gateway.conf , localizado no diretório /etc/nginx/conf.d .

Começamos definindo o formato das entradas no log de acesso para tráfego gRPC (linhas 1–4). Neste exemplo, usamos um formato JSON para capturar os dados mais relevantes de cada solicitação. Observe, por exemplo, que o método HTTP não está incluído, pois todas as solicitações gRPC usam POST . Também registramos o código de status gRPC junto com o código de status HTTP. No entanto, o código de status gRPC pode ser gerado de diferentes maneiras. Em condições normais, grpc-status é retornado como um trailer HTTP/2 do backend, mas em algumas condições de erro ele pode ser retornado como um cabeçalho HTTP/2, pelo backend ou pelo próprio NGINX. Para simplificar o log de acesso, usamos um bloco de mapa (linhas 6 a 9) para avaliar uma nova variável $grpc_status e obter o status do gRPC de onde quer que ele se origine.

Esta configuração contém duas diretivas de escuta (linhas 12 e 13) para que possamos testar tanto o tráfego de texto simples (porta 50051) quanto o tráfego protegido por TLS (porta 443). O parâmetro http2 configura o NGINX para aceitar conexões HTTP/2 – observe que isso é independente do parâmetro ssl . Observe também que a porta 50051 é a porta de texto simples convencional para gRPC, mas não é adequada para uso em produção.

A configuração TLS é convencional, com exceção da diretiva ssl_protocols (linha 23), que especifica o TLS 1.2 como o protocolo aceitável mais fraco. A especificação HTTP/2 exige o uso do TLS 1.2 (ou superior), o que garante que todos os clientes suportem a extensão Server Name Indication (SNI) para TLS. Isso significa que o gateway gRPC pode compartilhar a porta 443 com servidores virtuais definidos em outros blocos server{} .

Executando serviços gRPC de exemplo

Para explorar os recursos gRPC do NGINX, estamos usando um ambiente de teste simples que representa os principais componentes de um gateway gRPC, com vários serviços gRPC implantados. Usamos dois aplicativos de exemplo dos guias oficiais do gRPC : helloworld (escrito em Go) e RouteGuide (escrito em Python). O aplicativo RouteGuide é especialmente útil porque inclui cada um dos quatro métodos de serviço gRPC:

• RPC simples (solicitação-resposta única)
• Resposta-streaming RPC
• Solicitação de streaming RPC
• RPC de transmissão bidirecional

Ambos os serviços gRPC são instalados como contêineres Docker em nosso host NGINX. Para obter instruções completas sobre como criar o ambiente de teste, consulte o Apêndice .

Configuramos o NGINX para saber sobre os serviços RouteGuide e helloworld, juntamente com os endereços dos contêineres disponíveis.

Adicionamos um bloco upstream para cada um dos serviços gRPC (linhas 40–45 e 47–51) e os preenchemos com os endereços dos contêineres individuais que estão executando o código do servidor gRPC.

Roteamento de solicitações gRPC

Com o NGINX escutando na porta de texto simples convencional para gRPC (50051), adicionamos informações de roteamento à configuração para que as solicitações do cliente cheguem ao serviço de backend correto. Mas primeiro precisamos entender como as chamadas de método gRPC são representadas como solicitações HTTP/2. O diagrama a seguir mostra uma versão abreviada do arquivo route_guide.proto para o serviço RouteGuide, ilustrando como o pacote, o serviço e o método RPC formam o URI, conforme visto pelo NGINX.

As informações transportadas na solicitação HTTP/2 podem, portanto, ser usadas para fins de roteamento, bastando corresponder ao nome do pacote (aqui, routeguide ou helloworld ).

O primeiro bloco de localização (linha 26), sem nenhum modificador, define uma correspondência de prefixo de forma que /routeguide. corresponda a todos os serviços e métodos RPC definidos no arquivo .proto correspondente para esse pacote. A diretiva grpc_pass (linha 27) portanto passa todas as solicitações do cliente RouteGuide para o grupo upstream routeguide_service . Esta configuração (e a paralela para o serviço helloworld nas linhas 29 e 30) fornece um mapeamento simples entre um pacote gRPC e seus serviços de backend.

Observe que o argumento para as diretivas grpc_pass começa com o esquema grpc:// , que faz proxy de solicitações usando uma conexão gRPC de texto simples. Se o backend estiver configurado para TLS, podemos usar o esquema grpcs:// para proteger a conexão gRPC com criptografia de ponta a ponta.

Depois de executar o cliente RouteGuide, podemos confirmar o comportamento do roteamento revisando as entradas do arquivo de log. Aqui vemos que o método RPC RouteChat foi roteado para o contêiner em execução na porta 10002.

$ python route_guide_client.py ... $ tail -1 /var/log/nginx/grpc_log.json | jq { "carimbo de data/hora": "2021-01-20T12:17:56+01:00", "cliente": "127.0.0.1", "uri": "/routeguide.RouteGuide/RouteChat", "http-status": 200, "status-grpc": 0, "rio acima": "127.0.0.1:10002", "rx-bytes": 161, "bytes de tx": 212 }

Roteamento preciso

Conforme mostrado acima, o roteamento de vários serviços gRPC para diferentes backends é simples, eficiente e requer muito poucas linhas de configuração. No entanto, os requisitos de roteamento em um ambiente de produção podem ser mais complexos e exigir roteamento com base em outros elementos no URI (o serviço gRPC ou até mesmo métodos RPC individuais).

O snippet de configuração a seguir estende o exemplo anterior para que o método RPC de streaming bidirecional RouteChat seja roteado para um backend e todos os outros métodos RouteGuide para um backend diferente.

A segunda diretiva de localização (linha 7) usa o modificador = (sinal de igual) para indicar que esta é uma correspondência exata no URI para o método RPC RouteChat . Correspondências exatas são processadas antes das correspondências de prefixo, o que significa que nenhum outro bloco de localização é considerado para o URI do RouteChat .

Respondendo a erros

Os erros do gRPC são um pouco diferentes daqueles do tráfego HTTP convencional. Os clientes esperam que as condições de erro sejam expressas como respostas gRPC, o que torna o conjunto padrão de páginas de erro do NGINX (em formato HTML) inadequado quando o NGINX é configurado como um gateway gRPC. Resolvemos isso especificando um conjunto de respostas de erro personalizadas para clientes gRPC.

O conjunto completo de respostas de erro do gRPC é uma configuração relativamente longa e amplamente estática, então as mantemos em um arquivo separado, errors.grpc_conf , e usamos a diretiva include (linha 34) para referenciá-las. Ao contrário dos clientes HTTP/REST, não se espera que os aplicativos clientes gRPC lidem com uma ampla variedade de códigos de status HTTP. A documentação do gRPC especifica como um proxy intermediário, como o NGINX, deve converter códigos de erro HTTP em códigos de status do gRPC para que os clientes sempre recebam uma resposta adequada. Usamos a diretiva error_page para realizar esse mapeamento.

Cada um dos códigos de status HTTP padrão é passado para um local nomeado usando o prefixo @ para que uma resposta compatível com gRPC possa ser gerada. Por exemplo, o HTTP404 a resposta é redirecionada internamente para o local @grpc_unimplemented , que é definido posteriormente no arquivo:

O local nomeado @grpc_unimplemented está disponível apenas para processamento interno do NGINX – os clientes não podem solicitá-lo diretamente, pois não existe um URI roteável. Dentro deste local, construímos uma resposta gRPC preenchendo os cabeçalhos gRPC obrigatórios e enviando-os, sem um corpo de resposta, usando o código de status HTTP204 ( Sem conteúdo ).

Podemos usar o comando curl(1) para imitar um cliente gRPC com comportamento inadequado solicitando um método gRPC inexistente. Observe, no entanto, que o curl geralmente não é adequado como um cliente de teste gRPC porque os buffers de protocolo usam um formato de dados binários. Para testar o gRPC na linha de comando, considere usar grpc_cli .

$ curl -i --http2 -H "Content-Type: application/grpc" -H "TE: trailers" -X POST https://grpc.example.com/does.Not/Exist HTTP/2 204 servidor: nginx/1.19.5 data: Qua, 20 Jan 2021 15:03:41 GMT grpc-status: 12 grpc-message: não implementado

O arquivo grpc_errors.conf referenciado acima também contém mapeamentos de código de status HTTP para gRPC para outras respostas de erro que o NGINX pode gerar, como tempos limite e erros de certificado de cliente.

Autenticando clientes com metadados gRPC

Os metadados gRPC permitem que os clientes enviem informações adicionais junto com chamadas de método RPC, sem exigir que esses dados façam parte da especificação de buffers de protocolo (arquivo .proto ). Metadados são uma lista simples de pares de chave-valor, com cada par transmitido como um cabeçalho HTTP/2 separado. Os metadados são, portanto, facilmente acessíveis ao NGINX.

Dos muitos casos de uso de metadados, a autenticação de cliente é o mais comum para um gateway de API gRPC. O snippet de configuração a seguir mostra como o NGINX Plus pode usar metadados gRPC para executar a autenticação JWT (a autenticação JWT é exclusiva do NGINX Plus). Neste exemplo, o JWT é enviado nos metadados do token de autenticação .

Cada cabeçalho de solicitação HTTP está disponível para o NGINX Plus como uma variável chamada $ http_header . Hífens ( - ) no nome do cabeçalho são convertidos em sublinhados ( _ ) no nome da variável, então o JWT fica disponível como $http_auth_token (linha 2).

Se chaves de API forem usadas para autenticação, talvez com APIs HTTP/REST existentes, então elas também podem ser transportadas em metadados gRPC e validadas pelo NGINX. Uma configuração para autenticação de chave de API<.htmla> é fornecida na Parte 1 desta série de blogs.

Implementando verificações de saúde

Ao balancear a carga de tráfego para vários backends, é importante evitar enviar solicitações para backends que estão inativos ou indisponíveis. Com o NGINX Plus, podemos usar verificações de integridade ativas para enviar proativamente solicitações fora de banda aos backends e removê-los da rotação de balanceamento de carga quando não responderem às verificações de integridade conforme o esperado. Dessa forma, garantimos que as solicitações dos clientes nunca cheguem a backends fora de serviço.

O seguinte snippet de configuração habilita verificações de integridade ativas para os serviços RouteGuide e helloworld gRPC; para destacar a configuração relevante, ele omite algumas diretivas incluídas no arquivo grpc_gateway.conf usado nas seções anteriores.

Para cada rota, agora também especificamos a diretiva health_check (linhas 17 e 21). Conforme especificado pelo argumento type=grpc , o NGINX Plus usa o protocolo de verificação de integridade gRPC para enviar uma verificação de integridade a cada servidor no grupo upstream. Entretanto, nossos serviços gRPC simples não implementam o protocolo de verificação de integridade do gRPC e, portanto, esperamos que eles respondam com o código de status que significa “não implementado” ( grpc_status=12 ). Quando isso acontece, é o suficiente para indicar que estamos nos comunicando com um serviço gRPC ativo.

Com essa configuração em vigor, podemos derrubar qualquer um dos contêineres de backend sem que os clientes gRPC sofram atrasos ou tempos limite. As verificações de integridade ativas são exclusivas do NGINX Plus; leia mais sobre verificações de integridade do gRPC em nosso blog.

Aplicando Limitação de Taxa e Outros Controles de Gateway de API

A configuração de exemplo em grpc_gateway.conf é adequada para uso em produção, com algumas pequenas modificações para TLS. A capacidade de rotear solicitações gRPC com base em pacote, serviço ou método RPC significa que a funcionalidade NGINX existente pode ser aplicada ao tráfego gRPC exatamente da mesma forma que para APIs HTTP/REST, ou mesmo para tráfego regular da web. Em cada caso, o bloco de localização relevante pode ser estendido com configurações adicionais, como limitação de taxa ou controle de largura de banda.

Resumo

Nesta terceira e última postagem de blog da nossa série sobre a implantação do NGINX Open Source e do NGINX Plus como um gateway de API, focamos no gRPC como uma tecnologia nativa da nuvem para criar aplicativos de microsserviços. Demonstramos como o NGINX é capaz de fornecer aplicativos gRPC com a mesma eficiência que as APIs HTTP/REST, e como ambos os estilos de API podem ser publicados por meio do NGINX como um gateway de API multifuncional.

As instruções para configurar o ambiente de teste usado nesta postagem do blog estão no apêndice abaixo, e você pode baixar todos os arquivos do nosso repositório GitHub Gist .

Confira as outras postagens do blog desta série:

• A Parte 1 explica como configurar o NGINX em alguns casos de uso essenciais de gateway de API baseado em HTTP.
• A Parte 2 explora casos de uso mais avançados para proteger serviços de backend de clientes maliciosos ou malcomportados.

Para experimentar o NGINX Plus como um gateway de API, comece hoje mesmo seu teste gratuito de 30 dias ou entre em contato conosco para discutir seus casos de uso . Durante o teste, use o conjunto completo de arquivos de configuração do nosso repositório GitHub Gist .

Apêndice: Configurando o ambiente de teste

As instruções a seguir instalam o ambiente de teste em uma máquina virtual para que ele fique isolado e repetível. Entretanto, não há razão para que ele não possa ser instalado em um servidor físico, “bare metal”.

Para simplificar o ambiente de teste, usamos contêineres Docker para executar os serviços gRPC. Isso significa que não precisamos de vários hosts para o ambiente de teste, mas ainda podemos fazer com que o NGINX faça conexões proxy com uma chamada de rede, como em um ambiente de produção.

Usar o Docker também nos permite executar várias instâncias de cada serviço gRPC em uma porta diferente sem exigir alterações de código. Cada serviço gRPC escuta na porta 50051 dentro do contêiner, que é mapeada para uma porta localhost exclusiva na máquina virtual. Isso, por sua vez, libera a porta 50051 para que o NGINX possa usá-la como sua porta de escuta. Portanto, quando os clientes de teste se conectam usando a porta pré-configurada 50051, eles alcançam o NGINX.

Instalando o NGINX Open Source ou NGINX Plus

1. Instale o NGINX Open Source ou o NGINX Plus de acordo com as instruções no Guia de administração do NGINX Plus.

2. Copie os seguintes arquivos do repositório GitHub Gist para /etc/nginx/conf.d :

   • grpc_gateway.conf
   • erros.grpc_conf

   Observação:  Se não estiver usando TLS, comente as diretivas ssl_* em grpc_gateway.conf .

3. Inicie o NGINX Open Source ou o NGINX Plus.

   $ sudo nginx
   

Instalando o Docker

Para Debian e Ubuntu, execute:

$ sudo apt-get install docker.io

Para CentOS, RHEL e Oracle Linux, execute:

$ sudo yum instalar docker

Instalando os contêineres de serviço RouteGuide

1. Crie a imagem do Docker para os contêineres RouteGuide a partir do seguinte Dockerfile.

   Você pode copiar o Dockerfile para um subdiretório local antes da compilação ou especificar a URL do Gist para o Dockerfile como um argumento para o comando docker build :

   $ sudo docker build -t routeguide https://gist.githubusercontent.com/nginx-gists/87ed942d4ee9f7e7ebb2ccf757ed90be/raw/ce090f92f3bbcb5a94bbf8ded4d597cd47b43cbe/routeguide.Dockerfile
   

   Pode levar alguns minutos para baixar e criar a imagem. O aparecimento da mensagem Construído com sucesso e uma sequência hexadecimal (o ID da imagem) sinalizam a conclusão da construção.

2. Confirme se a imagem foi criada executando docker images .

   $ sudo docker images REPOSITÓRIO TAG IMAGEM ID CRIADO TAMANHO routeguide mais recente 63058a1cf8ca 1 minuto atrás 1,31 GB python mais recente 825141134528 9 dias atrás 923 MB
   

3. Inicie os contêineres do RouteGuide.

   $ sudo docker run --nome rg1 -p 10001:50051 -d guia de rota $ sudo docker run --nome rg2 -p 10002:50051 -d guia de rota $ sudo docker run --nome rg3 -p 10003:50051 -d guia de rota
   

   À medida que cada comando é bem-sucedido, uma longa sequência hexadecimal aparece, representando o contêiner em execução.

4. Verifique se todos os três contêineres estão ativos executando docker ps . (A saída de exemplo é dividida em várias linhas para facilitar a leitura.)

   $ sudo docker ps ID DO CONTAINER IMAGEM COMANDO STATUS ... d0cdaaeddf0f routeguide "python route_g..."  Aumento de 2 segundos... c04996ca3469 routeguide "python route_g..."  Aumentou 9 segundos...
   2170ddb62898 guia de rota "python route_g..."  Aumentou 1 minuto... ... NOMES DE PORTOS ... 0.0.0.0:10003->50051/tcp rg3 ... 0.0.0.0:10002->50051/tcp rg2 ... 0.0.0.0:10001->50051/tcp rg1
   

   A coluna PORTS na saída mostra como cada um dos contêineres mapeou uma porta local diferente para a porta 50051 dentro do contêiner.

Instalando os contêineres de serviço helloworld

1. Crie a imagem do Docker para os contêineres helloworld a partir do seguinte Dockerfile.

   Você pode copiar o Dockerfile para um subdiretório local antes da compilação ou especificar a URL do Gist para o Dockerfile como um argumento para o comando docker build :

   $ sudo docker build -t helloworld https://gist.githubusercontent.com/nginx-gists/87ed942d4ee9f7e7ebb2ccf757ed90be/raw/ce090f92f3bbcb5a94bbf8ded4d597cd47b43cbe/helloworld.Dockerfile
   

   Pode levar alguns minutos para baixar e criar a imagem. O aparecimento da mensagem Construído com sucesso e uma sequência hexadecimal (o ID da imagem) sinalizam a conclusão da construção.

2. Confirme se a imagem foi criada executando docker images .

   $ sudo docker images REPOSITÓRIO TAG IMAGEM ID CRIADO TAMANHO helloworld mais recente e5832dc0884a 10 segundos atrás 926 MB routeguide mais recente 170761fa3f03 4 minutos atrás 1,31 GB python mais recente 825141134528 9 dias atrás 923 MB golang mais recente d0e7a411e3da 3 semanas atrás 794 MB
   

3. Inicie os contêineres helloworld.

   $ sudo docker run --nome hw1 -p 20001:50051 -d olamundo $ sudo docker run --nome hw2 -p 20002:50051 -d olamundo
   

   À medida que cada comando é bem-sucedido, uma longa sequência hexadecimal aparece, representando o contêiner em execução.

4. Verifique se os dois contêineres helloworld estão ativos executando docker ps .

   $ sudo docker ps CONTAINER ID IMAGEM COMANDO STATUS ... e0d204ae860a helloworld "go run greeter..."  Aumentou 5 segundos... 
   66f21d89be78 helloworld "vai correr saudador..."  9 segundos... d0cdaaeddf0f routeguide "python route_g..."  4 minutos... c04996ca3469 routeguide "python route_g..."  Até 4 minutos... 
   2170ddb62898 guia de rota "python route_g..."  Até 5 minutos ... ... NOMES DE PORTOS ... 0.0.0.0:20002->50051/tcp hw2 ... 0.0.0.0:20001->50051/tcp hw1 ... 0.0.0.0:10003->50051/tcp rg3 ... 0.0.0.0:10002->50051/tcp rg2 ... 0.0.0.0:10001->50051/tcp rg1
   

Instalando os aplicativos do cliente gRPC

1. Instale os pré-requisitos da linguagem de programação, alguns dos quais podem já estar instalados no ambiente de teste.

   • Para Ubuntu e Debian, execute:

     $ sudo apt-get install golang-go python3 python-pip git
     

   • Para CentOS, RHEL e Oracle Linux, execute:

     $ sudo yum instalar golang python python-pip git
     

   Observe que o python-pip requer que o repositório EPEL esteja habilitado (execute sudo yum install epel-release primeiro, conforme necessário).

2. Baixe o aplicativo helloworld:

   $ vá para google.golang.org/grpc
   

3. Baixe o aplicativo RouteGuide:

   $ git clone -b v1.14.1 https://github.com/grpc/grpc $ pip install grpcio-tools
   

Testando a configuração

1. Execute o cliente helloworld:

   $ ir executar ir/src/google.golang.org/grpc/examples/helloworld/greeter_client/main.go
   

2. Execute o cliente RouteGuide:

   $ cd grpc/exemplos/python/guia_de_rota $ python route_guide_client.py
   

3. Verifique os logs do NGINX para confirmar se o ambiente de teste está operacional:

   $ tail /var/log/nginx/grpc_log.json