Primeiros passos com o Cloud Endpoints para Kubernetes com ESPv2

OpenAPI   |  gRPC

Neste tutorial, você aprende a configurar e implantar uma API de amostra e o Extensible Service Proxy V2 (ESPv2) em um cluster do Kubernetes que não está no Google Cloud. Se quiser usar o Google Kubernetes Engine (GKE), consulte Primeiros passos com o Endpoints no GKE.

A API de exemplo é descrita com a especificação OpenAPI. O tutorial também mostra como criar uma chave de API para enviar solicitações à API.

Neste tutorial, são usadas imagens de contêiner predefinidas do exemplo de código e do ESPv2, que são armazenadas no Artifact Registry. Se você não está familiarizado com os contêineres, consulte as páginas a seguir para saber mais:

• Como implantar um aplicativo da Web em contêiner.
• Imagens de contêiner do Kubernetes.

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. Configurar um projeto do Google Cloud . Consulte Antes de começar.
2. Instale e configure o software usado no tutorial. Consulte Como instalar e configurar o software necessário.
3. Opcionalmente, faça o download do exemplo de código. Consulte Como conseguir o exemplo de código.
4. Faça o download do arquivo de configuração do Kubernetes. Consulte Como conseguir o arquivo de configuração do Kubernetes.
5. Configure o arquivo openapi.yaml, usado para configurar o Endpoints. Consulte Como configurar o Endpoints.
6. Implante a configuração do Endpoints para criar um serviço do Cloud Endpoints. Consulte Como implantar a configuração do Endpoints.
7. Crie credenciais para o serviço do Endpoints. Consulte Como criar credenciais para o serviço.
8. Implante a API e o ESPv2 no cluster. Consulte Como implantar o back-end da API.
9. Consiga o endereço IP externo do serviço. Consulte Como conseguir o endereço IP externo.
10. Envie uma solicitação à API usando um endereço IP. Consulte Como enviar uma solicitação usando um endereço IP.
11. 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 do domínio. Consulte Como enviar uma solicitação usando o FQDN.

Limpar

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

Custos

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

• 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 um teste sem custo financeiro.

Ao concluir as tarefas descritas neste documento, é possível evitar o faturamento contínuo excluindo os recursos criados. Para mais informações, consulte Limpeza.

Antes de começar

Antes de começar

Para acompanhar este tutorial, é preciso ter uma configuração de cluster do Kubernetes ou Minikube. Para saber mais, consulte a Documentação do Kubernetes.

1. 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.
   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

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

3. Anote o ID do projeto Google Cloud , porque ele será necessário mais tarde.

Como instalar e configurar o software necessário

Neste tutorial, você vai instalar a Google Cloud CLI para usar a CLI gcloud no gerenciamento do projeto. Você usará a interface de linha de comando kubectl (em inglês) para executar comandos em clusters do Kubernetes. Também será preciso uma maneira de testar a 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 em Google Cloud:

   gcloud auth login

   Na nova guia aberta, 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 gerenciar as configurações da CLI gcloud.

6. Instale kubectl:

   gcloud components install kubectl

7. Consiga novas credenciais de usuário que serão usadas nas credenciais padrão do aplicativo. As credenciais de usuário autorizam a kubectl.

   gcloud auth application-default login

8. Na nova guia que é aberta, escolha uma conta.
9. Execute o comando a seguir para garantir que o cliente do Kubernetes esteja configurado corretamente:

   kubectl version

   O resultado será semelhante a:

      Client Version: version.Info{Major:"1", Minor:"8", GitVersion:"v1.8.4",
        GitCommit:"9befc2b8928a9426501d3bf62f72849d5cbcd5a3", GitTreeState:"clean",
        BuildDate:"2017-11-20T05:28:34Z", GoVersion:"go1.8.3", Compiler:"gc",
        Platform:"linux/amd64"}
      Server Version: version.Info{Major:"1", Minor:"7+",
        GitVersion:"v1.7.8-gke.0",
        GitCommit:"a7061d4b09b53ab4099e3b5ca3e80fb172e1b018", GitTreeState:"clean",
        BuildDate:"2017-10-10T18:48:45Z", GoVersion:"go1.8.3", Compiler:"gc",
        Platform:"linux/amd64"}
      

Como fazer o download do código de amostra

Opcionalmente, faça o download do exemplo de código. Neste tutorial, será implantada uma imagem do contêiner pré-construída, portanto você não precisa criar um contêiner a partir do exemplo de código. No entanto, faça o download do exemplo de código que é fornecido em várias linguagens para ajudar você a entender como funciona a API de amostra.

