Configurar o gRPC do Cloud Endpoints para o Cloud Run com o ESPv2
Esta página mostra como configurar o Cloud Endpoints para Cloud Run com um back-end de gRPC. O Endpoints usa o Extensible Service Proxy V2 (ESPv2) como um gateway de API. Implante o contêiner ESPv2 pré-construído no Cloud Run para fornecer gerenciamento de API para o Cloud Run. Em seguida, ajude a proteger seus serviços usando o IAM do Cloud Run para que o ESPv2 possa invocá-los.
Com essa configuração, o ESPv2 intercepta todas as solicitações e executa as verificações necessárias, como a autenticação, antes de invocar o serviço. Quando o serviço responde, o ESPv2 coleta e relata a telemetria, como mostrado na figura abaixo. É possível conferir as métricas do serviço na página Endpoints > Serviços no Console do Google Cloud.
Para uma visão geral do Cloud Endpoints, consulte Sobre o Endpoints e Arquitetura do Endpoints.
Como migrar para o ESPv2
As versões anteriores do Cloud Endpoints não eram compatíveis com o gRPC no Cloud Run com ESP. Para usar este recurso, migre para o Extensible Service Proxy V2.
Lista de tarefas
Ao seguir o tutorial, use a lista de tarefas abaixo. Todas as tarefas são necessárias para concluir este tutorial.
- Crie um projeto do Google Cloud e, se você não tiver implantado seu próprio Cloud Run, implante um serviço gRPC de back-end de amostra. Consulte Antes de começar.
- Reserve um nome de host do Cloud Run para o serviço ESPv2. Consulte Como reservar um nome de host do Cloud Run.
- Crie um documento de configuração da API gRPC que descreva sua API e configure as rotas para o Cloud Run. Consulte Como configurar o Endpoints.
- Implante o documento de configuração da API gRPC para criar um serviço gerenciado. Consulte Como implantar a configuração do Endpoints.
- Crie uma nova imagem do Docker do ESPv2 com a configuração do serviço do Endpoints. Consulte Como criar uma nova imagem do ESPv2.
- Implante o contêiner do ESPv2 no Cloud Run. Em seguida, conceda ao ESPv2 a permissão de Gerenciamento de identidade e acesso (IAM, na sigla em inglês) para invocar seu serviço. Consulte Como implantar o contêiner do ESPv2.
- Chamar um serviço. Consulte Como enviar uma solicitação à API.
- Rastreie a atividade para seus serviços. Consulte Como rastrear a atividade da API.
- Evite cobranças na sua conta do Google Cloud. Consulte Limpeza.
Custos
Neste documento, você usará os seguintes componentes faturáveis do Google Cloud:
Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços.
Ao concluir as tarefas descritas neste documento, é possível evitar o faturamento contínuo excluindo os recursos criados. Saiba mais em Limpeza.
Antes de começar
Para configurar:
No console do Google Cloud, acesse a página Gerenciar recursos. e criar um projeto.
Verifique se o faturamento foi ativado para o projeto.
Anote o ID do projeto, porque ele será necessário mais tarde. No restante desta página, esse ID de projeto é chamado de ESP_PROJECT_ID.
Anote o número do projeto, porque ele será necessário mais tarde. No restante desta página, esse número de projeto é chamado de ESP_PROJECT_NUMBER.
Faça o download e instale a CLI do Google Cloud.
Siga as etapas no Guia de início rápido do gRPC para Python (em inglês) para instalar o gRPC e as ferramentas dele.
Implante o serviço de back-end gRPC do Cloud Run de python-grpc-bookstore-server para usar com este tutorial. O serviço gRPC usa a seguinte imagem de contêiner:
gcr.io/endpointsv2/python-grpc-bookstore-server:2
Siga as etapas em Início rápido: implantação de um contêiner pré-agrupado de exemplo para implantar o serviço. Substitua a imagem do contêiner especificada nesse início rápido com
gcr.io/endpointsv2/python-grpc-bookstore-server:2
Observe a região e o código do projeto em que o serviço foi implantado. No restante desta página, esse ID de projeto é chamado de BACKEND_PROJECT_ID. O nome do serviço Cloud Run implantado é chamado de BACKEND_SERVICE_NAME. O nome do host do Cloud Run é chamado de BACKEND_HOST_NAME.
Como reservar um nome de host do Cloud Run
É preciso reservar um nome do host do Cloud Run para o serviço ESPv2 para configurar o documento da OpenAPI ou a configuração do serviço gRPC. Para reservar um nome do host, você implantará um contêiner de amostra no Cloud Run. Posteriormente, você implantará o contêiner do ESPv2 no mesmo serviço do Cloud Run.
-
Verifique se a gcloud CLI está autorizada a acessar seus dados e serviços.
- Faça login.
gcloud auth login
- Na nova guia do navegador que é aberta, escolha uma conta que tenha o papel Editor ou Proprietário no projeto do Google Cloud que você criou para implantar o ESPv2 no Cloud Run.
- Faça login.
- Defina a região.
gcloud config set run/region us-central1
-
Implantar a imagem de amostra
gcr.io/cloudrun/hello
no Cloud Run. Substitua CLOUD_RUN_SERVICE_NAME pelo nome do serviço que você quer usar.gcloud run deploy CLOUD_RUN_SERVICE_NAME \ --image="gcr.io/cloudrun/hello" \ --allow-unauthenticated \ --platform managed \ --project=ESP_PROJECT_ID
Após a conclusão, o comando exibirá uma mensagem semelhante à seguinte:
Service [CLOUD_RUN_SERVICE_NAME] revision [CLOUD_RUN_SERVICE_NAME-REVISION_NUM] has been deployed and is serving traffic at CLOUD_RUN_SERVICE_URL
Por exemplo, se você definir CLOUD_RUN_SERVICE_NAME para
gateway
:Service [gateway] revision [gateway-00001] has been deployed and is serving traffic at https://gateway-12345-uc.a.run.app
Neste exemplo,
https://gateway-12345-uc.a.run.app
é o CLOUD_RUN_SERVICE_URL egateway-12345-uc.a.run.app
é o CLOUD_RUN_HOSTNAME. - Anote CLOUD_RUN_SERVICE_NAME e CLOUD_RUN_HOSTNAME.
Depois, implante o ESPv2 no serviço CLOUD_RUN_SERVICE_NAME do Cloud Run.
Especifique CLOUD_RUN_HOSTNAME no campo
host
do documento da OpenAPI.
Como configurar o Endpoints
A amostra bookstore-grpc
contém os arquivos necessários para fazer cópias locais e configurações.
- Crie um arquivo descritor protobuf autocontido a partir do seu arquivo de serviço
.proto
:- Salve uma cópia de
bookstore.proto
do repositório de exemplo no seu diretório de trabalho atual. Esse arquivo define a API do serviço Bookstore. - Crie o seguinte diretório no diretório de trabalho:
mkdir generated_pb2
- Crie o arquivo de descritor,
api_descriptor.pb
, usando o compilador de buffers de protocoloprotoc
. Execute o seguinte comando no diretório onde você salvoubookstore.proto
:python3 -m grpc_tools.protoc \ --include_imports \ --include_source_info \ --proto_path=. \ --descriptor_set_out=api_descriptor.pb \ --python_out=generated_pb2 \ --grpc_python_out=generated_pb2 \ bookstore.proto
No comando anterior,
--proto_path
está definido como o diretório de trabalho atual. No ambiente da versão do gRPC, caso você use um diretório diferente para arquivos de entrada.proto
, mude--proto_path
para que o compilador pesquise o diretório em que salvoubookstore.proto
.
- Salve uma cópia de
-
Crie um arquivo de texto chamado
api_config.yaml
no diretório de trabalho atual (o mesmo diretório que contémbookstore.proto
). Por conveniência, esta página refere-se ao documento de configuração da API gRPC pelo nome do arquivo, mas você pode nomear algo diferente, se preferir. Adicione o seguinte conteúdo ao arquivo: O recuo é importante para o formato yaml. Por exemplo, o campo# The configuration schema is defined by the service.proto file. # https://github.com/googleapis/googleapis/blob/master/google/api/service.proto type: google.api.Service config_version: 3 name: CLOUD_RUN_HOSTNAME title: Cloud Endpoints + Cloud Run gRPC apis: - name: endpoints.examples.bookstore.Bookstore usage: rules: # ListShelves methods can be called without an API Key. - selector: endpoints.examples.bookstore.Bookstore.ListShelves allow_unregistered_calls: true backend: rules: - selector: "*" address: grpcs://BACKEND_HOST_NAME
name
precisa estar no mesmo nível detype
. No campo
name
, especifique CLOUD_RUN_HOSTNAME, a parte do nome do host do URL que foi reservada acima em Como reservar um nome de host do Cloud Run. Não inclua o identificador de protocolo, comohttps://
ougrpcs://
.No campo
address
na seçãobackend.rules
, substitua BACKEND_HOST_NAME pelo serviço real do Cloud Run gRPC Criado em Antes de começar.Anote o valor da propriedade
title
no arquivoapi_config.yaml
:title: Cloud Endpoints + Cloud Run gRPC
O valor da propriedade
title
se tornará o nome do serviço do Endpoints depois que você implantar a configuração.- Salve o documento de configuração da API gRPC.
Para saber mais, consulte Como configurar o Endpoints.
Como implantar a configuração do Endpoints
Para implantar a configuração do Endpoints, use o comando gcloud endpoints services deploy
. Ele utiliza o Service Management para criar um serviço gerenciado.
- Verifique se você está no diretório onde os arquivos
api_descriptor.pb
eapi_config.yaml
estão localizados. - Confirme se o projeto padrão que a ferramenta de linha de comando
gcloud
está usando no momento é o projeto do Google Cloud em que você pretende implantar a configuração do Endpoints. Valide o código do projeto retornado do comando a seguir para garantir que o serviço não seja criado no projeto incorreto.gcloud config list project
Se você precisar alterar o projeto padrão, execute o comando:
gcloud config set project YOUR_PROJECT_ID
- Implante o arquivo
proto descriptor
e o arquivo de configuração usando o Google Cloud CLI:gcloud endpoints services deploy api_descriptor.pb api_config.yaml
Durante a criação e a configuração do serviço, o Service Management envia informações ao terminal. Quando a implantação for concluída, uma mensagem parecida com esta será exibida:
Service Configuration [CONFIG_ID] uploaded for service [bookstore.endpoints.example-project.cloud.goog]
CONFIG_ID é o ID exclusivo de configuração de serviço do Endpoints criado pela implantação. Exemplo:
Service Configuration [2017-02-13r0] uploaded for service [bookstore.endpoints.example-project.cloud.goog]
No exemplo anterior,
2017-02-13r0
é o ID de configuração do serviço ebookstore.endpoints.example-project.cloud.goog
é o nome do serviço. O código de configuração do serviço consiste em um carimbo de data e um número de revisão. Se você implantar novamente a configuração do Endpoints no mesmo dia, o número de revisão será alterado no código da configuração do serviço.
Como verificar os serviços obrigatórios
No mínimo, o Endpoints e o ESP exigem a ativação dos seguintes serviços do Google:Nome | Título |
---|---|
servicemanagement.googleapis.com |
API Service Management |
servicecontrol.googleapis.com |
API Service Control |
endpoints.googleapis.com |
Google Cloud Endpoints |
Na maioria dos casos, o comando gcloud endpoints services deploy
ativa os serviços necessários. No entanto, o comando gcloud
é concluído com êxito, mas não ativa os serviços necessários nas seguintes circunstâncias:
Você usou um aplicativo de terceiros, como o Terraform, e não incluiu esses serviços.
Você implantou a configuração do Endpoints em um projeto do Google Cloud existente, em que esses serviços foram desativados explicitamente.
Use o seguinte comando para confirmar se os serviços necessários estão ativados:
gcloud services list
Se você não encontrar os serviços necessários listados, ative-os:
gcloud services enable servicemanagement.googleapis.comgcloud services enable servicecontrol.googleapis.com
gcloud services enable endpoints.googleapis.com
Ative também seu serviço do Endpoints:
gcloud services enable ENDPOINTS_SERVICE_NAME
Para determinar o ENDPOINTS_SERVICE_NAME, é possível:
Após implantar a configuração do Endpoints, acesse a página Endpoints no Console do Cloud. A lista de ENDPOINTS_SERVICE_NAME possíveis é mostrada na coluna Nome do serviço.
Para a OpenAPI, o ENDPOINTS_SERVICE_NAME é o que você especificou no campo
host
da especificação do OpenAPI. Para gRPC, o ENDPOINTS_SERVICE_NAME é o que você especificou no camponame
da configuração do gRPC Endpoints.
Para mais informações sobre os comandos gcloud
, consulte serviços gcloud
.
Se você receber uma mensagem de erro, consulte Como solucionar problemas de implantação na configuração do Endpoints.
Para mais informações, consulte Como implantar a configuração do Endpoints.
Como criar uma nova imagem do ESPv2
Crie a configuração do serviço do Endpoints em uma nova imagem docker do ESPv2. Em seguida, você implantará essa imagem no serviço reservado do Cloud Run.
Para criar a configuração do serviço em uma nova imagem docker do ESPv2:
Faça o download deste script em sua máquina local em que a gcloud CLI está instalada.
Execute o script com o seguinte comando:
chmod +x gcloud_build_image
./gcloud_build_image -s CLOUD_RUN_HOSTNAME \ -c CONFIG_ID -p ESP_PROJECT_ID
Para CLOUD_RUN_HOSTNAME, especifique o nome do host do URL que você reservou acima em Como reservar um nome de host do Cloud Run. Não inclua o identificador de protocolo,
https://
.Por exemplo:
chmod +x gcloud_build_image
./gcloud_build_image -s gateway-12345-uc.a.run.app \ -c 2019-02-01r0 -p your-project-id
-
O script usa o comando da
gcloud
para fazer o download da configuração do serviço, criar essa configuração em uma nova imagem do ESPv2 e fazer upload da nova imagem para o registro de contêiner do projeto. O script usa automaticamente a versão mais recente do ESPv2, indicada pela ESP_VERSION no nome da imagem de saída. O upload da imagem de saída é feito para:gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID
Exemplo:
gcr.io/your-project-id/endpoints-runtime-serverless:2.14.0-gateway-12345-uc.a.run.app-2019-02-01r0"
Como implantar o contêiner do ESPv2
Implante o serviço do Cloud Run do ESPv2 com a nova imagem que você criou acima. Substitua CLOUD_RUN_SERVICE_NAME pelo mesmo nome de serviço do Cloud Run que você usou quando reservou originalmente o nome do host acima em Como reservar um nome de host do Cloud Run:
gcloud run deploy CLOUD_RUN_SERVICE_NAME \ --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \ --allow-unauthenticated \ --platform managed \ --project=ESP_PROJECT_ID
Se você quiser configurar o Endpoints para usar opções adicionais de inicialização do ESPv2, como a de ativar o CORS, passe os argumentos na variável de ambiente
ESPv2_ARGS
:gcloud run deploy CLOUD_RUN_SERVICE_NAME \ --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \ --set-env-vars=ESPv2_ARGS=--cors_preset=basic \ --allow-unauthenticated \ --platform managed \ --project ESP_PROJECT_ID
Para mais informações e exemplos sobre como configurar a variável de ambiente
ESPv2_ARGS
, incluindo a lista de opções disponíveis e informações sobre como especificar várias opções, consulte Sinalizações do Extensible Service Proxy V2.- Conceda permissão ao ESPv2 para invocar os serviços do Cloud Run.
Execute o seguinte comando para cada serviço. No seguinte comando:
- Substitua BACKEND_SERVICE_NAME pelo nome do serviço do Cloud Run que está sendo invocado. Se você estiver usando o serviço criado pela implantação de `gcr.io/endpointsv2/python-grpc-bookstore-server:2`, use
python-grpc-bookstore-server
como este valor. - Substitua ESP_PROJECT_NUMBER pelo número do projeto criado para o ESPv2. Uma forma de descobrir isso é acessar IAM no console do Google Cloud e encontre o Conta de serviço padrão do Compute, que é a conta de serviço usada no a sinalização `member`.
gcloud run services add-iam-policy-binding BACKEND_SERVICE_NAME \ --member "serviceAccount:ESP_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \ --role "roles/run.invoker" \ --platform managed \ --project BACKEND_PROJECT_ID
- Substitua BACKEND_SERVICE_NAME pelo nome do serviço do Cloud Run que está sendo invocado. Se você estiver usando o serviço criado pela implantação de `gcr.io/endpointsv2/python-grpc-bookstore-server:2`, use
Para mais informações, consulte Como gerenciar o acesso usando o IAM.
Como enviar solicitações à API
Para enviar solicitações à API de amostra, use um cliente gRPC de amostra escrito em Python.
Clone o repositório do Git onde o código do cliente gRPC está hospedado:
git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
Altere o diretório de trabalho:
cd python-docs-samples/endpoints/bookstore-grpc/
Instale as dependências:
pip3 install virtualenv
virtualenv env
source env/bin/activate
pip3 install -r requirements.txt
Envie uma solicitação à API de amostra:
python3 bookstore_client.py --host CLOUD_RUN_HOSTNAME --port 443 --use_tls true
Especifique o nome do host do seu serviço ESPv2 do Cloud Run em CLOUD_RUN_HOSTNAME, sem o identificador de protocolo. Por exemplo:
python3 bookstore_client.py --host espv2-grpc-HASH-uc.a.run.app --port 443 --use_tls true
Veja os gráficos de atividade da API na página Endpoints > Serviços.
Ir para a página Serviços do Endpoints
Pode levar alguns instantes até a solicitação aparecer nos gráficos.
Verifique os registros de solicitações da API na página "Explorador de registros".
Se não receber uma resposta bem-sucedida, consulte Como solucionar problemas em erros de resposta.
Você acaba de implantar e testar uma API no Endpoints.
Rastrear a atividade da API
Confira os gráficos de atividade da API na página Endpoints > Serviço no console do Google Cloud.
Ver gráficos de atividades do Endpoints
Pode levar alguns instantes até a solicitação aparecer nos gráficos.
Verifique os registros de solicitações da API na página "Visualizador de registros".
Como criar um portal do desenvolvedor para a API
É possível usar o Portal do Cloud Endpoints para criar um portal do desenvolvedor, um site que você pode usar para interagir com a API de amostra. Para saber mais, consulte a Visão geral do Portal do Cloud Endpoints.
Limpar
Para evitar cobranças na conta do Google Cloud pelos recursos usados nesta página, siga estas etapas.
Consulte Como excluir uma API e as instâncias relacionadas para mais informações sobre como interromper os serviços usados neste tutorial.