Introdução aos Endpoints para Kubernetes com o ESPv2

Este tutorial mostra como implementar um exemplo simples de um serviço gRPC com o Extensible Service Proxy V2 (ESPv2) num cluster do Kubernetes que não está a ser executado noGoogle Cloud. O tutorial usa a versão Python do exemplo bookstore-grpc. Consulte a secção O que se segue para ver exemplos de gRPC noutros idiomas.

O tutorial usa imagens de contentores pré-criadas do código de exemplo e do ESPv2, que estão armazenadas no Artifact Registry. Se não tiver familiaridade com os contentores, consulte o seguinte para mais informações:

Para uma vista geral do Cloud Endpoints, consulte os artigos Acerca dos Endpoints e Arquitetura dos Endpoints.

Objetivos

Use a seguinte lista de tarefas de alto nível à medida que avança no tutorial. Todas as tarefas são necessárias para enviar pedidos com êxito para a API.

  1. Configure um Google Cloud projeto e transfira o software necessário. Consulte a secção Antes de começar.
  2. Copie e configure ficheiros do exemplo bookstore-grpc. Consulte o artigo Configurar o Cloud Endpoints.
  3. Implemente a configuração do Endpoints para criar um serviço do Endpoints. Consulte o artigo Implementar a configuração dos Endpoints.
  4. Crie credenciais para o seu serviço Endpoints. Consulte o artigo Criar credenciais para o seu serviço.
  5. Crie um back-end para publicar a API e implemente a API. Consulte o artigo Implementar o back-end da API.
  6. Obtenha o endereço IP externo do serviço. Consulte o artigo Determinar o endereço IP externo do serviço.
  7. Envie um pedido para a API. Consulte o artigo Enviar uma solicitação para a API.
  8. Evite incorrer em cobranças na sua Google Cloud conta. Consulte a secção Limpar.

Custos

Neste documento, usa os seguintes componentes faturáveis do Google Cloud:

Para gerar uma estimativa de custos com base na sua utilização prevista, use a calculadora de preços.

Os novos Google Cloud utilizadores podem ser elegíveis para uma avaliação sem custo financeiro.

Quando terminar as tarefas descritas neste documento, pode evitar a faturação contínua eliminando os recursos que criou. Para mais informações, consulte o artigo Limpe.

Antes de começar

Este tutorial pressupõe que já tem o Minikube ou um cluster do Kubernetes configurado. Para mais informações, consulte a documentação do Kubernetes.

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

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

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. Tome nota do Google Cloud ID do projeto, uma vez que é necessário mais tarde.
  7. Instale e inicialize a CLI gcloud.
  8. Atualize a CLI gcloud e instale os componentes do Endpoints. 
    gcloud components update
  9. Certifique-se de que a CLI do Google Cloud (gcloud) está autorizada a aceder aos seus dados e serviços no Google Cloud: 
    gcloud auth login
     No novo separador apresentado, selecione uma conta.
  10. Defina o projeto predefinido para o ID do seu projeto: 
    gcloud config set project
    YOUR_PROJECT_ID

    Substitua YOUR_PROJECT_ID pelo ID do seu Google Cloud projeto.

    Se tiver outros Google Cloud projetos e quiser usá-los gcloud para os gerir, consulte Gerir configurações da CLI gcloud.

  11. Instalar kubectl: 
    gcloud components install kubectl
  12. Adquira novas credenciais de utilizador para usar com as Credenciais padrão da aplicação. As credenciais do utilizador são necessárias para autorizar kubectl. 
    gcloud auth application-default login
  13. No novo separador do navegador apresentado, escolha uma conta.
  14. Siga os passos no guia de início rápido do gRPC Python para instalar o gRPC e as ferramentas do gRPC.

Configurar pontos finais

O exemplo bookstore-grpc contém os ficheiros que tem de copiar localmente e configurar.

  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

Consulte o artigo Configurar pontos finais para mais informações.

Implementação da configuração dos pontos finais

Para implementar a configuração do Endpoints, use o comando gcloud endpoints services deploy. Este comando usa a infraestrutura de serviços, a plataforma de serviços fundamentais da Google, usada pelos Endpoints e outros serviços para criar e gerir 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.

Se receber uma mensagem de erro, consulte o artigo Resolução de problemas da implementação da configuração de endpoints.

Consulte o artigo Implementar a configuração dos Endpoints para ver informações adicionais.

A verificar os serviços necessários

No mínimo, os pontos finais e o ESP requerem a ativação dos seguintes serviços Google:
Nome Título
servicemanagement.googleapis.com Service Management API
servicecontrol.googleapis.com Service Control API

