Primeiros passos com o Cloud Endpoints para GKE com ESPv2

---

OpenAPI | gRPC

Este tutorial mostra como configurar e implantar uma API de amostra e o Extensible Service Proxy V2 (ESPv2) a um cluster do Google Kubernetes Engine (GKE).

A API REST do código de amostra é descrita com a especificação OpenAPI. Além disso, você também aprende a criar uma chave de API e usá-la ao enviar solicitações para a API.

Neste tutorial, são usadas imagens de contêiner predefinidas do código de amostra e do ESPv2, que são armazenadas no Container Registry.

Para uma visão geral do Cloud Endpoints, consulte Sobre o Endpoints e Arquitetura do Endpoints.

Objetivos

Ao seguir o tutorial, use a lista geral de tarefas abaixo. Para enviar solicitações à API, é necessário concluir todas as tarefas da Parte 1.

Parte 1

1. Configure um projeto do Google Cloud. Consulte Antes de começar.
2. Crie um cluster de contêiner no GKE. Consulte Como criar um cluster de contêiner.
3. Instale e configure o software usado no tutorial. Consulte Como instalar e configurar o software necessário.
4. Faça o download do código de exemplo. Consulte Como conseguir o código de amostra.
5. Configure o arquivo openapi.yaml, que é usado para configurar o Cloud Endpoints. Consulte Como configurar o Endpoints.
6. Implante a configuração do Endpoints para criar um serviço do Endpoints. Consulte Como implantar a configuração do Endpoints.
7. Implante a API e o ESPv2 no cluster. Consulte Como implantar o back-end da API.
8. Consiga o endereço IP do cluster. Consulte Como conseguir o endereço IP externo do cluster.
9. Envie uma solicitação para a API usando um endereço IP. Consulte Como enviar uma solicitação usando um endereço IP.
10. Rastreie a atividade da API. Consulte Como rastrear a atividade da API.

Parte 2

1. Configurar um registro DNS para a API. Consulte Como configurar o DNS para o Endpoints.
2. Envie uma solicitação à API usando o nome de domínio totalmente qualificado. Consulte Como enviar uma solicitação usando o FQDN.

Limpar

Quando terminar, consulte Limpeza para evitar cobranças recorrentes na conta do Google Cloud.

Custos

Neste documento, você usará os seguintes componentes faturáveis do Google Cloud:

• GKE
• Endpoints

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

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.

   Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

   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.

   Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

   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, porque ele será necessário mais tarde.

Criar um cluster de contêiner

Você precisa criar um cluster de contêiner no GKE para que o código de backend da API de amostra seja executado. O cluster precisa de um alias de IP para usar o balanceamento de carga nativo de contêiner. Para criar um cluster de contêiner para a API de amostra usando um alias de API:

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

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

Anote o nome e a zona do cluster. Essas informações serão necessárias para autenticar o kubectl no cluster de contêiner.

Como instalar e configurar o software necessário

Neste tutorial, você instalará a CLI gcloud para usar a Google Cloud CLI e gerenciar seu projeto. Use kubectl para executar comandos em clusters do GKE. Também precisará testar sua API.

No procedimento a seguir, se você já tem o software necessário instalado, siga para a próxima etapa.

Siga estas etapas para instalar e configurar o software necessário:

1. Você precisará que um aplicativo envie solicitações à API de amostra.

   • Usuários de Linux e macOS: este tutorial fornece um exemplo de uso de curl, que normalmente vem pré-instalado em seu sistema operacional. Caso não tenha curl, faça o download na página Versões e downloads (em inglês) do curl.
   • Usuários do Windows: neste tutorial, há um exemplo que usa Invoke-WebRequest (em inglês), que é compatível com o PowerShell 3.0 e versões posteriores.
2. Instale e inicialize a CLI gcloud.
3. Atualize a CLI gcloud e instale os componentes do Endpoints:

   gcloud components update

4. 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 no navegador, selecione uma conta.
5. Defina o projeto padrão como o ID do projeto:

   gcloud config set project YOUR_PROJECT_ID

   Substitua YOUR_PROJECT_ID pela ID do seu projeto. Se você tiver outros projetos do Google Cloud e quiser usar gcloud para gerenciá-los, consulte Como CLI gcloud gcloud.

