Primeiros passos com Endpoints para Cloud Run

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 Beta (ESPv2 Beta) como um gateway de API. Para fornecer o gerenciamento de APIs para o Cloud Run, implante o contêiner pré-criado do ESPv2 Beta para Cloud Run. Em seguida, ajude a proteger seus serviços usando o IAM do Cloud Run para que o ESPv2 Beta possa invocá-los.

Com essa configuração, o ESPv2 Beta 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, a telemetria é coletada e relatada pelo ESPv2 Beta. É possível ver métricas do seu 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 Beta

As versões anteriores do Cloud Endpoints não eram compatíveis com o gRPC no Cloud Run com ESP. Faça o seguinte: migre para o Extensible Service Proxy V2 Beta para usar este recurso.

Lista de tarefas

Ao seguir o tutorial, use a lista de tarefas abaixo. Todas as tarefas são necessárias para concluir este tutorial.

  1. Crie um projeto do Google Cloud e, se você não tiver implantado seu próprio Cloud Run, implante um serviço gRPC de amostra. Consulte Antes de começar.
  2. Implante o contêiner do ESPv2 Beta no Cloud Run. Consulte Como implantar o ESPv2 Beta.
  3. 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.
  4. Implante o documento de configuração da API gRPC para criar um serviço gerenciado. Consulte Como implantar a configuração do Endpoints.
  5. Crie e implante uma nova imagem do Docker do ESPv2 Beta com a configuração do serviço do Endpoints. Em seguida, conceda ao ESPv2 Beta a permissão de Gerenciamento de identidade e acesso (IAM, na sigla em inglês) para invocar seu serviço. Consulte Como criar uma nova imagem do ESPv2 Beta.
  6. Chamar um serviço. Consulte Como enviar uma solicitação à API.
  7. Rastrear a atividade para seus serviços. Consulte Como rastrear a atividade da API.
  8. Evite cobranças na sua conta do Google Cloud. Consulte Limpeza.

Antes de começar

Para configurar:

  1. No Console do Cloud, acesse a página Gerenciar recursos e crie um projeto.

    Acessar a página Gerenciar recursos

  2. Verifique se o faturamento foi ativado para o projeto.

    Saiba como ativar o faturamento

  3. Anote o ID do projeto, porque ele será necessário mais tarde. No restante desta página, esse ID do projeto é chamado de ESP_PROJECT_ID.

  4. 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.

  5. Faça o download do SDK do Cloud e instale-o.

    Fazer o download do Cloud SDK

  6. 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.

  7. Implante o serviço gRPC de amostra do Cloud Run 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 implantado é chamado de BACKEND_SERVICE_NAME.

Como implantar o ESPv2 Beta

Para implantar o contêiner do ESPv2 Beta no Cloud Run, siga estas etapas:

  1. Verifique se o SDK do Cloud tem autorização para acessar seus dados e serviços:
    1. Faça login.
      gcloud auth login
    2. 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 Beta no Cloud Run.
  2. Defina a região.
    gcloud config set run/region us-central1
  3. Implante o ESPv2 Beta 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/endpoints-release/endpoints-runtime-serverless:2" \
        --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 e gateway-12345-uc.a.run.app é o CLOUD_RUN_HOSTNAME.

  4. Anote CLOUD_RUN_HOSTNAME. Especifique o CLOUD_RUN_HOSTNAME no campo name do documento de configuração da API gRPC em uma etapa posterior).
  5. È possível verificar se a versão inicial do ESPv2 Beta está implantada no Cloud Run visitando o CLOUD_RUN_SERVICE_URL no seu navegador da Web. Você verá uma mensagem de aviso sobre uma variável de ambiente ausente. Esta mensagem de aviso é esperada e será exibida até que a etapa Criando uma nova imagem Beta do ESPv2 seja concluída.
  6. Seu serviço Cloud Run é público na Internet. Se você quiser adicionar recursos de autenticação, recomendamos usar um dos métodos de autenticação aceitos pelo Endpoints.

Configurar o Endpoints

