Esta página foi traduzida pela API Cloud Translation.

Começar a usar os Endpoints para GKE com ESPv2

OpenAPI | gRPC

Este tutorial mostra como implementar um exemplo simples de serviço gRPC com o Extensible Service Proxy V2 (ESPv2) no Google Kubernetes Engine (GKE). Este 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.

Configure um Google Cloud projeto e transfira o software necessário. Consulte a secção Antes de começar.
Copie e configure ficheiros do exemplo bookstore-grpc. Consulte o artigo Configurar pontos finais.
Implemente a configuração do Endpoints para criar um serviço do Endpoints. Consulte o artigo Implementar a configuração dos Endpoints.
Crie um back-end para publicar a API e implemente a API. Consulte o artigo Implementar o back-end da API.
Obtenha o endereço IP externo do serviço. Consulte o artigo Determinar o endereço IP externo do serviço.
Envie um pedido para a API. Consulte o artigo Enviar uma solicitação para a API.
Evite incorrer em cobranças na sua conta Google Cloud . Consulte 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 gratuita.

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

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.

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

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.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Tome nota do Google Cloud ID do projeto, uma vez que é necessário mais tarde.
Instale e inicialize a CLI Google Cloud.
Atualize a CLI gcloud e instale os componentes do Endpoints.
```
gcloud components update
```
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
```
É aberto um novo separador do navegador e é-lhe pedido que escolha uma conta.
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 projeto.

Se tiver outros Google Cloud projetos e quiser usar gcloud para os gerir, consulte Gerir configurações da CLI gcloud.
Instalar kubectl:
```
gcloud components install kubectl
```
Adquirir novas credenciais de utilizador para usar como credenciais predefinidas da aplicação. As credenciais do utilizador são necessárias para autorizar kubectl.
```
gcloud auth application-default login
```
No novo separador do navegador apresentado, escolha uma conta.
Siga os passos no guia de início rápido do gRPC Python para instalar o gRPC e as ferramentas gRPC.

Configurar pontos finais

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

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.
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 gestão de serviços para criar um serviço gerido.

Make sure you are in the directory where the api_descriptor.pb and api_config.yaml files are located.
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
```
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.

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 ENDPOINTS_SERVICE_NAME possíveis é apresentada na coluna Nome do serviço.
Para a OpenAPI, o ENDPOINTS_SERVICE_NAME é o que especificou no campo host da sua especificação OpenAPI. Para o gRPC, o 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.

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.

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 criar um cluster do GKE para alojar o back-end da API e implementar a API.

Criar um cluster de contentores

O cluster precisa de um alias de IP para usar o balanceamento de carga nativa do contentor. Para criar um cluster de contentores com um alias de IP para o nosso exemplo:

gcloud container clusters create espv2-demo-cluster \
    --enable-ip-alias \
    --create-subnetwork="" \
    --network=default \
    --zone=us-central1-a

O comando acima cria um cluster, espv2-demo-cluster, com uma sub-rede aprovisionada automaticamente na zona us-central1-a.

A autenticar `kubectl` no cluster de contentores

Para usar kubectl para criar e gerir recursos de cluster, tem de obter credenciais de cluster e disponibilizá-las ao kubectl. Para tal, execute o seguinte comando, substituindo NAME pelo nome do novo cluster e ZONE pela respetiva zona do cluster.

gcloud container clusters get-credentials NAME --zone ZONE

A verificar as autorizações necessárias

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

Quando implementada no pod do GKE, a conta de serviço anexada é a conta de serviço do nó. Normalmente, é a conta de serviço predefinida do Compute Engine. Siga esta recomendação de autorização para escolher uma conta de serviço de nó adequada.

Se for usada a identidade da carga de trabalho, pode ser usada uma conta de serviço separada da conta de serviço do nó para comunicar com os serviços Google. Pode criar uma conta de serviço do Kubernetes para o pod executar o ESP e o ESPv2, criar uma conta de serviço Google e associar a conta de serviço do Kubernetes à conta de serviço Google.

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

