Primeiros passos com o Endpoints para o GKE com o ESP

OpenAPI | gRPC

Neste tutorial, você aprende a implantar um exemplo simples do serviço gRPC com o Extensible Service Proxy (ESP) no Google Kubernetes Engine (GKE). A versão Python da amostra bookstore-grpc é utilizada neste tutorial. Consulte as amostras de gRPC em outras linguagens na seção A seguir.

Neste tutorial, são usadas imagens de contêiner predefinidas do exemplo de código e do ESP, que são armazenadas no Artifact Registry. Se você não está familiarizado com os contêineres, consulte as páginas a seguir para saber mais:

• Como implantar um aplicativo da Web em contêiner
• Imagens de contêiner do Kubernetes

Para uma visão geral do Cloud Endpoints, consulte Sobre o Endpoints e Arquitetura do Endpoints.

Objetivos

Ao seguir o tutorial, use a lista detalhada de tarefas abaixo. Em todas elas, é necessário que as solicitações para a API sejam enviadas com sucesso.

1. Configure um projeto do Google Cloud e faça o download do software necessário. Consulte Antes de começar.
2. Copie e configure arquivos da amostra bookstore-grpc. Consulte Como configurar o Endpoints.
3. Implante a configuração do Endpoints para criar um serviço dele. Consulte Como implantar a configuração do Endpoints.
4. Crie um back-end para exibir a API e implante-a. Consulte Como implantar o back-end da API.
5. Consiga o endereço IP externo do serviço. Consulte Como conseguir o endereço IP externo do serviço.
6. Envie uma solicitação para a API. Consulte Como enviar uma solicitação para a API.
7. Para evitar cobranças na sua conta do Google Cloud . Consulte liberar espaço.

Custos

Neste documento, você vai usar os seguintes componentes faturáveis do Google Cloud:

• GKE
• Endpoints

Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços.

Novos usuários do Google Cloud podem estar qualificados para um teste sem custo financeiro.

Ao concluir as tarefas descritas neste documento, é possível evitar o faturamento contínuo excluindo os recursos criados. Para mais informações, consulte Limpeza.

Antes de começar

Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

1. Anote o ID do projeto Google Cloud , porque ele será necessário mais tarde.
2. Instale e inicialize a Google Cloud CLI.
3. Atualize a CLI gcloud e instale os componentes do Endpoints.

   gcloud components update

4. Verifique se a Google Cloud CLI (gcloud) está autorizada a acessar seus dados e serviços em Google Cloud:

   gcloud auth login

   Uma nova guia do navegador será aberta e você precisará escolher uma conta.
5. Defina o projeto padrão como o ID do projeto.

   gcloud config set project YOUR_PROJECT_ID

   Substitua YOUR_PROJECT_ID pela ID do seu projeto.

   Se você tiver outros projetos do Google Cloud e quiser usar gcloud para gerenciá-los, consulte Como gerenciar configurações da CLI gcloud.

6. Instale kubectl:

   gcloud components install kubectl

7. Consiga novas credenciais de usuário a serem usadas como credenciais padrão do aplicativo. As credenciais do usuário são necessárias para autorizar kubectl.

   gcloud auth application-default login

   Na nova guia do navegador que se abre, escolha uma conta.
8. 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.

Como configurar o Endpoints

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

1. Create a self-contained protobuf descriptor file from your service .proto file:
   1. Save a copy of bookstore.proto from the example repository. This file defines the Bookstore service's API.
   2. Create the following directory: mkdir generated_pb2
   3. Create the descriptor file, api_descriptor.pb, by using the protoc protocol buffers compiler. Run the following command in the directory where you saved bookstore.proto:

      python -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

      In the preceding command, --proto_path is set to the current working directory. In your gRPC build environment, if you use a different directory for .proto input files, change --proto_path so the compiler searches the directory where you saved bookstore.proto.

2. Create a gRPC API configuration YAML file:
   1. Save a copy of the api_config.yamlfile. This file defines the gRPC API configuration for the Bookstore service.
   2. Replace MY_PROJECT_ID in your api_config.yaml file with your Google Cloud project ID. For example:

      #
      # Name of the service configuration.
      #
      name: bookstore.endpoints.example-project-12345.cloud.goog
      

      Note that the apis.name field value in this file exactly matches the fully-qualified API name from the .proto file; otherwise deployment won't work. The Bookstore service is defined in bookstore.proto inside package endpoints.examples.bookstore. Its fully-qualified API name is endpoints.examples.bookstore.Bookstore, just as it appears in the api_config.yaml file.

      apis:
        - name: endpoints.examples.bookstore.Bookstore

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 Google Cloud em que você quer 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 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 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

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 doGoogle Cloud atual em que esses serviços foram explicitamente desativados.

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

