Começar a usar o Cloud Endpoints para Kubernetes com o ESPv2

OpenAPI   |  gRPC

Este tutorial mostra como configurar e implementar uma API de exemplo e o proxy de serviço extensível V2 (ESPv2) num cluster do Kubernetes que não esteja no Google Cloud. Se quiser usar o Google Kubernetes Engine (GKE), consulte o artigo Introdução aos Endpoints no GKE.

A API de exemplo é descrita através da especificação OpenAPI. O tutorial também mostra como criar uma chave da API para enviar pedidos para a API.

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:

• Implementar uma aplicação Web contentorizada.
• Imagens de contentores do Kubernetes.

Para uma vista geral do Cloud Endpoints, consulte os artigos Acerca dos Endpoints e Arquitetura dos Endpoints.

Objetivos

Use a seguinte lista de tarefas de alto nível à medida que avança no tutorial. Todas as tarefas na Parte 1 são necessárias para enviar pedidos com êxito para a API.

Parte 1

1. Configure um Google Cloud projeto. Consulte a secção Antes de começar.
2. Instale e configure o software usado no tutorial. Consulte o artigo Instalar e configurar o software necessário.
3. Opcionalmente, transfira o exemplo de código. Consulte o artigo Obter o código de exemplo.
4. Transfira o ficheiro de configuração do Kubernetes. Consulte o artigo Obter o ficheiro de configuração do Kubernetes.
5. Configure o ficheiro openapi.yaml, que é usado para configurar os pontos finais. Consulte o artigo Configurar pontos finais.
6. Implemente a configuração do Endpoints para criar um serviço do Cloud Endpoints. Consulte o artigo Implementar a configuração dos Endpoints.
7. Crie credenciais para o seu serviço Endpoints. Consulte o artigo Criar credenciais para o seu serviço.
8. Implemente a API e o ESPv2 no cluster. Consulte o artigo Implementar o back-end da API.
9. Obtenha o endereço IP externo do serviço. Consulte o artigo Determinar o endereço IP externo.
10. Envie um pedido para a API através de um endereço IP. Consulte Enviar um pedido através de um endereço IP.
11. Acompanhe a atividade da API. Consulte o artigo Acompanhamento da atividade da API.

Parte 2

1. Configure um registo de DNS para a API de exemplo. Consulte o artigo Configurar o DNS para pontos finais.
2. Envie um pedido para a API através do nome do domínio. Consulte Enviar uma solicitação através do FQDN.

Limpeza

Quando terminar, consulte o artigo Limpar para evitar incorrer em custos na sua Google Cloud conta.

Custos

Neste documento, usa os seguintes componentes faturáveis do Google Cloud:

• Endpoints

Para gerar uma estimativa de custos com base na sua utilização prevista, use a calculadora de preços.

Os novos Google Cloud utilizadores podem ser elegíveis para uma avaliação gratuita.

Quando terminar as tarefas descritas neste documento, pode evitar a faturação contínua eliminando os recursos que criou. Para mais informações, consulte o artigo Limpe.

Antes de começar

Antes de começar

Este tutorial pressupõe que já tem o Minikube ou um cluster do Kubernetes configurado. Para mais informações, consulte a documentação do Kubernetes.

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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

Verify that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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

Verify that billing is enabled for your Google Cloud project.

1. Tome nota do Google Cloud ID do projeto, uma vez que é necessário mais tarde.

Instalar e configurar o software necessário

Neste tutorial, instala a CLI do Google Cloud para usar a CLI gcloud para gerir o seu projeto. Usa kubectl, uma interface de linhas de comando, para executar comandos em clusters do Kubernetes. Também precisa de uma forma de testar a API.

No procedimento seguinte, se já tiver o software necessário instalado, avance para o passo seguinte.

Para instalar e configurar o software necessário:

