Primeiros passos com o Endpoints para Kubernetes com ESP

Este tutorial mostra como implantar um exemplo simples do serviço gRPC com o Extensible Service Proxy (ESP) em um cluster do Kubernetes que não está em execução no Google Cloud. A versão Python da amostra bookstore-grpc é utilizada neste tutorial. Consulte a seção A seguir para ter acesso a exemplos do gRPC em outras linguagens.

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

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 Cloud Endpoints.
  3. Implante a configuração do Endpoints para criar um serviço dele. Consulte Como implantar a configuração do Endpoints.
  4. Crie credenciais para o serviço do Endpoints. Consulte Como criar credenciais para o serviço.
  5. Crie um back-end para exibir a API e implante-a. Consulte Como implantar o back-end da API.
  6. Consiga o endereço IP externo do serviço. Consulte Como conseguir o endereço IP externo do serviço.
  7. Envie uma solicitação para a API. Consulte Como enviar uma solicitação para a API.
  8. Evite cobranças na sua conta do Google Cloud. Consulte Fazer 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. Novos usuários do Google Cloud podem estar qualificados para uma avaliação gratuita.

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 acompanhar este tutorial, é preciso ter uma configuração de cluster do Kubernetes ou Minikube. Para saber mais, consulte a Documentação do Kubernetes.

  1. Faça login na sua conta do Google Cloud. Se você começou a usar o Google Cloud agora, 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.

  2. No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

    Acessar o seletor de projetos

  3. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

  4. No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

    Acessar o seletor de projetos

  5. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

  6. Anote o ID do projeto do Google Cloud. Ele será necessário posteriormente.
  7. Instale e inicialize a CLI gcloud.
  8. Atualize a CLI gcloud e instale os componentes do Endpoints. 
    gcloud components update
  9. Verifique se a Google Cloud CLI (gcloud) está autorizada a acessar seus dados e serviços no Google Cloud: 
    gcloud auth login
    Na nova guia aberta, selecione uma conta.
  10. Defina o projeto padrão como o ID do projeto: 
    gcloud config set project
    YOUR_PROJECT_ID

    Substitua YOUR_PROJECT_ID pelo ID do seu projeto do Google Cloud.

    Se você tiver outros projetos do Google Cloud e quiser usar gcloud para gerenciá-los, consulte Como CLI gcloud gcloud.

  11. Instale kubectl: 
    gcloud components install kubectl
  12. Consiga novas credenciais de usuário a serem usadas para o Application Default Credentials. As credenciais de usuário são necessárias para autorizar o kubectl. 
    gcloud auth application-default login
  13. Na nova guia aberta do navegador, escolha uma conta.
  14. Siga as etapas no Início rápido do gRPC em Python 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. Esse comando usa a Service Infrastructure, a plataforma de serviços fundamentais do Google. Ela é usada pelo Endpoints e por outros serviços para criar e gerenciar APIs e serviços.

  1. Make sure you are in the directory where the api_descriptor.pb and api_config.yaml files are located.
  2. Confirm that the default project that the gcloud command-line tool is currently using is the Google Cloud project that you want to deploy the Endpoints configuration to. Validate the project ID returned from the following command to make sure that the service doesn't get created in the wrong project. 
    gcloud config list project

    If you need to change the default project, run the following command:

    gcloud config set project YOUR_PROJECT_ID
  3. Deploy the proto descriptor file and the configuration file by using the Google Cloud CLI: 
    gcloud endpoints services deploy api_descriptor.pb api_config.yaml

    As it is creating and configuring the service, Service Management outputs information to the terminal. When the deployment completes, a message similar to the following is displayed:

    Service Configuration [CONFIG_ID] uploaded for service [bookstore.endpoints.example-project.cloud.goog]

    CONFIG_ID is the unique Endpoints service configuration ID created by the deployment. For example:

    Service Configuration [2017-02-13r0] uploaded for service [bookstore.endpoints.example-project.cloud.goog]

    In the previous example, 2017-02-13r0 is the service configuration ID and bookstore.endpoints.example-project.cloud.goog is the service name. The service configuration ID consists of a date stamp followed by a revision number. If you deploy the Endpoints configuration again on the same day, the revision number is incremented in the service configuration ID.

Como verificar os serviços obrigatórios

O Endpoints e o ESP exigem que estes serviços do Google estejam ativados:
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:

  • 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 criar credenciais para o serviço

Para fornecer gerenciamento da API, o ESP e o ESPv2 exigem os serviços do Service Infrastructure. Para chamá-los, o ESP e o ESPv2 precisam usar tokens de acesso. Quando você implanta o ESP ou o ESPv2 nos ambientes do Google Cloud, como o GKE ou o Compute Engine, o ESP e o ESPv2 recebem tokens de acesso por meio do serviço de metadados do Google Cloud.

Ao implantar o ESP ou ESPv2 em um ambiente que não seja do Google Cloud, como seu computador local, um cluster do Kubernetes local ou outro provedor de nuvem, é preciso fornecer um arquivo JSON da conta de serviço que contém uma chave privada. O ESP e o ESPv2 usam a conta de serviço para gerar tokens de acesso e chamar os serviços necessários para gerenciar a API.