Na maioria dos casos, o comando gcloud endpoints services deploy ativa estes serviços obrigatórios. No entanto, o comando gcloud é concluído com êxito, mas não ativa os serviços necessários nas seguintes circunstâncias:

  • Se usou uma aplicação de terceiros, como o Terraform, e não incluiu estes serviços.

  • Implementou a configuração do Endpoints numGoogle Cloud projeto existente no qual estes serviços foram explicitamente desativados.

Use o seguinte comando para confirmar que os serviços necessários estão ativados:

gcloud services list

Se não vir os serviços necessários listados, ative-os:

gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

Ative também o serviço Endpoints:

gcloud services enable ENDPOINTS_SERVICE_NAME

Para determinar o ENDPOINTS_SERVICE_NAME, pode:

  • Após implementar a configuração do Endpoints, aceda à página Endpoints na Cloud Console. A lista de possíveis ENDPOINTS_SERVICE_NAME é apresentada na coluna Nome do serviço.

  • Para a OpenAPI, ENDPOINTS_SERVICE_NAME é o que especificou no campo host da sua especificação OpenAPI. Para o gRPC, ENDPOINTS_SERVICE_NAME é o que especificou no campo name da sua configuração de pontos finais gRPC.

Para mais informações sobre os comandos gcloud, consulte os serviços gcloud.

Criar credenciais para o seu serviço

Para fornecer gestão para a sua API, o ESP e o ESPv2 requerem os serviços na infraestrutura de serviços. Para chamar estes serviços, o ESP e o ESPv2 têm de usar tokens de acesso. Quando implementa o ESP ou o ESPv2 em Google Cloud ambientes, como o GKE ou o Compute Engine, o ESP e o ESPv2 obtêm tokens de acesso para si através do Google Cloud serviço de metadados.

Quando implementa o ESP ou o ESPv2 num ambiente que não seja oGoogle Cloud , como o seu computador local, um cluster Kubernetes no local ou outro fornecedor de nuvem, tem de fornecer um ficheiro JSON de conta de serviço que contenha uma chave privada. O ESP e o ESPv2 usam a conta de serviço para gerar chaves de acesso para chamar os serviços de que precisa para gerir a sua API.

Pode usar a Google Cloud consola ou a CLI Google Cloud para criar a conta de serviço e o ficheiro de chave privada:

Consola

  1. Na Google Cloud consola, abra a página Contas de serviço .

    Aceda à página Contas de serviço

  2. Clique em Selecionar um projeto.
  3. Selecione o projeto no qual 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, introduza o nome da conta de serviço.
  6. Clique em Criar.
  7. Clique em Continuar.
  8. Clique em Concluído.
  9. Clique no endereço de email da conta de serviço recém-criada.
  10. Clique em Chaves.
  11. Clique em Adicionar chave e, de seguida, em Criar nova chave.

  12. Clique em Criar. É transferido um ficheiro de chave JSON para o seu computador.

    Certifique-se de que armazena o ficheiro de chave em segurança, uma vez que pode ser usado para se autenticar como a sua conta de serviço. Pode mover e mudar o nome deste ficheiro como quiser.

  13. Clique em Fechar.

gcloud

  1. Introduza o seguinte para apresentar os IDs dos seus Google Cloud projetos:

    gcloud projects list

  2. Substitua PROJECT_ID no seguinte comando para definir o projeto predefinido para o projeto em que a sua API se encontra:

    gcloud config set project PROJECT_ID

  3. Certifique-se de que a CLI do Google Cloud (gcloud) está autorizada a aceder aos seus dados e serviços em Google Cloud:

    gcloud auth login

    Se tiver mais do que uma conta, certifique-se de que escolhe a conta que está no Google Cloud projeto em que a API se encontra. Se executar o comando gcloud auth list, a conta que selecionou é apresentada como a conta 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 nome a apresentar que quer usar:

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

    O comando atribui um endereço de email à conta de serviço no seguinte formato:

    SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

    Este endereço de email é necessário nos comandos subsequentes.

  5. Crie um ficheiro de chave de 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 as funções de IAM necessárias:

Esta secção descreve os recursos do IAM usados pelo ESP e pelo ESPv2, bem como as funções do IAM necessárias para que a conta de serviço anexada aceda a estes recursos.

Configuração do serviço de ponto final

O ESP e o ESPv2 chamam o controlo de serviços, que usa a configuração do serviço de endpoint. A configuração do serviço de ponto final é um recurso do IAM, e o ESP e o ESPv2 precisam da função Controlador de serviços para aceder a ele.

A função IAM está na configuração do serviço de ponto final e não no projeto. Um projeto pode ter várias configurações de serviços de pontos finais.

Use o seguinte comando gcloud para adicionar a função à conta de serviço anexada para a configuração do serviço de ponto final.

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

Onde
* SERVICE_NAME é o nome do serviço de ponto final
* 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 rastreio para um projeto. Este projeto é denominado projeto de rastreio. No ESP, o projeto de rastreio e o projeto que detém a configuração do serviço de ponto final são os mesmos. No ESPv2, o projeto de rastreio pode ser especificado através da flag --tracing_project_id e, por predefinição, é o projeto de implementação.