6. Instale kubectl:

   gcloud components install kubectl

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

   gcloud auth application-default login

   Na nova guia aberta no navegador, selecione uma conta.

Como fazer o download do código de amostra

Para ajudá-lo agilizar a entrada em operação, o código de exemplo é fornecido em vários idiomas. Veja como fazer o download do código de amostra para a máquina local em:

Java

Para clonar ou fazer o download da API de amostra:

1. Clone o repositório do aplicativo de amostra na máquina local:

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

   Como alternativa, faça o download da amostra (em inglês) como um arquivo zip e o descompacte.

2. Acesse o diretório que contém o exemplo de código:

   cd java-docs-samples/endpoints/getting-started

Python

Para clonar ou fazer o download da API de amostra:

1. Clone o repositório do aplicativo de amostra na máquina local:

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

   Como alternativa, faça o download da amostra (em inglês) como um arquivo zip e o descompacte.

2. Acesse o diretório que contém o exemplo de código:

   cd python-docs-samples/endpoints/getting-started

Go

Para clonar ou fazer o download da API de amostra:

1. Verifique se a variável de ambiente GOPATH (em inglês) está configurada.
2. Clone o repositório do aplicativo de amostra na máquina local:

   go get -d github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started

3. Acesse o diretório que contém o exemplo de código:

   cd $GOPATH/src/github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started

PHP

Para clonar ou fazer o download da API de amostra:

1. Clone o repositório do aplicativo de amostra na máquina local:

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

   Como alternativa, faça o download da amostra (em inglês) como um arquivo zip e o descompacte.

2. Acesse o diretório que contém o exemplo de código:

   cd php-docs-samples/endpoints/getting-started

Ruby

Para clonar ou fazer o download da API de amostra:

1. Clone o repositório do aplicativo de amostra na máquina local:

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

   Como alternativa, faça o download da amostra (em inglês) como um arquivo zip e o descompacte.

2. Acesse o diretório que contém o exemplo de código:

   cd ruby-docs-samples/endpoints/getting-started

NodeJS

Para clonar ou fazer o download da API de amostra:

1. Clone o repositório do aplicativo de amostra na máquina local:

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

   Como alternativa, faça o download da amostra (em inglês) como um arquivo zip e o descompacte.

2. Acesse o diretório que contém o código de amostra:

   cd nodejs-docs-samples/endpoints/getting-started

Como configurar o Endpoints

O código de exemplo inclui o arquivo de configuração OpenAPI, openapi.yaml, que é baseado na especificação OpenAPI v2.0. Para configurar o Endpoints:

1. No diretório de código de amostra, abra o arquivo de configuração openapi.yaml.
   Java

   swagger: "2.0"
   info:
     description: "A simple Google Cloud Endpoints API example."
     title: "Endpoints Example"
     version: "1.0.0"
   host: "echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog"

   Python

   swagger: "2.0"
   info:
     description: "A simple Google Cloud Endpoints API example."
     title: "Endpoints Example"
     version: "1.0.0"
   host: "echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog"

   Go

   swagger: "2.0"
   info:
     description: "A simple Google Cloud Endpoints API example."
     title: "Endpoints Example"
     version: "1.0.0"
   host: "echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog"

   PHP

   swagger: "2.0"
   info:
     description: "A simple Google Cloud Endpoints API example."
     title: "Endpoints Example"
     version: "1.0.0"
   host: "echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog"

   Ruby

   swagger: "2.0"
   info:
     description: "A simple Google Cloud Endpoints API example."
     title: "Endpoints Example"
     version: "1.0.0"
   host: "echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog"

   NodeJS

   swagger: "2.0"
   info:
     description: "A simple Google Cloud Endpoints API example."
     title: "Endpoints Example"
     version: "1.0.0"
   host: "echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog"

   Observações:

   • A amostra de configuração exibe as linhas próximas ao campo host, que precisa ser modificado. Para implantar o arquivo openapi.yaml no Endpoints, é necessário o documento completo da OpenAPI.
   • O arquivo de exemplo openapi.yaml contém uma seção para configurar a autenticação que não é necessária para este tutorial. Não é necessário configurar as linhas com YOUR-SERVICE-ACCOUNT-EMAIL e YOUR-CLIENT-ID.
   • A OpenAPI é uma especificação agnóstica de linguagem. Por conveniência, o mesmo arquivo openapi.yaml está na amostra getting-started no repositório do GitHub de cada linguagem.

