Esta página foi traduzida pela API Cloud Translation.

Introdução aos Endpoints para Kubernetes com o ESPv2

OpenAPI | gRPC

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.

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

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.

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.

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.

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 nãoGoogle Cloud , como o seu computador local, um cluster do 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 tokens 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

Na Google Cloud consola, abra a página Contas de serviço .
Aceda à página Contas de serviço
Clique em Selecionar um projeto.
Selecione o projeto no qual a API foi criada e clique em Abrir.
Clique em + Criar conta de serviço.
No campo Nome da conta de serviço, introduza o nome da conta de serviço.
Clique em Criar.
Clique em Continuar.
Clique em Concluído.
Clique no endereço de email da conta de serviço recém-criada.
Clique em Chaves.
Clique em Adicionar chave e, de seguida, em Criar nova chave.
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 autenticar como a sua conta de serviço. Pode mover e mudar o nome deste ficheiro como quiser.
Clique em Fechar.

`gcloud`

Introduza o seguinte para apresentar os IDs dos seus Google Cloud projetos:
```
gcloud projects list
```
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
```
Importante: tem de criar a conta de serviço no mesmo projeto em que se encontra a sua API.
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.
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.

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

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 secret do Kubernetes e montar o volume:

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.

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:

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

Nota: se estiver a usar o MiniKube, tem de alterar o campo type do serviço de LoadBalancer para NodePort no ficheiro de configuração.
Nota: 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 ESPv2. Leia acerca das práticas recomendadas de configuração para ver mais detalhes. Quando é lançada uma nova versão do ESPv2, pode fazer um reinício contínuo de todos os pods para garantir que é usada a versão mais recente.
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 Configurar 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.

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

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!