1. Precisa de uma aplicação para enviar pedidos para a API de exemplo.

   • Utilizadores do Linux e macOS: este tutorial oferece um exemplo de utilização do curl, que normalmente vem pré-instalado no seu sistema operativo. Se não tiver o curl, pode transferi-lo na curl página de lançamentos e transferências.
   • Utilizadores do Windows: este tutorial fornece um exemplo com Invoke-WebRequest, que é suportado no PowerShell 3.0 e posterior.
2. Instale e inicialize a CLI gcloud.
3. Atualize a CLI gcloud e instale os componentes do Endpoints:

   gcloud components update

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

   No novo separador apresentado, selecione uma conta.
5. Defina o projeto predefinido para o ID do seu projeto:

   gcloud config set project YOUR_PROJECT_ID

   Substitua YOUR_PROJECT_ID pelo ID do seu projeto. Se tiver outros Google Cloud projetos e quiser usar gcloud para os gerir, consulte o artigo Gerir configurações da CLI gcloud.

6. Instalar kubectl:

   gcloud components install kubectl

7. Adquirir novas credenciais de utilizador para usar nas credenciais padrão da aplicação. As credenciais do utilizador autorizam o kubectl.

   gcloud auth application-default login

8. No novo separador apresentado, escolha uma conta.
9. Execute o seguinte comando para se certificar de que o cliente do Kubernetes está configurado corretamente:

   kubectl version

   Deverá ver uma saída semelhante à seguinte:

      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"}
      

Transferir o exemplo de código

Opcionalmente, transfira o exemplo de código. Neste tutorial, implementa uma imagem de contentor pré-criada, pelo que não tem de criar um contentor a partir do código de exemplo. No entanto, recomendamos que transfira o código de exemplo, que é fornecido em vários idiomas para ajudar a compreender o funcionamento da API de exemplo.

Para transferir o exemplo de código:

Java

Para clonar ou transferir a API de exemplo:

1. Clone o repositório da app de exemplo para a sua máquina local:

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

   Em alternativa, transfira o exemplo como um ficheiro ZIP e extraia-o.

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

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

Python

Para clonar ou transferir a API de exemplo:

1. Clone o repositório da app de exemplo para a sua máquina local:

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

   Em alternativa, transfira o exemplo como um ficheiro ZIP e extraia-o.

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

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

Ir

Para clonar ou transferir a API de exemplo:

1. Certifique-se de que a variável de ambiente GOPATH está definida.
2. Clone o repositório da app de exemplo para a sua máquina local:

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

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

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

PHP

Para clonar ou transferir a API de exemplo:

1. Clone o repositório da app de exemplo para a sua máquina local:

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

   Em alternativa, transfira o exemplo como um ficheiro ZIP e extraia-o.

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

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

Ruby

Para clonar ou transferir a API de exemplo:

1. Clone o repositório da app de exemplo para a sua máquina local:

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

   Em alternativa, transfira o exemplo como um ficheiro ZIP e extraia-o.

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

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

NodeJS

Para clonar ou transferir a API de exemplo:

1. Clone o repositório da app de exemplo para a sua máquina local:

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

   Em alternativa, transfira o exemplo como um ficheiro ZIP e extraia-o.

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

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

Obter o ficheiro de configuração do Kubernetes

1. Clone o repositório do GitHub que contém os ficheiros yaml usados neste tutorial para o seu computador local:

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

   Em alternativa, transfira o exemplo como um ficheiro ZIP e extraia-o.

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

    cd endpoints-samples/kubernetes

Configurar pontos finais

Tem de ter um documento OpenAPI baseado no OpenAPI 2.0 ou no OpenAPI 3.x que descreva a superfície das suas apps e quaisquer requisitos de autenticação. Para saber mais, consulte o artigo Versões do OpenAPI suportadas.

Também tem de adicionar um campo específico da Google que contenha o URL de cada app para que o ESPv2 tenha as informações necessárias para invocar uma app. Se não conhece o OpenAPI, consulte a vista geral do OpenAPI para mais informações.

Para configurar pontos finais:

1. Crie um novo ficheiro de texto denominado openapi.yaml. Para facilitar, esta página refere-se ao documento OpenAPI por esse nome, mas pode atribuir-lhe outro nome se preferir.
2. Copie o conteúdo de um dos seguintes ficheiros para o novo ficheiro openapi.yaml. Pode optar por 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 da Google à especificação OpenAPI que lhe 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 está a usar.

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

1. Abra o ficheiro openapi.yaml.
2. No campo host, substitua YOUR_PROJECT_ID pelo seu Google Cloud ID do projeto.
3. Guarde o ficheiro 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 pontos finais:

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

Depois de concluir todos os passos de configuração seguintes para poder enviar pedidos com êxito para a API de exemplo através de um endereço IP, consulte o artigo Configurar o DNS dos pontos finais para ver informações sobre como configurar echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog para ser o nome de domínio totalmente qualificado (FQDN).

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

Para implementar a configuração do Endpoints, use o comando gcloud endpoints services deploy. Este comando usa a gestão de serviços para criar um serviço gerido.

Para implementar a configuração dos Endpoints:

1. Certifique-se de que está no diretório onde se encontra o ficheiro de configuração openapi.yaml.
2. Carregue a configuração e crie um serviço gerido:

   gcloud endpoints services deploy openapi.yaml
   

O comando gcloud chama a API Service Management para criar um serviço gerido com o nome especificado no campo host ou servers.url do ficheiro openapi.yaml. A gestão de serviços configura o serviço de acordo com as definições no ficheiro openapi.yaml. Quando faz alterações a openapi.yaml, tem de voltar a implementar o ficheiro para atualizar o serviço Endpoints.

À medida que cria e configura o serviço, o Service Management envia informações para o terminal. Pode ignorar com segurança os avisos sobre os caminhos no ficheiro openapi.yaml que não requerem uma chave da API. Quando terminar de configurar o serviço, a gestão de serviços apresenta uma mensagem com o ID de configuração do serviço e o nome do serviço, semelhante ao seguinte:

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 Endpoints. O ID de configuração do serviço consiste numa data/hora seguida de um número de revisão. Se implementar o ficheiro openapi.yaml novamente no mesmo dia, o número de revisão é incrementado no ID de configuração do serviço. Pode ver a configuração do serviço Endpoints na página Endpoints > Serviços na Google Cloud consola.

Se receber uma mensagem de erro, consulte o artigo Resolução de problemas da implementação da configuração de pontos finais.

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, o Compute Engine ou o ambiente flexível do App 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 que não seja oGoogle Cloud , como o seu computador local, um cluster 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 chaves 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

1. Na Google Cloud consola, abra a página Contas de serviço .

   Aceda à página Contas de serviço

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

12. 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 se autenticar como a sua conta de serviço. Pode mover e mudar o nome deste ficheiro como quiser.

13. Clique em Fechar.

gcloud

1. Introduza o seguinte para apresentar os IDs dos seus Google Cloud projetos:

   gcloud projects list

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

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

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

5. 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 controlo de serviços, que usa a configuração do serviço de endpoint. A configuração do serviço de ponto final é um recurso do IAM, e o ESP e o ESPv2 precisam da função Controlador de serviços para aceder a ele.

A função IAM está na configuração do serviço de ponto final e não no projeto. Um projeto pode ter várias configurações de serviços de pontos finais.

Use o seguinte comando gcloud para adicionar a função à conta de serviço anexada para a configuração do serviço de ponto final.

gcloud endpoints services add-iam-policy-binding SERVICE_NAME \
  --member serviceAccount:SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com \
  --role roles/servicemanagement.serviceController

Onde
* SERVICE_NAME é o nome do serviço de ponto final
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com é a conta de serviço anexada.

Cloud Trace

O ESP e o ESPv2 chamam o serviço Cloud Trace para exportar o rastreio para um projeto. Este projeto é denominado projeto de rastreio. No ESP, o projeto de rastreio e o projeto que detém a configuração do serviço de ponto final são os mesmos. No ESPv2, o projeto de rastreio pode ser especificado através da flag --tracing_project_id e é predefinido como o projeto de implementação.