O ESP e o ESPv2 requerem a função Agente do Cloud Trace para ativar o Cloud Trace.

Use o seguinte comando gcloud para adicionar a função à 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

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

Consulte gcloud iam service-accounts para mais informações sobre os comandos.

Implementar o back-end da API

Até agora, implementou a configuração do serviço na gestão de serviços, mas ainda não implementou o código que publica o back-end da API. Esta secção explica como implementar contentores pré-criados para a API de exemplo e o ESPv2 no Kubernetes.

Fornecer o ESPv2 com as credenciais do serviço

O ESPv2, que é executado num contentor, precisa de acesso às credenciais armazenadas localmente no ficheiro service-account-creds.json. Para fornecer ao ESPv2 acesso às credenciais, crie um segredo do Kubernetes e monte o segredo do Kubernetes como um volume do Kubernetes.

Para criar o segredo do Kubernetes e montar o volume:

  1. Se usou a Google Cloud consola para criar a conta de serviço, mude o nome do ficheiro JSON para service-account-creds.json. Mova-o para o mesmo diretório onde se encontram os ficheiros api_descriptor.pb e api_config.yaml.

  2. Crie um segredo do Kubernetes com as credenciais da conta de serviço:

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

    Se a operação for bem-sucedida, é apresentada a seguinte mensagem: 

    secret "service-account-creds" created

O ficheiro de manifesto de implementação que usa para implementar a API e o ESPv2 no Kubernetes já contém o volume secreto, conforme mostrado nas duas secções seguintes do ficheiro:

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

Configurar o nome do serviço e iniciar o serviço

O ESPv2 precisa de saber o nome do seu serviço para encontrar a configuração que implementou anteriormente através do comando gcloud endpoints services deploy.

Para configurar o nome do serviço e iniciar o serviço:

  1. Guarde uma cópia do ficheiro de manifesto de implementação, grpc-bookstore.yaml>, no mesmo diretório que service-account-creds.json.

  2. Abra grpc-bookstore.yaml e substitua SERVICE_NAME pelo nome do seu serviço Endpoints. Este é o mesmo nome que configurou no campo name do ficheiro api_config.yaml.

    containers:
- name: esp
  image: gcr.io/endpoints-release/endpoints-runtime:2
  args: [
    "--listener_port=9000",
    "--service=SERVICE_NAME",
    "--rollout_strategy=managed",
    "--backend=grpc://127.0.0.1:8000",
    "--non_gcp",
    "--service_account_key=/etc/esp/creds/service-account-creds.json",
  ]

    A opção --rollout_strategy=managed configura o ESPv2 para usar a configuração do serviço implementada mais recente. Quando especifica esta opção, no prazo de um minuto após implementar uma nova configuração de serviço, o ESPv2 deteta a alteração e começa a usá-la automaticamente. Recomendamos que especifique esta opção em vez de fornecer um ID de configuração específico para o ESPv2 usar. Para mais detalhes sobre os argumentos do ESPv2, consulte as opções de arranque do ESPv2.

  3. Inicie o serviço para implementar o serviço no Kubernetes:

    kubectl create -f grpc-bookstore.yaml

    Se vir uma mensagem de erro semelhante à seguinte:

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

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

Obter o endereço IP externo do serviço

Precisa do endereço IP externo do serviço para enviar pedidos para a API de exemplo. Depois de iniciar o serviço no contentor, pode demorar alguns minutos até que o endereço IP externo esteja pronto.

  1. Ver o endereço IP externo:

    kubectl get service

  2. Tome nota do valor de EXTERNAL-IP e guarde-o numa variável de ambiente SERVER_IP, uma vez que é usado quando envia pedidos para a API de exemplo.

    export SERVER_IP=YOUR_EXTERNAL_IP

Enviar um pedido para a API

Para enviar pedidos para a API de exemplo, pode usar um cliente gRPC de exemplo escrito em Python.

  1. Clone o repositório Git onde o código do cliente gRPC está alojado:

    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 dependências: 

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

  4. Envie um pedido para a API de exemplo:

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

Se não receber uma resposta bem-sucedida, consulte o artigo Resolução de problemas de erros de resposta.

Acabou de implementar e testar uma API no Endpoints!

Limpar

Para evitar incorrer em custos na sua conta do Google Cloud pelos recursos usados neste tutorial, elimine o projeto que contém os recursos ou mantenha o projeto e elimine os recursos individuais.

  1. Elimine a API:

    gcloud endpoints services delete SERVICE_NAME

    Substitua SERVICE_NAME pelo nome da sua API.

  2. Elimine o cluster do GKE:

    gcloud container clusters delete NAME --zone ZONE

O que se segue?