Para fazer o download do exemplo de código:

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 app 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 exemplo de código:

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

Como conseguir o arquivo de configuração do Kubernetes

1. Clone o repositório GitHub que contém os arquivos yaml usados neste tutorial em sua máquina local:

    git clone https://github.com/googlecloudplatform/endpoints-samples

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

2. Altere para o diretório que contém os arquivos de configuração:

    cd endpoints-samples/kubernetes

Como configurar o Endpoints

É necessário ter um documento OpenAPI baseado em OpenAPI 2.0 ou OpenAPI 3.x que descreva a superfície dos seus apps e quaisquer requisitos de autenticação. Para saber mais, consulte Versões compatíveis da OpenAPI.

Também é preciso adicionar um campo específico do Google que contenha o URL de cada app para que o ESPv2 tenha as informações necessárias para invocar um app. Se você é novo na OpenAPI, consulte a visão geral da OpenAPI para mais informações.

Para configurar o Endpoints:

1. Crie um arquivo de texto chamado openapi.yaml. Por conveniência, esta página se refere ao documento da OpenAPI por esse nome, mas é possível usar outro nome se você preferir.
2. Copie o conteúdo de um dos seguintes arquivos no novo arquivo openapi.yaml. Você pode usar a OpenAPI 2.0 ou a OpenAPI 3.x.

   OpenAPI 2.0

   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"
   
   consumes:
     - "application/json"
   produces:
     - "application/json"
   
   schemes:
   # Uncomment the next line if you configure SSL for this API.
   # - "https"
     - "http"
   
   paths:
     /echo:
       post:
         description: "Echo back a given message."
         operationId: "echo"
         produces:
           - "application/json"
         responses:
           200:
             description: "Echo"
             schema:
               $ref: "#/definitions/echoMessage"
         parameters:
           -
             description: "Message to echo"
             in: body
             name: message
             required: true
             schema:
               $ref: "#/definitions/echoMessage"
         security:
           - api_key: []
     /auth/info/googlejwt:
       get:
         description: "Returns the requests' authentication information."
         operationId: "auth_info_google_jwt"
         produces:
           - "application/json"
         responses:
           200:
             description: "Authenication info."
             schema:
               $ref: "#/definitions/authInfoResponse"
         security:
           - api_key: []
             google_jwt: []
     /auth/info/googleidtoken:
       get:
         description: "Returns the requests' authentication information."
         operationId: "authInfoGoogleIdToken"
         produces:
           - "application/json"
         responses:
           200:
             description: "Authentication info."
             schema:
               $ref: "#/definitions/authInfoResponse"
         security:
           - api_key: []
             google_id_token: []
   
   definitions:
     echoMessage:
       type: "object"
       properties:
         message:
           type: "string"
     authInfoResponse:
       properties:
         id:
           type: "string"
         email:
           type: "string"
   
   securityDefinitions:
     # This section configures basic authentication with an API key.
     api_key:
       type: "apiKey"
       name: "key"
       in: "query"
   
     # This section configures authentication using Google API Service Accounts
     # to sign a json web token. This is mostly used for server-to-server
     # communication.
     google_jwt:
       authorizationUrl: ""
       flow: "implicit"
       type: "oauth2"
       # This must match the 'iss' field in the JWT.
       x-google-issuer: "jwt-client.endpoints.sample.google.com"
       # Update this with your service account's email address.
       x-google-jwks_uri: "https://www.googleapis.com/service_accounts/v1/jwk/YOUR_SERVICE_ACCOUNT_EMAIL"
       # This must match the "aud" field in the JWT. You can add multiple
       # audiences to accept JWTs from multiple clients.
       x-google-audiences: "echo.endpoints.sample.google.com"
     # This section configures authentication using Google OAuth2 ID Tokens.
     # ID Tokens can be obtained using OAuth2 clients, and can be used to access
     # your API on behalf of a particular user.
   
     google_id_token:
       authorizationUrl: ""
       flow: "implicit"
       type: "oauth2"
       x-google-issuer: "https://accounts.google.com"
       x-google-jwks_uri: "https://www.googleapis.com/oauth2/v3/certs"
       # Your OAuth2 client's Client ID must be added here. You can add
       # multiple client IDs to accept tokens from multiple clients.
       x-google-audiences: "YOUR_CLIENT_ID"

   OpenAPI 3.x

   openapi: 3.0.4
   info:
     description: "A simple Google Cloud Endpoints API example."
     title: "Endpoints Example"
     version: "1.0.0"
   servers:
     - url: "http://echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
       x-google-endpoint: {}
   
   paths:
     "/echo":
       post:
         description: "Echo back a given message."
         operationId: "echo"
         requestBody:
           description: "Message to echo"
           required: true
           content:
             "application/json":
               schema:
                 $ref: "#/components/schemas/echoMessage"
         responses:
           '200':
             description: "Echo"
             content:
               "application/json":
                 schema:
                   $ref: "#/components/schemas/echoMessage"
         security:
           - api_key: []
   
     "/auth/info/googlejwt":
       get:
         description: "Returns the requests' authentication information."
         operationId: "auth_info_google_jwt"
         responses:
           '200':
             description: "Authentication info."
             content:
               "application/json":
                 schema:
                   $ref: "#/components/schemas/authInfoResponse"
         security:
           - api_key: []
             google_jwt: []
   
     "/auth/info/googleidtoken":
       get:
         description: "Returns the requests' authentication information."
         operationId: "authInfoGoogleIdToken"
         responses:
           '200':
             description: "Authentication info."
             content:
               "application/json":
                 schema:
                   $ref: "#/components/schemas/authInfoResponse"
         security:
           - api_key: []
             google_id_token: []
   
   components:
     schemas:
       echoMessage:
         type: "object"
         properties:
           message:
             type: "string"
       authInfoResponse:
         properties:
           id:
             type: "string"
           email:
             type: "string"
   
     securitySchemes:
       api_key:
         type: "apiKey"
         name: "key"
         in: "query"
   
       google_jwt:
         type: "oauth2"
         flows:
           implicit:
             authorizationUrl: ""
             scopes: {}
         x-google-auth:
           issuer: "jwt-client.endpoints.sample.google.com"
           jwksUri: "https://www.googleapis.com/service_accounts/v1/jwk/YOUR_SERVICE_ACCOUNT_EMAIL"
           audiences: "echo.endpoints.sample.google.com"
   
       google_id_token:
         type: "oauth2"
         flows:
           implicit:
             authorizationUrl: ""
             scopes: {}
         x-google-auth:
           issuer: "https://accounts.google.com"
           jwksUri: "https://www.googleapis.com/oauth2/v3/certs"
           audiences:
             - "YOUR_CLIENT_ID"