2. No campo host, substitua o texto pelo nome do serviço do Endpoints, que precisa estar no seguinte formato:

   host: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
   

   Substitua o YOUR_PROJECT_ID pelo ID do projeto do Google Cloud. Exemplo:

   host: "echo-api.endpoints.example-project-12345.cloud.goog"
   

Observe que echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog é o nome do serviço do Endpoints. e não o nome de domínio totalmente qualificado (FQDN, na sigla em inglês) usado para enviar solicitações à API.

Para mais informações sobre os campos no documento da OpenAPI exigido pelo Endpoints, consulte Como configurar o Endpoints.

Depois de concluir todas as etapas de configuração a seguir e enviar solicitações à API de amostra usando um endereço IP, consulte Como configurar o DNS do Endpoints para informações sobre como configurar echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog para ser o FQDN.

Como implantar a configuração do Endpoints

Para implantar a configuração do Endpoints, use o comando gcloud endpoints services deploy. Ele utiliza o Service Management para criar um serviço gerenciado.

Para implantar a configuração do Endpoints:

1. Verifique se você está no diretório endpoints/getting-started.
2. Faça upload da configuração e crie um serviço gerenciado:

   gcloud endpoints services deploy openapi.yaml
   

Em seguida, o comando gcloud chama a API Service Management para criar um serviço gerenciado com o nome especificado no campo host do arquivo openapi.yaml. O Service Management configura o serviço de acordo com as configurações no arquivo openapi.yaml. Ao fazer alterações em openapi.yaml, é necessário reimplantar o arquivo para atualizar o serviço do Endpoints.

Durante a criação e a configuração do serviço, a Service Management envia informações ao terminal. Ignore os avisos sobre os caminhos no arquivo openapi.yaml que não exigem uma chave de API. Quando a configuração do serviço é concluída, o Service Management mostra uma mensagem com o código de configuração e o nome do serviço:

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

No exemplo anterior, 2017-02-13r0 é o ID de configuração do serviço e echo-api.endpoints.example-project-12345.cloud.goog é o serviço do Endpoints. O código de configuração do serviço consiste em um carimbo de data e um número de revisão. Se você implantar o arquivo openapi.yaml novamente no mesmo dia, o número de revisão será incrementado no ID de configuração do serviço. É possível visualizar a configuração do serviço do Endpoints na página Endpoints > Serviços no console do Google Cloud.

Se você receber uma mensagem de erro, consulte Como solucionar problemas de implantação na configuração do Endpoints.

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.

Implantar o back-end da API

Até agora, você implantou o documento da OpenAPI no Service Management, mas não o código que exibe o back-end da API. Veja nesta seção como implantar contêineres predefinidos para a API de amostra e o ESPv2 no cluster.

Como verificar as permissões necessárias

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

Quando implantada no pod do GKE, a conta de serviço anexada é a conta de serviço do nó. Ela costuma ser a conta de serviço padrão do Compute Engine. Siga esta recomendação de permissão para escolher uma conta de serviço de nó adequada.

Se a Identidade da carga de trabalho for usada, uma conta de serviço separada diferente da conta de serviço do nó poderá ser usada para falar com os serviços do Google. É possível criar uma conta de serviço do Kubernetes para o pod executar o ESP e o ESPv2. Além disso, você pode criar uma conta de serviço do Google e associá-la à do Kubernetes.

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

Se a conta de serviço anexada for a conta de serviço padrão do Compute Engine do projeto e a configuração do serviço do endpoint for implantada no mesmo projeto, a conta de serviço já deve ter permissões suficientes para acessar os recursos do IAM, então a etapa a seguir pode ser pulada. Caso contrário, adicione os papéis do IAM à conta de serviço anexada.

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 papéis e permissões?

Implantar os contêineres no cluster

Os contêineres oferecem um mecanismo de empacotamento lógico em que é possível simplificar os aplicativos no ambiente em que são executados. Siga o procedimento a seguir para implantar a API de amostra e o ESPv2 no cluster. Para implantar os contêineres no cluster:

1. Receba as credenciais do cluster e disponibilize-as para kubectl:

       gcloud container clusters get-credentials NAME --zone ZONE
       

   Substitua NAME pelo nome do cluster e ZONE pela zona do cluster.
2. Implante um serviço do Kubernetes no cluster do GKE. O serviço Kubernetes implementa a API. git clone este repositório, cd getting-started/ para colocar na pasta e editar o arquivo de configuração do Kubernetes LANG-deployment.yaml e substituir SERVICE_NAME nas opções de inicialização do ESPv2 com o nome do seu serviço.
   Java

   - name: esp
     image: gcr.io/endpoints-release/endpoints-runtime:2
     args: [
       "--listener_port=8081",
       "--backend=127.0.0.1:8080",
       "--service=SERVICE_NAME",
       "--rollout_strategy=managed",
       "--healthz=/healthz",
     ]
     readinessProbe:
       httpGet:
         path: /healthz
         port: 8081

   Python

   - name: esp
     image: gcr.io/endpoints-release/endpoints-runtime:2
     args: [
       "--listener_port=8081",
       "--backend=http://127.0.0.1:8080",
       "--service=SERVICE_NAME",
       "--rollout_strategy=managed",
       "--healthz=/healthz",
     ]
     readinessProbe:
       httpGet:
         path: /healthz
         port: 8081

   Go

   - name: esp
     image: gcr.io/endpoints-release/endpoints-runtime:2
     args: [
       "--listener_port", "8081",
       "--backend", "127.0.0.1:8080",
       "--service", "SERVICE_NAME",
       "--rollout_strategy", "managed",
       "--healthz=/healthz",
     ]
     readinessProbe:
       httpGet:
         path: /healthz
         port: 8081

   PHP

   - name: esp
     image: gcr.io/endpoints-release/endpoints-runtime:2
     args: [
       "--listener_port", "8081",
       "--backend", "127.0.0.1:8080",
       "--service", "SERVICE_NAME",
       "--rollout_strategy", "managed",
       "--healthz=/healthz",
     ]

   Ruby

   - name: esp
     image: gcr.io/endpoints-release/endpoints-runtime:2
     args: [
       "--listener_port", "8081",
       "--backend", "127.0.0.1:8080",
       "--service", "SERVICE_NAME",
       "--rollout_strategy", "managed",
       "--healthz=/healthz",
     ]

   NodeJS

   - name: esp
     image: gcr.io/endpoints-release/endpoints-runtime:2
     args: [
       "--listener_port", "8081",
       "--backend", "127.0.0.1:8080",
       "--service", "SERVICE_NAME",
       "--rollout_strategy", "managed",
       "--healthz=/healthz",
     ]
     readinessProbe:
       httpGet:
         path: /healthz
         port: 8081

   Exemplo:

     args: [
       "--listener_port=8081",
       "--backend=http://127.0.0.1:8080",
       "--service=echo-api.endpoints.example-project-12345.cloud.goog ",
       "--rollout_strategy=managed",
     ]
   

   A opção --rollout_strategy=managed configura o ESPv2 para usar a implantação mais recente da configuração do serviço. Ao especificar essa opção, a alteração é detectada pelo ESPv2 em até um minuto após a implantação de uma nova configuração do serviço e começa a ser usada automaticamente. Recomendamos especificar essa opção em vez de fornecer um ID de configuração específico para o ESPv2. Para saber mais sobre as outras opções do ESPv2 usadas, consulte Opções de inicialização do ESPv2.

   Recomendamos que você defina imagePullPolicy na especificação do contêiner acima como Always. Isso permitirá que os pods recém-criados sempre extraiam a versão mais recente do ESPv2. Leia sobre as práticas recomendadas de configuração para mais detalhes. Quando uma nova versão do ESPv2 é lançada, é possível executar uma reinicialização contínua de todos os pods para garantir que a versão mais recente seja usada.

   Se você executar uma frota grande de endpoints no mesmo projeto do Google Cloud (mais de cem), recomendamos ativar a configuração do serviço do contêiner em vez de usar a sinalização --rollout_strategy=managed para extrair a configuração de serviço da API Service Management. A API Service Management tem uma cota padrão. Se um grupo grande de endpoints usar --rollout_strategy=managed, todos os endpoints pesquisarão a configuração do serviço mais recente. A frota pode exceder a cota e, portanto, causar falhas na atualização da configuração do serviço. Siga as etapas abaixo para ativar a configuração de serviço.

   • Faça o download da configuração de serviço em JSON.

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

   • Ative o recurso do mapa de configuração no contêiner e use a sinalização "--service_config_path" para especificar o caminho do arquivo de configuração.

   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
   