Se a conta de serviço anexada for a conta de serviço predefinida do Compute Engine do projeto e a configuração do serviço de ponto final for implementada no mesmo projeto, a conta de serviço deve ter autorizações suficientes para aceder aos recursos de IAM. Pode ignorar o passo de configuração das funções de IAM. Caso contrário, devem ser adicionadas as seguintes funções do IAM à conta de serviço anexada.

Adicione as funções 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 é predefinido como 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?

Configurar as chaves e os certificados SSL

O equilíbrio de carga nativo do contentor usa o HTTP2 LB, que tem de ser encriptado com TLS. Isto exigiu a implementação de um certificado TLS no GKE Ingress e no ESPv2. Pode usar o seu próprio certificado ou um certificado autoassinado.

Crie um certificado e uma chave autoassinados através do openssl. Certifique-se de que introduziu o mesmo FQDN bookstore.endpoints.MY_PROJECT_ID.cloud.goog quando lhe foi pedido o "Nome comum(CN)". Este nome é usado pelos clientes para validar o certificado do servidor.
```
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
-keyout ./server.key -out ./server.crt
```
Crie um segredo do Kubernetes com a sua chave e certificado SSL. Tenha em atenção que o certificado é copiado para dois locais, server.crt e tls.crt, uma vez que o segredo é fornecido ao GKE Ingress e ao ESPv2. O GKE ingress procura o caminho do certificado tls.crt e o ESPv2 procura o caminho do certificado server.crt.
```
kubectl create secret generic esp-ssl \
--from-file=server.crt=./server.crt --from-file=server.key=./server.key \
--from-file=tls.crt=./server.crt --from-file=tls.key=./server.key
```

Implementar a API de exemplo e o ESPv2 no cluster

Nota: para frotas de pontos finais singulares/mais pequenas, use --rollout_strategy=managed com SERVICE_NAME. Para grandes frotas de pontos finais, monte a configuração do serviço, conforme mostrado na secção seguinte.

Para implementar o serviço gRPC de exemplo no cluster para que os clientes o possam usar:

git clone este repositório e abra-o para editar o ficheiro de manifesto de implementação grpc-bookstore.yaml.

Substitua SERVICE_NAME pelo nome do seu serviço de endpoints para entrada e contentor ESPv2. Este é o mesmo nome que configurou no campo name do ficheiro api_config.yaml.

# Copyright 2016 Google Inc.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License

# Use this file to deploy the container for the grpc-bookstore sample
# and the container for the Extensible Service Proxy (ESP) to
# Google Kubernetes Engine (GKE).

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: esp-grpc-bookstore
  annotations:
    kubernetes.io/ingress.class: "gce"
    kubernetes.io/ingress.allow-http: "false"
spec:
  tls:
  - hosts:
    - SERVICE_NAME
    secretName: esp-ssl
  backend:
    serviceName: esp-grpc-bookstore
    servicePort: 443
---
apiVersion: cloud.google.com/v1
kind: BackendConfig
metadata:
  name: esp-grpc-bookstore
spec:
  healthCheck:
    type: HTTP2
    requestPath: /healthz
    port: 9000
---
apiVersion: v1
kind: Service
metadata:
  name: esp-grpc-bookstore
  annotations:
    service.alpha.kubernetes.io/app-protocols: '{"esp-grpc-bookstore":"HTTP2"}'
    cloud.google.com/neg: '{"ingress": true, "exposed_ports": {"443":{}}}'
    cloud.google.com/backend-config: '{"default": "esp-grpc-bookstore"}'
spec:
  ports:
  # Port that accepts gRPC and JSON/HTTP2 requests over TLS.
  - port: 443
    targetPort: 9000
    protocol: TCP
    name: esp-grpc-bookstore
  selector:
    app: esp-grpc-bookstore
  type: ClusterIP
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: esp-grpc-bookstore
spec:
  replicas: 1
  selector:
    matchLabels:
      app: esp-grpc-bookstore
  template:
    metadata:
      labels:
        app: esp-grpc-bookstore
    spec:
      volumes:
      - name: esp-ssl
        secret:
          secretName: esp-ssl
      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",
          "--healthz=/healthz",
          "--ssl_server_cert_path=/etc/esp/ssl",
        ]
        ports:
          - containerPort: 9000
        volumeMounts:
        - mountPath: /etc/esp/ssl
          name:  esp-ssl
          readOnly: true
      - name: bookstore
        image: gcr.io/endpointsv2/python-grpc-bookstore-server:1
        ports:
          - containerPort: 8000

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.