É possível usar o console do Google Cloud ou a Google Cloud CLI para criar a conta de serviço e o arquivo de chave privada:

Console

  1. No console do Google Cloud, abra a página Contas de serviço .

    Acesse a página Contas de serviço

  2. Clique em Selecione um projeto.
  3. Selecione o projeto em que a API foi criada e clique em Abrir.
  4. Clique em + Criar conta de serviço.
  5. No campo Nome da conta de serviço, insira o nome para sua conta de serviço.
  6. Clique em Criar.
  7. Clique em Continuar.
  8. Clique em Concluído.
  9. Clique no endereço de e-mail da conta de serviço recém-criada.
  10. Clique em Chaves.
  11. Clique em Adicionar chave e em Criar nova chave.

  12. Clique em Criar. O download de um arquivo de chave JSON é feito no seu computador.

    Armazene o arquivo de chave com segurança, porque ele pode ser usado para autenticar como sua conta de serviço. Mova e renomeie esse arquivo como quiser.

  13. Clique em Fechar.

gcloud

  1. Insira o comando a seguir para exibir os IDs dos seus projetos do Google Cloud:

    gcloud projects list

  2. Substitua PROJECT_ID no comando a seguir para definir o projeto que contém sua API como padrão:

    gcloud config set project PROJECT_ID

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

    gcloud auth login

    Se você tiver mais de uma conta, escolha a que está no projeto do Google Cloud e que contém a API. Se você executar gcloud auth list, a conta selecionada será mostrada como a ativa para o projeto.

  4. Para criar uma conta de serviço, execute o seguinte comando e substitua SERVICE_ACCOUNT_NAME e My Service Account pelo nome e pelo nome de exibição que você quer usar:

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
   --display-name "My Service Account"

    O comando atribui um endereço de e-mail para a conta de serviço no seguinte formato:

    SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

    Esse endereço de e-mail é necessário nos comandos subsequentes.

  5. Crie um arquivo da chave da conta de serviço:

    gcloud iam service-accounts keys create ~/service-account-creds.json \
   --iam-account SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

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?

Para mais informações sobre os comandos, consulte gcloud iam service-accounts.

Implantar o back-end da API

Até aqui, você implantou a configuração do serviço no Service Management, mas não o código que disponibilizará o back-end da API. Nesta seção, veja como implantar contêineres predefinidos da API de amostra e ESP no Kubernetes.

Como fornecer as credenciais de serviço ao ESP

O ESP, que é executado dentro de um contêiner, precisa acessar as credenciais armazenadas localmente no arquivo service-account-creds.json. Para que o ESP tenha acesso às credenciais, crie um secret do Kubernetes e ative-o como um volume do Kubernetes.

Para criar o secret do Kubernetes e ativar o volume:

  1. Se você usou o console do Google Cloud para criar a conta de serviço, renomeie o arquivo JSON para service-account-creds.json. Mova-o para o mesmo diretório em que os arquivos api_descriptor.pb e api_config.yaml estão localizados.

  2. Crie uma chave secreta do Kubernetes com as credenciais da conta de serviço:

     kubectl create secret generic service-account-creds
      --from-file=service-account-creds.json

    Caso consiga, verá a mensagem secret "service-account-creds" created.

O arquivo de manifesto de implantação usado para implantar a API e o ESP no Kubernetes já contém o volume secret, conforme mostrado nas duas seções do arquivo a seguir:

volumes:
  - name: service-account-creds
    secret:
      secretName: service-account-creds
volumeMounts:
  - mountPath: /etc/nginx/creds
    name: service-account-creds
    readOnly: true

Como configurar o nome do serviço e iniciar o serviço

O ESP precisa saber o nome do serviço para encontrar a configuração implantada anteriormente usando o comando gcloud endpoints services deploy.

Para configurar o nome do serviço e iniciá-lo:

  1. Salve uma cópia do arquivo de manifesto de implantação, k8s-grpc-bookstore.yaml, para o mesmo diretório service-account-creds.json.

  2. Abra k8s-grpc-bookstore.yaml e substitua SERVICE_NAME pelo nome do serviço do Endpoints. Este é o mesmo nome configurado no campo name do arquivo api_config.yaml.

    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",
      "--service_account_key=/etc/nginx/creds/service-account-creds.json"
    ]

    A opção --rollout_strategy=managed configura o ESP para usar a implantação mais recente da configuração do serviço. 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.

  3. Inicie o serviço para implantá-lo no Kubernetes:

    kubectl create -f k8s-grpc-bookstore.yaml

    Se for exibida uma mensagem de erro parecida com esta:

    The connection to the server localhost:8080 was refused - did you specify the right host or port?

    Isso indica que kubectl não está configurado corretamente. Consulte Configurar kubectl para mais informações.

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

Você precisa do endereço IP externo do serviço para enviar solicitações à API de amostra. Após o início do serviço no contêiner, pode levar alguns minutos para o endereço IP externo ficar 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, conforme usado ao enviar solicitações para a API de exemplo.

    export SERVER_IP=YOUR_EXTERNAL_IP

Como enviar uma solicitação à 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: 

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

  4. Envie uma solicitação à API de amostra:

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

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.

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