3. Inicie o serviço do Kubernetes usando o comando kubectl apply:
   Java

   kubectl apply -f java-deployment.yaml

   Python

   kubectl apply -f python-deployment.yaml

   Go

   kubectl apply -f golang-deployment.yaml

   PHP

   kubectl apply -f php-deployment.yaml

   Ruby

   kubectl apply -f ruby-deployment.yaml

   NodeJS

   kubectl apply -f nodejs-deployment.yaml

Se você receber uma mensagem de erro, consulte Como solucionar problemas do Endpoints no GKE. Para mais informações, consulte Como implantar o back-end da API.

Como buscar o endereço IP externo do cluster

Para enviar solicitações para a API, é preciso o IP externo do serviço. 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 ingress
2. Anote o valor de EXTERNAL-IP. Use esse endereço IP ao enviar uma solicitação à API de amostra.

Como enviar uma solicitação usando um endereço IP

Agora que o serviço está sendo executado no cluster de contêiner e você tem o endereço IP externo, é possível enviar solicitações para a API.

Criar uma chave de API e definir uma variável de ambiente

O código de amostra requer uma chave de API. Para simplificar a solicitação, defina uma variável de ambiente para a chave da API.

1. No mesmo projeto do Google Cloud usado para a API, crie uma chave de API na página de credenciais da API. Se você quer criar uma chave de API em um projeto diferente do Google Cloud, consulte Como ativar uma API no projeto do Google Cloud.

   Acessar a página Credenciais

2. Clique em Criar credenciais e, em seguida, selecione Chave de API.
3. Copie a chave para a área de transferência.
4. Clique em Fechar.
5. No computador local, cole a chave da API para atribuí-la a uma variável de ambiente:
   • No Linux ou no macOS: export ENDPOINTS_KEY=AIza...
   • No Windows PowerShell: $Env:ENDPOINTS_KEY="AIza..."

Enviar a solicitação

Linux ou mac OS

Utilize curl para enviar uma solicitação HTTP usando a variável de ambiente ENDPOINTS_KEY definida anteriormente. Substitua IP_ADDRESS pelo endereço IP externo da instância.

curl --request POST \
   --header "content-type:application/json" \
   --data '{"message":"hello world"}' \
   "http://IP_ADDRESS:80/echo?key=${ENDPOINTS_KEY}"

No curl anterior:

• A opção --data especifica os dados a serem enviados para a API.
• A opção --header especifica que os dados estão no formato JSON.

PowerShell

Utilize Invoke-WebRequest para enviar uma solicitação HTTP usando a variável de ambiente ENDPOINTS_KEY definida anteriormente. Substitua IP_ADDRESS pelo endereço IP externo da instância.