O ESP e o ESPv2 requerem a função Agente do Cloud Trace para ativar o Cloud Trace.

Use o seguinte comando gcloud para adicionar a função à conta de serviço anexada:

gcloud projects add-iam-policy-binding TRACING_PROJECT_ID \
  --member serviceAccount:SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com \
  --role roles/cloudtrace.agent

Onde
* TRACING_PROJECT_ID é o ID do projeto de rastreio
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com é a conta de serviço anexada. Para mais informações, consulte o artigo O que são funções e autorizações?

Consulte gcloud iam service-accounts para mais informações sobre os comandos.

Implementar o back-end da API

Até agora, implementou o documento OpenAPI no Service Management, 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.

A verificar as autorizações necessárias

Conceda as autorizações necessárias à conta de serviço associada ao seu cluster:

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

Para mais informações, consulte o artigo O que são funções e autorizações?

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:

1. Certifique-se de que muda o nome do ficheiro JSON para service-account-creds.json e o copia para endpoints-samples/kubernetes se tiver sido transferido para um diretório diferente. Desta forma, o nome corresponde às opções especificadas no ficheiro de manifesto de implementação echo.yaml.
2. Certifique-se de que está no diretório endpoints-samples/kubernetes.

3. Crie um segredo do Kubernetes com as credenciais da conta de serviço através do seguinte comando:

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

   Em caso de êxito, é 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:

1. Abra o ficheiro do manifesto de implementação, echo.yaml, e substitua SERVICE_NAME nas opções de arranque do ESPv2 pelo nome do seu serviço. Este é o mesmo nome que configurou no campo host ou server.url do seu documento OpenAPI. Por 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 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 ver informações sobre as outras opções do ESPv2 usadas, 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 como 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.

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

   kubectl create -f echo.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 o artigo Configure o kubectl para mais informações. Para mais informações, consulte o artigo Implementar Endpoints no Kubernetes.

Obtenha o endereço IP externo do serviço

Se estiver a usar o Minikube, avance para a secção Enviar um pedido através de um endereço IP. Depois de iniciar o serviço no contentor, pode demorar alguns minutos até que o endereço IP externo esteja pronto.

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

1. Execute o seguinte comando:

   kubectl get service

2. Tome nota do valor de EXTERNAL-IP. Usa esse endereço IP quando envia um pedido para a API de exemplo.

Enviar um pedido através de um endereço IP

Depois de a API de amostra estar em execução no cluster de contentores, pode enviar pedidos para a API.

Crie uma chave da API e defina uma variável de ambiente

O código de exemplo requer uma chave da API. Para simplificar o pedido, defina uma variável de ambiente para a chave da API.

1. No mesmo Google Cloud projeto que usou para a sua API, crie uma chave da API na página de credenciais da API. Se quiser criar uma chave da API num Google Cloud projeto diferente, consulte o artigo Ativar uma API no seu Google Cloud projeto.

   Aceda à página Credenciais

2. Clique em Criar credenciais e, de 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 a atribuir a uma variável de ambiente:
   • No Linux ou macOS: export ENDPOINTS_KEY=AIza...
   • No Windows PowerShell: $Env:ENDPOINTS_KEY="AIza..."

Envie o pedido para minikube

Os seguintes comandos usam a variável de ambiente ENDPOINTS_KEY que 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

Envie o pedido para outros clusters do Kubernetes

Linux ou Mac OS

Use curl para enviar um pedido HTTP através da variável de ambiente ENDPOINTS_KEY que definiu anteriormente. Substitua IP_ADDRESS pelo endereço IP externo da sua instância.

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

Nos curl anteriores:

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

PowerShell

Use Invoke-WebRequest para enviar um pedido HTTP através da variável de ambiente ENDPOINTS_KEY que definiu anteriormente. Substitua IP_ADDRESS pelo endereço IP externo da sua 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 anterior, as duas primeiras linhas terminam com um acento grave. Quando colar o exemplo no PowerShell, certifique-se de que não existe um espaço após os acentos graves. Para obter informações sobre as opções usadas no pedido de exemplo, consulte Invoke-WebRequest na documentação da Microsoft.