Por exemplo:

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

Implementar configurações de serviços nos Endpoints

Se executar uma grande frota de Endpoints (mais de 100) no mesmo projeto do Google Cloud, recomendamos que monte a configuração do serviço para o contentor em vez de usar a flag --rollout_strategy=managed para extrair a configuração do serviço da API Service Management.

A API Service Management tem uma quota predefinida. Se uma grande frota de proxies ESPv2 usar --rollout_strategy=managed, todos vão sondar a configuração de serviço mais recente. A frota pode exceder a quota e, assim, causar falhas na atualização da configuração do serviço.

Siga os passos abaixo para montar a configuração do serviço:

Transfira a configuração JSON do serviço.

curl -o "/tmp/service_config.json" -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://servicemanagement.googleapis.com/v1/services/SERVICE/configs/CONFIG_ID?view=FULL"

Crie um recurso de mapa de configuração do Kubernetes a partir da configuração JSON.

kubectl create configmap service-config-configmap \
  --from-file=service_config.json:/tmp/service_config.json

Monte o recurso do mapa de configuração no contentor e use a flag --service_config_path para especificar o caminho do ficheiro de configuração.

Por exemplo:

  containers:
  - args:
    - --listener_port=8081
    - --backend=http://127.0.0.1:8080
    - --service_json_path=/etc/espv2_config/service_config.json
    - --healthz=/healthz
    image: gcr.io/endpoints-release/endpoints-runtime:2
    name: esp
    ports:
    - containerPort: 8081
      protocol: TCP
    volumeMounts:
    - mountPath: /etc/espv2_config
      name: service-config-volume
  volumes:
  - configMap:
      defaultMode: 420
      name: service-config-configmap
    name: service-config-volume

Inicie o serviço:
```
kubectl create -f grpc-bookstore.yaml
```

Se receber uma mensagem de erro, consulte o artigo Resolução de problemas de pontos finais no GKE.

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.

Ver o endereço IP externo:
```
kubectl get ingress
```
Tome nota do valor de EXTERNAL-IP e guarde-o numa variável de ambiente SERVER_IP. O endereço IP externo é usado para enviar pedidos para a API de exemplo.
```
export SERVER_IP=YOUR_EXTERNAL_IP
```

Enviar um pedido para a API

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

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

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

Change your working directory:

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

Install dependencies:

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

Create a root CA for the self-signed certificate

openssl x509 -in server.crt -out client.pem -outform PEM

Send a request to the sample API:
```
python bookstore_client.py --host SERVER_IP --port 443 \
--servername bookstore.endpoints.MY_PROJECT_ID.cloud.goog --use_tls true --ca_path=client.pem
```
- 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 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.

Elimine a API:
```
gcloud endpoints services delete SERVICE_NAME
```
Substitua SERVICE_NAME pelo nome da sua API.

Elimine o cluster do GKE:

gcloud container clusters delete NAME --zone ZONE

O que se segue?

Saiba como configurar a sua própria API gRPC para o Cloud Endpoints.
Analise o exemplo da livraria no GitHub mais detalhadamente. O cliente e o servidor estão disponíveis em Python e Java.
A amostra getting-started-grpc está disponível no GitHub nos seguintes idiomas:
- Java
- Python
- Ruby
- Go
- Node.js

Começar a usar os Endpoints para GKE com ESPv2 Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Objetivos

Custos

Antes de começar

Configurar pontos finais

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

A verificar os serviços necessários

Implementar o back-end da API

Criar um cluster de contentores

A autenticar kubectl no cluster de contentores

A verificar as autorizações necessárias

Adicione as funções IAM necessárias:

Configuração do serviço de ponto final

Cloud Trace

Configurar as chaves e os certificados SSL

Implementar a API de exemplo e o ESPv2 no cluster

Implementar configurações de serviços nos Endpoints

Obter o endereço IP externo do serviço

Enviar um pedido para a API

Limpar

O que se segue?

Começar a usar os Endpoints para GKE com ESPv2

A autenticar `kubectl` no cluster de contentores