(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} `
    -URI "http://IP_ADDRESS:80/echo?key=$Env:ENDPOINTS_KEY").Content

No exemplo acima, as duas primeiras linhas terminam em um acento grave. Quando você colar o exemplo no PowerShell, verifique se não há espaço após os acentos graves. Para informações sobre as opções usadas na solicitação de exemplo, consulte Invoke-WebRequest (em inglês) na documentação da Microsoft.

Aplicativo de terceiros

É possível usar um aplicativo terceirizado para enviar a solicitação, como o Postman (em inglês), uma extensão do navegador Chrome:

• Selecione POST como o verbo HTTP.
• Para o cabeçalho, selecione a chave content-type e o valor application/json.
• Para o corpo, digite o seguinte:
  {"message":"hello world"}
• No URL, use a chave de API real em vez da variável de ambiente. Por exemplo:
  http://192.0.2.0:80/echo?key=AIza...

A mensagem enviada é retornada pela API com a seguinte resposta:

{
  "message": "hello world"
}

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.

Observação: se quiser nos contar do que você gostou neste tutorial, envie um feedback na parte inferior desta página. Isso é muito importante para a melhoria dos tutoriais.
Se ocorrer um erro, entre no grupo do Google google-cloud-endpoints e informe o que aconteceu. Nesse grupo, são enviadas respostas de outros usuários do Endpoints e de engenheiros do Google, que o monitoram.

Como rastrear a atividade da API

Para rastrear a atividade da API:

1. Veja os gráficos de atividade da API na página Endpoints > Serviços.
   

   Ir para a página Serviços do Endpoints

   
   Pode levar alguns instantes para a solicitação aparecer nos gráficos.
2. Verifique os registros de solicitações da API na página "Explorador de registros".
   

   Acessar a página Explorador de registros

Como configurar o DNS para o Endpoints

Como o nome do serviço do Endpoints para a API está no domínio .endpoints.YOUR_PROJECT_ID.cloud.goog, é possível usá-lo como o nome de domínio totalmente qualificado (FQDN, na sigla em inglês). Basta fazer uma pequena alteração na configuração do arquivo openapi.yaml. Dessa forma, é possível enviar solicitações para a API de amostra usando echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog em vez do endereço IP.

Para configurar o DNS para o Endpoints:

1. Abra o arquivo de configuração da OpenAPI, openapi.yaml, e adicione a propriedade x-google-endpoints no nível superior do arquivo (sem recuo ou aninhamento), conforme mostrado no snippet a seguir:

   host: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
   x-google-endpoints:
   - name: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
     target: "IP_ADDRESS"
   

2. Na propriedade name, substitua YOUR_PROJECT_ID pelo ID do projeto.
3. Na propriedade target, substitua IP_ADDRESS pelo endereço IP usado ao enviar uma solicitação para a API de amostra.
4. Implante o arquivo de configuração da OpenAPI atualizado na Service Management usando o seguinte comando:

   gcloud endpoints services deploy openapi.yaml
   

Por exemplo, suponha que o arquivo openapi.yaml tenha estas configurações:

host: "echo-api.endpoints.example-project-12345.cloud.goog"
x-google-endpoints:
- name: "echo-api.endpoints.example-project-12345.cloud.goog"
  target: "192.0.2.1"

Ao implantar o arquivo openapi.yaml usando o comando gcloud anterior, o Service Management cria um registro A DNS, echo-api.endpoints.my-project-id.cloud.goog, que é resolvido para o endereço IP de destino, 192.0.2.1. Pode levar alguns minutos para a nova configuração do DNS se propagar.

Como configurar a SSL

Para mais detalhes sobre como configurar o DNS e a SSL, consulte Como ativar a SSL para o Endpoints.

Como enviar uma solicitação usando o FQDN

Agora que você tem o registro DNS configurado para a API de amostra, envie uma solicitação usando o FQDN (substitua YOUR_PROJECT_ID pelo ID do projeto) e a variável de ambiente ENDPOINTS_KEY definida anteriormente:

• No Linux ou no mac OS:

  curl --request POST \
      --header "content-type:application/json" \
      --data '{"message":"hello world"}' \
      "http://echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog:80/echo?key=${ENDPOINTS_KEY}"

• No Windows PowerShell:

  (Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' -Headers @{"content-type"="application/json"} -URI "http://echo-api.endpoints.[YOUR_PROJECT_ID].cloud.goog:80/echo?key=$Env:ENDPOINTS_KEY").Content

Como criar um portal do desenvolvedor para a API

É possível usar o portal do Cloud Endpoints para criar um portal do desenvolvedor, um site para interagir com a API de exemplo. Para saber mais, consulte a Visão geral do Portal do Cloud 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.

Consulte Como excluir uma API e as instâncias relacionadas para saber como interromper os serviços usados neste tutorial.

A seguir

• Saiba como criar uma imagem do Docker.
• Aprenda a implantar Endpoints no Kubernetes.
• Compartilhe a API com outro desenvolvedor.
• Saiba mais sobre a autenticação.
• Saiba mais sobre as opções de suporte da comunidade.
• Resolução de problemas na implantação do GKE.