App de terceiros

Pode usar uma aplicação de terceiros, como a extensão do navegador Chrome Postman, para enviar o pedido:

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

A API devolve a mensagem que envia e responde com o seguinte:

{
  "message": "hello world"
}

Se não recebeu uma resposta bem-sucedida, consulte o artigo Resolução de problemas de erros de resposta.

Acabou de implementar e testar uma API no Endpoints!

Nota: se quiser partilhar o que gostou neste tutorial, não hesite em enviar feedback na parte inferior desta página. O seu feedback ajuda-nos a melhorar estes tutoriais.
Se recebeu um erro, junte-se ao google-cloud-endpoints grupo Google e diga-nos o que correu mal. Este grupo recebe respostas de outros utilizadores do Endpoints e de engenheiros da Google, que monitorizam o grupo.

Acompanhamento da atividade da API

Para acompanhar a atividade da API:

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

2. Consulte os registos de pedidos da sua API na página do explorador de registos.
   

   Aceda à página do Explorador de registos

Configurar o DNS para pontos finais

Uma vez que o nome do serviço Endpoints para a API está no domínio .endpoints.YOUR_PROJECT_ID.cloud.goog, pode usá-lo como o nome de domínio totalmente qualificado (FQDN) fazendo uma pequena alteração de configuração no ficheiro openapi.yaml. Desta forma, pode enviar pedidos para a API de exemplo através de echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog em vez do endereço IP.

Para configurar o DNS dos Endpoints:

OpenAPI 2.0

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

   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 seu projeto.
3. Na propriedade target, substitua IP_ADDRESS pelo endereço IP que usou quando enviou um pedido para a API de exemplo.
4. Implemente o ficheiro de configuração OpenAPI atualizado na gestão de serviços:

   gcloud endpoints services deploy openapi.yaml
   

OpenAPI 3.x

1. Abra o ficheiro de configuração da OpenAPI, openapi.yaml, e adicione a propriedade servers.url no nível superior do ficheiro (sem recuo nem aninhamento), conforme mostrado no seguinte fragmento:

   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 seu projeto.
3. Na propriedade target, substitua IP_ADDRESS pelo endereço IP que usou quando enviou um pedido para a API de exemplo.
4. Implemente o ficheiro de configuração OpenAPI atualizado na gestão de serviços:

   gcloud endpoints services deploy openapi.yaml
   

Por exemplo, suponha que o ficheiro openapi.yaml tem a seguinte configuração:

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"

Quando implementa o ficheiro openapi.yaml através do comando gcloud anterior, a gestão de serviços cria um registo A de DNS, echo-api.endpoints.my-project-id.cloud.goog, que é resolvido para o endereço IP de destino, 192.0.2.1. A propagação da nova configuração de DNS pode demorar alguns minutos.

Configurar SSL

Para mais detalhes sobre como configurar o DNS e o SSL, consulte o artigo Ativar SSL para pontos finais.

Enviar um pedido para o FQDN

Agora que tem o registo DNS configurado para a API de exemplo, envie-lhe um pedido usando o FQDN (substitua YOUR_PROJECT_ID pelo ID do seu 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 incorrer em custos na sua conta do Google Cloud pelos recursos usados neste tutorial, elimine o projeto que contém os recursos ou mantenha o projeto e elimine os recursos individuais.

Limpar

• Elimine o serviço e a implementação do Kubernetes:

  kubectl delete -f echo.yaml

Consulte o artigo Eliminar uma API e instâncias de API para obter informações sobre como parar os serviços usados por este tutorial.

O que se segue?

• Saiba como implementar o Endpoints no Google Kubernetes Engine.
• Saiba como criar uma imagem do Docker.
• Partilhe a sua API com outro programador.
• Saiba mais acerca da autenticação.
• Saiba mais acerca das opções de apoio técnico da comunidade.
• Resolução de problemas de implementação do GKE.