Este tutorial usa uma extensão específica do Google para a especificação OpenAPI que permite configurar o nome do serviço. O método para especificar o nome do serviço depende da versão da especificação OpenAPI que você está usando.

OpenAPI 2.0

Use o campo host para especificar o nome do serviço:

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

Para configurar o Endpoints:

1. Abra o arquivo openapi.yaml.
2. No campo host, substitua YOUR_PROJECT_ID pelo ID do seu projeto Google Cloud .
3. Salve o arquivo openapi.yaml.

OpenAPI 3.x

Use o campo url no objeto servers para especificar o nome do serviço:

servers:
- url: https://echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog
    x-google-endpoint: {}

Para configurar o Endpoints:

1. Abra o arquivo openapi.yaml.
2. Se o arquivo openapi.yaml tiver um campo host, remova-o.
3. Adicione um objeto servers conforme mostrado.
4. No campo url, substitua YOUR_PROJECT_ID pelo ID do seu projeto Google Cloud .
5. Salve o arquivo openapi.yaml.

Depois de concluir todas as etapas de configuração a seguir para 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 nome de domínio totalmente qualificado (FQDN).

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 em que o arquivo de configuração openapi.yaml está localizado.
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 ou servers.url 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 ID 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 ID de configurações de 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ções de serviço. Você pode ver as configurações de serviço do Endpoints na página Endpoints > Serviços no Google Cloud console.

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

No mínimo, o Endpoints e o ESP exigem a ativação dos seguintes serviços do Google:

Nome	Título
servicemanagement.googleapis.com	API Service Management
servicecontrol.googleapis.com	API Service Control

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 doGoogle Cloud atual em que esses serviços foram explicitamente desativados.

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

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.

Como criar credenciais para o serviço

Para fornecer gerenciamento da API, o ESP e o ESPv2 exigem os serviços do Service Infrastructure. Para chamá-los, o ESP e o ESPv2 precisam usar tokens de acesso. Quando você implanta o ESP ou o ESPv2 em ambientes do Google Cloud , como o GKE, o Compute Engine ou o ambiente flexível da App Engine, o ESP e o ESPv2 recebem tokens de acesso por meio do serviço de metadados doGoogle Cloud .