A amostra bookstore-grpc contém os arquivos necessários para fazer cópias locais e configurações.

  1. Crie um arquivo descritor protobuf autocontido a partir do seu arquivo de serviço .proto:
    1. 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.
    2. Crie o seguinte diretório no diretório de trabalho: mkdir generated_pb2
    3. Crie o arquivo de descritor, api_descriptor.pb, usando o compilador de buffers de protocolo protoc. Execute o seguinte comando no diretório onde você salvou bookstore.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 salvou bookstore.proto.

  2. Crie um arquivo de texto chamado api_config.yaml no diretório de trabalho atual (o mesmo diretório que contém bookstore.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:
    # 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://python-grpc-bookstore-server-HASH-uc.a.run.app
    
    O recuo é importante para o formato yaml. Por exemplo, o campo name deve estar no mesmo nível de type.
  3. No campo name, especifique CLOUD_RUN_HOSTNAME, a parte do nome do host do URL que o Cloud Run criou quando você implementou o ESPv2 Beta acima em Como implantar o ESPv2 Beta. Não inclua o identificador de protocolo, https:// ou grpcs://.

  4. No campo address na seção backend.rules, substitua grpcs://python-grpc-bookstore-server-HASH-uc.a.run.app pelo URL real do serviço gRPC de amostra do Cloud Run python-grpc-bookstore-server, em que HASH é o código hash exclusivo gerado quando você criou o serviço.

    Este exemplo presume que você está usando o serviço gRPC Bookstore criado em Antes de começar. Se necessário, substitua esse valor pelo URL do serviço Cloud Run.

  5. Anote o valor da propriedade title no arquivo api_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.

  6. 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.

  1. Verifique se você está no diretório onde os arquivos api_descriptor.pb e api_config.yaml estão localizados.
  2. 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
    
  3. Implante o arquivo proto descriptor e o arquivo de configuração usando a ferramenta de linha de comando gcloud:
    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 e bookstore.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.com
gcloud 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 Pontos de extremidade 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 campo name 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 Beta

Crie a configuração do serviço do Endpoints em uma nova imagem docker do ESPv2 Beta e reimplante o serviço Cloud Run do ESPv2 Beta com a imagem. Em seguida, conceda ao ESPv2 Beta a permissão do IAM para invocar seus serviços.

Para criar a configuração do serviço em uma nova imagem docker do ESPv2 Beta:

  1. Faça o download deste script em sua máquina local em que o SDK da gcloud está instalado e execute-o como:

    chmod +x gcloud_build_image
    
    ./gcloud_build_image -s CLOUD_RUN_HOSTNAME \
        -c CONFIG_ID -p ESP_PROJECT_ID

    Para o CLOUD_RUN_HOSTNAME, especifique o nome do host do URL que o Cloud Run criou quando você implementou o ESPv2 Beta acima, na seção Como implantar o ESPv2 Beta. Não inclua o identificador de protocolo, https://.

    Exemplo:

    chmod +x gcloud_build_image
    ./gcloud_build_image -s gateway-12345-uc.a.run.app \
        -c 2019-02-01r0 -p ESP_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 Beta e fazer upload da nova imagem para o registro de contêiner do projeto localizado aqui:

    gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:CLOUD_RUN_HOSTNAME-CONFIG_ID

    Exemplo:

    gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:gateway-12345-uc.a.run.app-2019-02-01r0"
  2. Implante novamente o serviço Cloud Run do ESPv2 Beta com a nova imagem. Substitua CLOUD_RUN_SERVICE_NAME pelo mesmo nome de serviço do Cloud Run que você usou quando o implantou originalmente em Como implantar o ESPv2 Beta:

    gcloud run deploy CLOUD_RUN_SERVICE_NAME \
      --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:CLOUD_RUN_HOSTNAME-CONFIG_ID" \
      --allow-unauthenticated \
      --platform managed \
      --project=ESP_PROJECT_ID
  3. Se você quiser configurar o Endpoints para usar opções adicionais de inicialização do ESPv2 Beta, como ativar o CORS, por exemplo, 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: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 Beta.

  4. Conceda permissão ao ESPv2 Beta para invocar seus 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 Beta. Uma maneira de encontrar isso é acessando a página IAM no Console do Cloud e encontrar a conta de serviço de computação padrão, que é a conta de serviço usada na 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

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.

  1. 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
  2. Altere o diretório de trabalho:

    cd python-docs-samples/endpoints/bookstore-grpc/
  3. Instale as dependências:

    pip3 install virtualenv
    virtualenv env
    source env/bin/activate
    pip3 install -r requirements.txt
  4. 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 Beta do Cloud Run em CLOUD_RUN_HOSTNAME, sem o identificador de protocolo. Exemplo:

    python3 bookstore_client.py --host espv2-grpc-HASH-uc.a.run.app --port 443 --use_tls true

Caso não receba uma resposta bem-sucedida, consulte Como solucionar problemas em erros de resposta.

Você acaba de implantar e testar uma API no Endpoints.

Como rastrear atividade da API

  1. Veja os gráficos de atividade para sua API na página Endpoints > Serviço no Console do Cloud.

    Ver gráficos de atividades do Endpoints

    Pode levar alguns instantes até a solicitação aparecer nos gráficos.

  2. Verifique os registros de solicitações da API na página "Visualizador de registros".

    Ver registros de solicitações do Endpoints

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 para interagir com a API de exemplo. Para saber mais, consulte a Visão geral do Portal do Cloud Endpoints.

Limpeza

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados neste guia de início rápido, 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.

A seguir