Ative também seu serviço do Endpoints:

gcloud services enable ENDPOINTS_SERVICE_NAME

Para determinar o ENDPOINTS_SERVICE_NAME, é possível:

• Depois de 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 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 implantar o back-end da API

Até agora, você implantou a configuração do serviço no Service Management, mas não o código que exibe o back-end da API. Nesta seção, você aprenderá a criar um cluster do GKE para hospedar o back-end da API e implantá-la.

Como criar um cluster de contêiner

Para criar um cluster de contêiner de exemplo:

1. No console do Google Cloud , acesse a página de clusters do Kubernetes.
   

   Acessar a página de clusters do Kubernetes

2. Clique em Criar cluster.
3. Aceite as configurações padrão e clique em Criar. Anote a zona e o nome do cluster. Eles serão necessários mais adiante neste tutorial.

Como autenticar kubectl no cluster de contêiner

Para criar e gerenciar recursos do cluster com kubectl, é preciso ter credenciais do cluster disponíveis para kubectl. Para isso, execute o comando a seguir, substituindo NAME pelo nome do novo cluster e ZONE pela zona do cluster.

gcloud container clusters get-credentials NAME --zone ZONE

Como verificar as permissões necessárias

O ESP e o ESPv2 chamam os serviços do Google que usam o IAM para verificar se a identidade da chamada tem permissões suficientes para acessar os recursos do IAM usados. A identidade de chamada é a conta de serviço anexada que implanta o ESP e o ESPv2.

Quando implantada no pod do GKE, a conta de serviço anexada é a conta de serviço do nó. Ela costuma ser a conta de serviço padrão do Compute Engine. Siga esta recomendação de permissão para escolher uma conta de serviço de nó adequada.

Se a Identidade da carga de trabalho for usada, uma conta de serviço separada diferente da conta de serviço do nó poderá ser usada para falar com os serviços do Google. É possível criar uma conta de serviço do Kubernetes para o pod executar o ESP e o ESPv2. Além disso, você pode criar uma conta de serviço do Google e associá-la à do Kubernetes.

Siga estas etapas para associar uma conta de serviço do Kubernetes a uma conta de serviço do Google. Esta conta de serviço do Google é a conta de serviço anexada.

Se a conta de serviço anexada for a conta de serviço padrão do Compute Engine do projeto e a configuração do serviço do endpoint for implantada no mesmo projeto, a conta de serviço já deve ter permissões suficientes para acessar os recursos do IAM, então a etapa a seguir pode ser pulada. Caso contrário, adicione os papéis do IAM à conta de serviço anexada.

Adicione os papéis necessários do IAM:

Nesta seção, descrevemos os recursos do IAM que o ESP e o ESPv2 usam, além dos papéis do IAM necessários para que a conta de serviço anexada acesse esses recursos.

Configuração do serviço de endpoint

O ESP e o ESPv2 chamam o Service Control, que usa a configuração do serviço do endpoint. A configuração do serviço do endpoint é um recurso do IAM, e o ESP e o ESPv2 precisam do papel Controlador de serviço para acessá-lo.

O papel do IAM está na configuração do serviço do endpoint, não no projeto. Os projetos podem ter várias configurações de serviço de endpoint.

Use o comando gcloud a seguir para adicionar o papel à conta de serviço anexada na configuração do serviço do endpoint.

gcloud endpoints services add-iam-policy-binding SERVICE_NAME \
  --member serviceAccount:SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com \
  --role roles/servicemanagement.serviceController

Em que
* SERVICE_NAME é o nome do serviço do endpoint
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com é a conta de serviço anexada.

Cloud Trace

O ESP e o ESPv2 chamam o serviço Cloud Trace para exportar o Trace para um projeto. Esse projeto é chamado de projeto de rastreamento. No ESP, o projeto de rastreamento e o projeto que tem a configuração do serviço de endpoint são os mesmos. No ESPv2, o projeto de rastreamento pode ser especificado pela sinalização --tracing_project_id e assume como padrão o projeto de implantação.

O ESP e o ESPv2 exigem o papel Agente do Cloud Trace para ativar o Cloud Trace.

Use o seguinte comando gcloud para adicionar o papel à conta de serviço anexada:

gcloud projects add-iam-policy-binding TRACING_PROJECT_ID \
  --member serviceAccount:SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com \
  --role roles/cloudtrace.agent

Em que
* TRACING_PROJECT_ID é o ID do projeto de rastreamento
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com é a conta de serviço anexada. Para mais informações, consulte O que são funções e permissões?

Implantação da API de exemplo e ESP no cluster

Veja como implantar o exemplo do serviço do gRPC no cluster a ser usado pelos clientes:

1. Salve e abra uma cópia do arquivo do manifesto de implantação grpc-bookstore.yaml para editá-lo.
2. Substitua SERVICE_NAME pelo nome do serviço do Endpoints. Este é o mesmo nome configurado no campo name do arquivo api_config.yaml.
   spec:
     containers:
     - name: esp
       image: gcr.io/endpoints-release/endpoints-runtime:1
       args: [
         "--http2_port=9000",
         "--service=SERVICE_NAME",
         "--rollout_strategy=managed",
         "--backend=grpc://127.0.0.1:8000"
       ]
       ports:
         - containerPort: 9000
     - name: bookstore
       image: gcr.io/endpointsv2/python-grpc-bookstore-server:1
       ports:
         - containerPort: 8000

   A opção --rollout_strategy=managed configura o ESP para usar as configurações de serviço implantadas mais recentes. Quando você especifica essa opção, até 5 minutos depois de implantar uma nova configuração de serviço, o ESP detecta a alteração e começa a usá-la automaticamente. Recomendamos especificar essa opção em vez de um ID de configuração específico para uso do ESP. Para mais detalhes sobre os argumentos do ESP, consulte Opções de inicialização do ESP.

   Exemplo:

       spec:
         containers:
         - name: esp
           image: gcr.io/endpoints-release/endpoints-runtime:1
           args: [
             "--http2_port=9000",
             "--service=bookstore.endpoints.example-project-12345.cloud.goog",
             "--rollout_strategy=managed",
             "--backend=grpc://127.0.0.1:8000"
           ]

   Recomendamos que você defina imagePullPolicy na especificação do contêiner acima como Always. Isso permitirá que os pods recém-criados sempre usem a versão mais recente do ESP. Leia sobre as práticas recomendadas de configuração para mais detalhes. Quando uma nova versão do ESP é lançada, é possível executar uma reinicialização contínua de todos os pods para garantir que a versão mais recente seja usada.

3. Inicie o serviço:

   kubectl create -f grpc-bookstore.yaml
   

Observação: se o cluster do GKE for particular, use o servidor de metadados do Compute Engine como o resolvedor de DNS para resolver nomes de host de serviço do Google. Adicione esta sinalização do ESP: --dns=169.254.169.254

Se você receber uma mensagem de erro, consulte Como solucionar problemas do Endpoints no GKE.

Como conseguir o endereço IP externo do serviço

É necessário o endereço IP externo do serviço para enviar solicitações à API de amostra. Pode demorar alguns minutos depois de iniciar o serviço no contêiner antes que o endereço IP externo esteja pronto.

1. Veja o endereço IP externo:

   kubectl get service

2. Anote o valor de EXTERNAL-IP e salve-o em uma variável de ambiente SERVER_IP. O endereço IP externo é usado para enviar solicitações à API de amostra.

   export SERVER_IP=YOUR_EXTERNAL_IP
   

Como enviar uma solicitação à API

To send requests to the sample API, you can use a sample gRPC client written in Python.

1. Clone the git repo where the gRPC client code is hosted:

   git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
      

2. Change your working directory:

   cd python-docs-samples/endpoints/bookstore-grpc/
     

3. Install dependencies:

   pip install virtualenv
   virtualenv env
   source env/bin/activate
   python -m pip install -r requirements.txt

4. Send a request to the sample API:

   python bookstore_client.py --host SERVER_IP --port 80
   

   • Look at the activity graphs for your API in the Endpoints > Services page.
     

     Go to the Endpoints Services page

     It may take a few moments for the request to be reflected in the graphs.

   • Look at the request logs for your API in the Logs Explorer page.
     

     Go to the Logs Explorer page

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.

Observação: se quiser nos contar do que você gostou neste tutorial, envie um feedback na parte inferior desta página. Isso é muito importante para a melhoria dos tutoriais.
Se ocorrer um erro, entre no grupo do Google google-cloud-endpoints e informe o que aconteceu. Nesse grupo, são enviadas respostas de outros usuários do Endpoints e de engenheiros do Google, que o monitoram.

Limpar

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados no tutorial, exclua o projeto que os contém ou mantenha o projeto e exclua os recursos individuais.

1. Exclua a API:

   gcloud endpoints services delete SERVICE_NAME
   

   Substitua SERVICE_NAME pelo nome da API.

2. Exclua o cluster do GKE:

   gcloud container clusters delete NAME --zone ZONE
   

A seguir

• Descubra como configurar a API do gRPC do Cloud Endpoints.
• Consulte a amostra do Bookstore no GitHub para saber mais. Tanto o cliente quanto o servidor estão disponíveis em Python e em Java (links em inglês).
• A amostra getting-started-grpc está disponível no GitHub nos seguintes idiomas:
  • Java
  • Python
  • Ruby
  • Go
  • Node.js