Ao implantar o ESP ou o ESPv2 em um ambiente que não seja doGoogle Cloud , como seu computador local, um cluster do Kubernetes local ou outro provedor de nuvem, é preciso fornecer um arquivo JSON da 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 e chamar os serviços necessários para gerenciar a API.

Use o console Google Cloud ou a Google Cloud CLI para criar a conta de serviço e o arquivo de chave privada:

Console

1. No console do Google Cloud , abra a página Contas de serviço .

   Acessar a página Contas de serviço

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

12. Clique em Criar. O download de um arquivo de chave JSON é feito no seu computador.

    Armazene o arquivo de chave com segurança, porque ele pode ser usado para autenticação utilizando sua conta de serviço. Mova e renomeie esse arquivo como quiser.

13. Clique em Fechar.

gcloud

1. Para exibir os IDs dos seus projetos doGoogle Cloud , digite:

   gcloud projects list

2. Substitua PROJECT_ID no comando a seguir para definir o projeto que contém sua API como padrão:

   gcloud config set project PROJECT_ID

   Importante: é preciso criar a conta de serviço no mesmo projeto em que está a API.

3. Verifique se a Google Cloud CLI (gcloud) está autorizada a acessar seus dados e serviços em Google Cloud:

   gcloud auth login

   Se você tiver mais de uma conta, escolha a que está no projeto Google Cloud em que a API está localizada. Se você executar gcloud auth list, a conta selecionada será mostrada como a 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 pelo nome de exibição que você quer usar:

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

   O comando atribui um endereço de e-mail para a conta de serviço no seguinte formato:

   SERVICE_ACCOUNT_NAME@PROJECT_ID.

   Esse endereço de e-mail é necessário nos comandos subsequentes.

5. Crie um arquivo da chave da conta de serviço:

   gcloud iam service-accounts keys create ~/service-account-creds.json \
      --iam-account SERVICE_ACCOUNT_NAME@PROJECT_ID.

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 as configurações de serviço do endpoint. As configurações de 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á nas configurações de 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. \
  --role roles/servicemanagement.serviceController

Em que
* SERVICE_NAME é o nome do serviço do endpoint
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID. é 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 trace e o projeto que tem as configurações de 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. \
  --role roles/cloudtrace.agent

Em que
* TRACING_PROJECT_ID é o ID do projeto de rastreamento
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID. é a conta de serviço anexada. Para mais informações, consulte O que são funções e permissões?

Para mais informações sobre os comandos, consulte gcloud iam service-accounts.

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. Nesta seção, mostramos como implantar contêineres pré-criados da API de amostra e do ESPv2 no Kubernetes.

Como verificar as permissões necessárias

Conceder as permissões necessárias à conta de serviço associada ao cluster:

gcloud endpoints services add-iam-policy-binding SERVICE_NAME \
    --member "serviceAccount:SERVICE_ACCOUNT" \
    --role roles/servicemanagement.serviceController

Para mais informações, consulte O que são papéis e permissões?

Como fornecer as credenciais de serviço ao ESPv2

O ESPv2, que é executado dentro de um contêiner, precisa acessar as credenciais armazenadas localmente no arquivo service-account-creds.json. Para que o ESPv2 tenha acesso às credenciais, crie um secret do Kubernetes e ative-o como um volume do Kubernetes (links em inglês).

Para criar o secret do Kubernetes e ativar o volume:

1. Se o arquivo JSON tiver sido transferido por download para um diretório diferente, renomeie-o como service-account-creds.json e copie-o para endpoints-samples/kubernetes. Dessa forma, o nome corresponderá às opções especificadas no arquivo de manifesto de implantação echo.yaml.
2. Verifique se você está no diretório endpoints-samples/kubernetes.

3. Crie um secret do Kubernetes com as credenciais da conta de serviço usando o seguinte comando:

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

   Se o processo for bem-sucedido, a seguinte mensagem será exibida:

   secret "service-account-creds" created

O arquivo de manifesto de implantação usado para implantar a API e o ESPv2 no Kubernetes já contém o volume do secret, conforme mostrado nas duas seções do arquivo a seguir:

volumes:
  - name: service-account-creds
    secret:
      secretName: service-account-creds

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

Como configurar o nome do serviço e iniciar o serviço

O ESPv2 precisa saber o nome do serviço para encontrar a configuração implantada anteriormente usando o comando gcloud endpoints services deploy.

Para configurar o nome do serviço e iniciá-lo:

1. Abra o arquivo de manifesto de implantação echo.yaml e substitua SERVICE_NAME nas opções de inicialização do ESPv2 pelo nome do seu serviço. Ele é o mesmo que foi configurado no campo host ou server.url do documento da OpenAPI. Exemplo:

   "--service=echo-api.endpoints.example-project-12345.cloud.goog"

   containers:
   - name: esp
     image: gcr.io/endpoints-release/endpoints-runtime:2
     args: [
       "--listener_port=8080",
       "--backend=127.0.0.1:8081",
       "--service=SERVICE_NAME",
       "--rollout_strategy=managed",
       "--non_gcp",
       "--service_account_key=/etc/esp/creds/service-account-creds.json"
     ]
     ports:
       - containerPort: 8080
     volumeMounts:
       - mountPath: /etc/esp/creds
         name: service-account-creds
         readOnly: true
   - name: echo
     image: gcr.io/endpoints-release/echo:latest
     ports:
       - containerPort: 8081
   

   A opção "--rollout_strategy=managed" configura o ESPv2 para usar as configurações de serviço implantadas mais recentes. 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.

   Observação:se você estiver usando o MiniKube, será necessário mudar o campo type do serviço de LoadBalancer para NodePort no arquivo de configuração.
   Observação:recomendamos que você defina imagePullPolicy na especificação do contêiner 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.

2. Inicie o serviço para implantar o serviço do Endpoints no Kubernetes com o seguinte comando:

   kubectl create -f echo.yaml

   Se for exibida uma mensagem de erro parecida com esta:

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

   Isso indica que kubectl não está configurado corretamente. Para saber mais, consulte Configurar a kubectl (em inglês). Para mais informações, consulte Como implantar o Endpoints no Kubernetes.

Conseguir o endereço IP externo do serviço

Se estiver usando o Minikube, vá direto para Como enviar uma solicitação usando um endereço IP. Após o início do serviço no contêiner, pode levar alguns minutos para o endereço IP externo ficar pronto.

Para ver o endereço IP externo do serviço:

1. Execute o seguinte comando:

   kubectl get service

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

É possível enviar solicitações à API de exemplo depois que ela estiver em execução no cluster de contêiner.

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

O exemplo de código 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 Google Cloud usado para a API, crie uma chave de API na página de credenciais da API. Se você quiser 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 para minikube

Os comandos a seguir usam a variável de ambiente ENDPOINTS_KEY que você definiu anteriormente.

Linux ou mac OS

NODE_PORT=`kubectl get service esp-echo --output='jsonpath={.spec.ports[0].nodePort}'`
MINIKUBE_IP=`minikube ip`
curl --request POST \
    --header "content-type:application/json" \
    --data '{"message":"hello world"}' \
    ${MINIKUBE_IP}:${NODE_PORT}/echo?key=${ENDPOINTS_KEY}

PowerShell

$Env:NODE_PORT=$(kubectl get service esp-echo --output='jsonpath={.spec.ports[0].nodePort}')
$Env:MINIKUBE_IP=$(minikube ip)
(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} `
    -URI "http://$Env:MINIKUBE_IP:$Env:NODE_PORT/echo?key=$Env:ENDPOINTS_KEY").Content

Enviar a solicitação para outros clusters do Kubernetes

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 de terceiros, como o Postman, uma extensão do navegador Chrome, para enviar a solicitação:

• Selecione POST como o verbo HTTP.
• Para o cabeçalho, selecione a chave content-type e o valor application/json.
• Para o corpo, digite isto:
  {"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 até 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 Análise 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:

OpenAPI 2.0

1. Abra o arquivo de configuração da OpenAPI, openapi.yaml, e adicione a propriedade x-google-endpoints no nível superior do arquivo (não recuado ou aninhado), como 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
   

OpenAPI 3.x

1. Abra o arquivo de configuração da OpenAPI, openapi.yaml, e adicione a propriedade servers.url no nível superior do arquivo (não recuado ou aninhado), como mostrado no snippet a seguir:

   servers:
     - url: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
       x-google-endpoint:
         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 esteja configurado desta forma:

OpenAPI 2.0

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"

OpenAPI 3.x

servers:
  - url: "echo-api.endpoints.example-project-12345.cloud.goog"
    x-google-endpoint:
      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 ao 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

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.

Limpar

• Exclua o serviço e a implantação do Kubernetes:

  kubectl delete -f echo.yaml

Consulte Como excluir uma API e as instâncias relacionadas para mais informações sobre como interromper os serviços usados neste tutorial.

A seguir

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