Primeiros passos com o Cloud Endpoints para Kubernetes com ESPv2

Como fazer o download do código de amostra

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

Para fazer o download do código de amostra:

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

O código de amostra inclui o arquivo de configuração da OpenAPI, openapi.yaml, que é baseado na especificação OpenAPI v2.0 (em inglês). Para configurar o Endpoints:

1. No diretório de código de amostra, abra o arquivo de configuração openapi.yaml.
   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"

   Observe o seguinte:

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

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-samples/kubernetes.
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. Você pode conferir a configuração do serviço 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

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:

• Após 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 nos ambientes do Google Cloud, como o GKE, o Compute Engine ou o ambiente flexível do App Engine, o ESP e o ESPv2 recebem tokens de acesso por meio do serviço de metadados do Google Cloud.

Quando você implanta o ESP ou ESPv2 em um ambiente que não é do Google Cloud, como como sua área de trabalho local, um cluster do Kubernetes no local ou outra nuvem provedor, forneça um arquivo JSON da conta de serviço que contém 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 ou a Google Cloud CLI Para criar a conta de serviço e o arquivo de chave privada:

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 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 obter mais informações, consulte O que são papéis e permissões?

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

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 fornecer ESPv2 com acesso às credenciais, crie um Chave secreta do Kubernetes e ativar o secret do Kubernetes Volume do Kubernetes.

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. Esse nome é o mesmo que você configurou no campo host 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 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.

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. Consulte Configurar a kubectl para mais informações. 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 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 para minikube

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

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}

$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

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

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

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.

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

Por exemplo, suponha que o arquivo openapi.yaml esteja configurado desta forma:

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 ao FQDN

• 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 amostra. Para saber mais, consulte a Visão geral do Portal do Cloud Endpoints.