Esta página foi traduzida pela API Cloud Translation.

Começar a usar os Endpoints para GKE com ESP

OpenAPI | gRPC

Este tutorial mostra como implementar um exemplo simples de um serviço gRPC com o Extensible Service Proxy (ESP) 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 ESP, 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.

Configurar pontos finais

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

Crie um ficheiro de descritor protobuf autónomo a partir do ficheiro .proto do seu serviço:
1. Guarde uma cópia de bookstore.proto do repositório de exemplo. Este ficheiro define a API do serviço Bookstore.
2. Crie o seguinte diretório: mkdir generated_pb2
3. Crie o ficheiro de descritor, api_descriptor.pb, usando o compilador de buffers de protocolo protoc. Execute o seguinte comando no diretório onde guardou 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
```
  No comando anterior, --proto_path está definido como o diretório de trabalho atual. No seu ambiente de compilação gRPC, se usar um diretório diferente para os ficheiros de entrada, altere --proto_path para que o compilador pesquise o diretório onde guardou bookstore.proto..proto
Crie um ficheiro YAML de configuração da API gRPC:
1. Guarde uma cópia do api_config.yamlficheiro. Este ficheiro define a configuração da API gRPC para o serviço Bookstore.
2. Substitua MY_PROJECT_ID no ficheiro api_config.yaml pelo ID do projeto. Google Cloud Por exemplo:
```
#
# Name of the service configuration.
#
name: bookstore.endpoints.example-project-12345.cloud.goog
```
  Tenha em atenção que o valor do campo apis.name neste ficheiro corresponde exatamente ao nome da API totalmente qualificado do ficheiro .proto. Caso contrário, a implementação não funciona. O serviço Bookstore está definido em bookstore.proto no pacote endpoints.examples.bookstore. O nome da API totalmente qualificado é endpoints.examples.bookstore.Bookstore, tal como aparece no ficheiro api_config.yaml.
```
apis:
  - name: endpoints.examples.bookstore.Bookstore
```

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

Implementar a 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.

Certifique-se de que está no diretório onde se encontram os ficheiros api_descriptor.pb e api_config.yaml.
Confirme que o projeto predefinido que a ferramenta de linha de comandos gcloud está a usar atualmente é o projeto Google Cloud no qual quer implementar a configuração do Endpoints. Valide o ID do projeto devolvido pelo seguinte comando para se certificar de que o serviço não é criado no projeto errado.
```
gcloud config list project
```
Se precisar de alterar o projeto predefinido, execute o seguinte comando:
```
gcloud config set project YOUR_PROJECT_ID
```
Implemente o ficheiro proto descriptor e o ficheiro de configuração através da CLI do Google Cloud:
```
gcloud endpoints services deploy api_descriptor.pb api_config.yaml
```
À medida que cria e configura o serviço, o Service Management envia informações para o terminal. Quando a implementação estiver concluída, é apresentada uma mensagem semelhante à seguinte:
```
Service Configuration [CONFIG_ID] uploaded for service [bookstore.endpoints.example-project.cloud.goog]
```
CONFIG_ID é o ID exclusivo da configuração do serviço Endpoints criado pela implementação. Por 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 ID de configuração do serviço consiste numa indicação de data/hora seguida de um número de revisão. Se implementar novamente a configuração dos Endpoints no mesmo dia, o número de revisão é incrementado no ID de configuração do serviço.

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 pontos finais.

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

Para criar um cluster de contentores para o nosso exemplo:

Na Google Cloud consola, aceda à página Clusters do Kubernetes.

Aceda à página de clusters do Kubernetes
Clique em Criar cluster.
Aceite as predefinições e clique em Criar. Tome nota do nome e da zona do cluster, uma vez que são necessários mais tarde neste tutorial.

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 de 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. Por isso, 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 Service Control, 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 Service Controller 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?

Implementar a API de exemplo e o ESP no cluster

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

Guarde e abra para edição uma cópia do ficheiro de manifesto de implementação grpc-bookstore.yaml.
Substitua SERVICE_NAME pelo nome do seu serviço Endpoints. Este é o mesmo nome que configurou no campo name do ficheiro 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 a configuração do serviço implementada mais recente. Quando especifica esta opção, até 5 minutos após implementar uma nova configuração de serviço, o ESP deteta a alteração e começa a usá-la automaticamente. Recomendamos que especifique esta opção em vez de um ID de configuração específico para o ESP usar. Para mais detalhes sobre os argumentos do ESP, consulte as opções de arranque do ESP.

Por 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 defina o imagePullPolicy na especificação do contentor acima para Always. Isto permite que os pods recém-criados extraiam sempre a versão mais recente do ESP. Leia acerca das práticas recomendadas de configuração para ver mais detalhes. Quando é lançada uma nova versão do ESP, pode fazer um reinício contínuo de todos os pods para garantir que é usada a versão mais recente.
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 service
```
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

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

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

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

Altere o diretório de trabalho:

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

Instalar dependências:

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

Envie um pedido para a API de exemplo:
```
python bookstore_client.py --host SERVER_IP --port 80
```
- Consulte os gráficos de atividade da sua API na página Endpoints > Serviços.
  
  Aceda à página Serviços de pontos finais
  
  Pode demorar alguns momentos até que o pedido se reflita nos gráficos.
- Consulte os registos de pedidos da sua API na página do Explorador de registos.
  
  Aceda à página do Explorador de registos

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!