Configure a API Cloud Endpoints OpenAPI para o Knative Serving com o ESPv2

Esta página mostra como configurar o Cloud Endpoints para o Knative serving. Os Endpoints usam o Extensible Service Proxy V2 (ESPv2) como um gateway de API. Para fornecer gestão de APIs para o Knative Serving, implementa o contentor ESPv2 pré-criado no Knative Serving em execução num cluster do GKE.

Com esta configuração, o ESPv2 interceta todos os pedidos aos seus serviços e realiza todas as verificações necessárias (como a autenticação) antes de invocar o serviço. Quando o serviço responde, o ESPv2 recolhe e comunica a telemetria.

Para uma vista geral dos pontos finais, consulte os artigos Acerca dos pontos finais e Arquitetura dos pontos finais.

Lista de tarefas

Use a seguinte lista de tarefas enquanto segue o tutorial. Todas as tarefas são necessárias para concluir este tutorial.

  1. Crie um Google Cloud projeto e, se ainda não tiver implementado o seu próprio Knative Serving, implemente um serviço de exemplo. Consulte a secção Antes de começar.

  2. Crie um cluster do GKE com a publicação do Knative ativada.

  3. Implemente um serviço de fornecimento do Knative de exemplo.

  4. Crie um documento OpenAPI que descreva a sua API Endpoints e configure as rotas para o seu serviço Knative serving. Consulte o artigo Configurar pontos finais.

  5. Implemente o documento OpenAPI para criar um serviço gerido. Consulte o artigo Implementar a configuração dos Endpoints.

  6. Crie uma nova imagem Docker do ESPv2 com a configuração do serviço Endpoints. Consulte o artigo Criar uma nova imagem do ESPv2.

  7. Implemente a nova imagem de publicação do Knative ESPv2. Consulte o artigo Implementar a imagem do Cloud Run do ESPv2.

  8. Crie um mapeamento de domínio para o serviço de publicação do Knative ESPv2.

  9. Teste a sua configuração enviando um pedido para a API.

  10. Monitorize a atividade nos seus serviços. Consulte o artigo Acompanhamento da atividade da API.

  11. Limpar.

Custos

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

Para gerar uma estimativa de custos com base na sua utilização projetada, 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

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

  2. 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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

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

  4. 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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

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

  6. Tome nota do ID do projeto, pois é necessário mais tarde. No resto desta página, este ID do projeto é designado ESPv2_PROJECT_ID.
  7. Transfira e instale o SDK do Google Cloud.
  8. Instale o cURL se quiser enviar um pedido ao serviço de exemplo implementado.

    9. Configurar a linha de comandos gcloud

    Para configurar a CLI gcloud para o Knative Serving para Anthos:

    1. Certifique-se de que o Google Cloud SDK está autorizado a aceder aos seus dados e serviços.

      1. Inicie sessão. 

        gcloud auth login

      2. No novo separador do navegador apresentado, escolha uma conta com a função de Editor ou Proprietário no projeto do Google Cloud que criou para implementar o ESPv2 no Knative Serving.

    2. Atualize os componentes gcloud instalados:

      gcloud components update

    3. Defina a plataforma como gke e defina a predefinição do projeto para gcloud como a que acabou de criar:

      gcloud config set run/platform gke
gcloud config set project ESPv2_PROJECT_ID

      Substitua ESPv2_PROJECT_ID pelo ID do projeto que criou.

    4. Defina a zona pretendida para o novo cluster. Pode usar qualquer zona onde o GKE seja suportado, por exemplo:

      gcloud config set compute/zone ZONE

      Substitua ZONE pela sua zona. Por exemplo, use us-central1-a. Pode usar qualquer zona suportada pelo GKE.

    5. Ative as seguintes APIs para o projeto, que são necessárias para criar um cluster, criar e publicar um contentor no Artifact Registry:

      gcloud services enable container.googleapis.com artifactregistry.googleapis.com cloudbuild.googleapis.com

Criar um cluster do GKE com o Knative Serving ativado

Para criar um cluster e ativá-lo para publicação do Knative no Google Cloud:

  1. Crie um novo cluster com o comando:

    gcloud container clusters create CLUSTER_NAME \
  --addons=HttpLoadBalancing,CloudRun \
  --machine-type=n1-standard-4 \
  --num-nodes=3 \
  --enable-stackdriver-kubernetes

    Substitua CLUSTER_NAME pelo nome que quer dar ao cluster.

    Embora estas instruções não ativem a capacidade de escala automática de clusters para redimensionar clusters em função da procura, o Knative Serving no Google Cloud dimensiona automaticamente as instâncias no cluster.

  2. Aguarde pela conclusão da criação do cluster. Durante o processo de criação, deve ver mensagens semelhantes às seguintes:

    Creating cluster CLUSTER_NAME...done.
Created [https://container.googleapis.com/v1/projects/ESPv2_PROJECT_ID/zones/ZONE/clusters/CLUSTER_NAME].

    A saída também mostra a versão do cluster na coluna NODE_VERSION da saída. Por exemplo, 1.15.11-gke.1 ou 1.14.10-gke.27. Tome nota da versão do cluster para utilização posterior neste documento.

  3. Defina os valores predefinidos gcloud para usar o novo cluster e a localização do cluster, para evitar ter de os especificar quando usar a CLI gcloud:

    gcloud config set run/cluster CLUSTER_NAME
gcloud config set run/cluster_location ZONE

  4. Use o seguinte comando para ver detalhes sobre o novo cluster:

    gcloud container clusters describe CLUSTER_NAME

  5. Use o seguinte comando para obter as credenciais do seu cluster:

    gcloud container clusters get-credentials CLUSTER_NAME

Implementar um contentor de publicação do Knative de exemplo

Para implementar o contentor de exemplo do Knative Serving "hello" no cluster que acabou de criar:

  1. Aceda ao Cloud Run

  2. Clique em Criar serviço.

  3. Selecione Knative serving como plataforma de desenvolvimento.

  4. No menu pendente de clusters disponíveis, selecione o cluster que acabou de criar.

  5. Use o nome hello como o nome do serviço. Pode usar outro nome, mas, se o fizer, certifique-se de que o usa mais tarde. Estas instruções pressupõem que usa hello.

  6. Selecione Interno em Conetividade para que o serviço não seja acessível externamente.

  7. Clique em Seguinte para continuar para a segunda página do formulário de criação de serviços.

  8. Especifique gcr.io/cloudrun/hello como o URL da imagem do contentor.

  9. Clique em Criar para implementar a imagem no Knative Serving e aguarde pela conclusão da implementação.

    Quando terminar, é apresentado o ecrã Revisões. Tenha em atenção que o URL do serviço implementado é:

    http://hello.default.svc.cluster.local

    Quando cria um serviço interno, o GKE cria um nome DNS que só pode ser resolvido para pedidos originados no próprio cluster e não para pedidos externos. Não pode aceder a este link externamente a partir do cluster. Consulte os serviços do Cloud Run para mais informações.

  10. Para verificar se o seu serviço está a funcionar corretamente através do cURL, configure um túnel do seu computador para o cluster. Para ver estas instruções, clique no ícone à direita do URL no ecrã Revisões:

    Ecrã Revisões.

  11. É aberto um painel que mostra os dois comandos que usa para aceder ao serviço interno. Tem de executar estes comandos em duas janelas de terminal separadas porque o primeiro comando configura o encaminhamento de portas que é usado pelo segundo comando.

    Quando executar o comando cURL, deve ver o resultado do seu serviço no seguinte formato:

    <!doctype html>
<html lang=en>
<head>
<meta charset=utf-8>
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Congratulations | Cloud Run</title> 
...

Configurar pontos finais

Tem de ter um documento OpenAPI baseado na especificação OpenAPI v2.0 que descreva a superfície do seu serviço de back-end e quaisquer requisitos de autenticação. Também tem de adicionar um campo específico da Google que contenha o URL de cada serviço para que o ESPv2 tenha as informações necessárias para invocar um serviço. Se não conhece a OpenAPI, consulte a descrição geral da OpenAPI para ver mais informações.

Acerca da definição do campo de anfitrião da especificação OpenAPI

No campo host da especificação OpenAPI, especifica o nome do serviço Endpoints usado para aceder ao seu serviço Knative Serving. O nome do serviço Endpoints está no formato de um nome de domínio:

API_NAME.endpoints.ESPv2_PROJECT_ID.cloud.goog

Uma vez que o nome do serviço Endpoints corresponde a um nome de domínio, o nome tem de seguir estas regras:

  • Tem de conter apenas letras minúsculas, números, pontos finais ou travessões.
  • Não pode começar com um traço.
  • Não pode conter um sublinhado.

Por exemplo:

hello-api.endpoints.ESPv2_PROJECT_ID.cloud.goog

Criar a especificação OpenAPI

  1. Crie um ficheiro de texto denominado openapi-run-anthos.yaml.

  2. O seu serviço de back-end de publicação do Knative está definido na parte superior do ficheiro openapi-run-anthos.yaml, numa definição x-google-backend. Por exemplo:

    swagger: '2.0'
info:
  title: Cloud Endpoints + Cloud Run
  description: Sample API on Cloud Endpoints with a Cloud Run backend
  version: 1.0.0
host: API_NAME.endpoints.ESPv2_PROJECT_ID.cloud.goog
x-google-endpoints:
- name: API_NAME.endpoints.ESPv2_PROJECT_ID.cloud.goog
  target: "INGRESS-IP"
schemes:
  - https
produces:
  - application/json
x-google-backend:
  address: http://hello.default.svc.cluster.local
  disable_auth: true
paths:
  /hello:
    get:
      summary: Greet a user
      operationId: hello
      responses:
        '200':
          description: A successful response
          schema:
            type: string

    O recuo é importante para o formato YAML. Por exemplo, o campo host tem de estar ao mesmo nível que info.

  3. No campo host, especifique o nome do domínio da API Endpoints usado para aceder ao seu serviço Knative Serving no formato:

    API_NAME.endpoints.ESPv2_PROJECT_ID.cloud.goog

    Por exemplo:

    hello-api.endpoints.ESPv2_PROJECT_ID.cloud.goog

  4. A extensão x-google-endpoints regista uma entrada DNS para o seu serviço Endpoints no domínio cloud.goog, no formato:

    x-google-endpoints:
  - name: "API_NAME.endpoints.ESPv2_PROJECT_ID.cloud.goog"
  target: "IP_ADDRESS"

    O IP_ADDRESS é o IP do serviço istio-ingress para o seu cluster. Para determinar este endereço IP:

    1. Aceda à página do Google Kubernetes Engine na Google Cloud consola:

      Aceda ao Google Kubernetes Engine

    2. Clique em Serviços e entrada no painel de navegação do lado esquerdo para apresentar uma lista de serviços.

    3. Se a versão do cluster for 1.15.3-gke.19 ou superior, 1.14.3-gke.12 ou superior, ou 1.13.10-gke.8 ou superior, desloque a página para baixo até ao serviço istio-ingress. Para todas as outras versões do cluster, desloque a página para baixo até ao serviço istio-ingressgateway.

    4. Copie o endereço IP externo apresentado junto ao equilibrador de carga, sem a definição da porta, se existir. Por exemplo, se o IP for 192.0.2.1:15020, omita o :15020. Ignore os outros endereços IP apresentados.

  5. No campo address da secção x-google-backend, especifique o nome DNS interno do serviço "hello" de fornecimento do Knative e desative a autenticação para este serviço. Isto é necessário porque a chamada do ESPv2 para o serviço Knative serving é feita como uma chamada interna a partir do cluster e, por isso, a autenticação não é necessária.

  6. Tome nota do valor da propriedade title no ficheiro openapi-run-anthos.yaml:

    title: Cloud Endpoints + Cloud Run

  7. O valor da propriedade title torna-se o nome do serviço Endpoints depois de implementar a configuração.

  8. Guarde o documento OpenAPI.

Para obter informações sobre os campos no documento OpenAPI que o Endpoints requer, consulte o artigo Configurar o Endpoints.

Implementar a configuração dos pontos finais

Para implementar a configuração do Endpoints, use o comando gcloud endpoints services deploy. Este comando usa a 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 que contém o seu documento OpenAPI.

  2. Carregue a configuração e crie um serviço gerido.

    gcloud endpoints services deploy openapi-run-anthos.yaml \
  --project ESPv2_PROJECT_ID

    Esta ação cria um novo serviço de Endpoints com o nome que especificou no campo host do ficheiro openapi-run-anthos.yaml. O serviço Endpoints está configurado de acordo com o seu documento OpenAPI.

    À medida que cria e configura o serviço Endpoints, o Service Management envia informações para o terminal. Quando a implementação estiver concluída, é apresentada uma mensagem semelhante à seguinte:

    Service Configuration [CONFIG_ID] uploaded for service [API_NAME.endpoints.ESPv2_PROJECT_ID.cloud.goog]

    CONFIG_ID é o ID de configuração do serviço Endpoints exclusivo criado pela implementação. Por exemplo:

    Service Configuration [2019-02-01r0] uploaded for service [hello-api.endpoints.ESPv2_PROJECT_ID.cloud.goog]

    O ID de configuração do serviço consiste numa indicação de data/hora seguida de um número de revisão. Se implementar o openapi-run-anthos.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 e o histórico de implementação na página Endpoints > Services na Google Cloud consola.

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

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 uma nova imagem de apresentação do Knative ESPv2

Crie a configuração do serviço Endpoints numa nova imagem Docker do ESPv2. Depois de criar esta imagem, pode implementá-la no seu cluster.

Para criar a configuração do serviço numa nova imagem Docker do ESPv2:

  1. Transfira este script para a sua máquina local onde a CLI gcloud está instalada e execute-o da seguinte forma:

    chmod +x gcloud_build_image
./gcloud_build_image -s API_NAME.endpoints.ESPv2_PROJECT_ID.cloud.goog \
-c CONFIG_ID -p ESPv2_PROJECT_ID

    O script usa o comando gcloud para transferir a configuração do serviço, criar a configuração do serviço numa nova imagem do ESPv2 e carregar a nova imagem para o registo de contentores do seu projeto. O script usa automaticamente a versão mais recente do ESPv2, indicada por ESPv2_VERSION no nome da imagem de saída. A imagem de saída é carregada para:

    gcr.io/ESPv2_PROJECT_ID/endpoints-runtime-serverless:ESPv2_VERSION-API_NAME.endpoints.ESPv2_PROJECT_ID.cloud.goog-CONFIG_ID

Implementar a imagem de publicação do ESPv2 Knative

Implemente a imagem do serviço de publicação do ESPv2 Knative no seu cluster:

  1. Implemente o serviço de publicação Knative do ESPv2 com a nova imagem:

    gcloud run deploy ESPv2_SERVICE_NAME \
  --image="gcr.io/ESPv2_PROJECT_ID/endpoints-runtime-serverless:ESPv2_VERSION-API_NAME.endpoints.ESPv2_PROJECT_ID.cloud.goog-CONFIG_ID" \
  --platform gke \
  --project=ESPv2_PROJECT_ID

    Para ESPv2_PROJECT_ID, especifique o nome que quer usar para o serviço ESPv2. Neste exemplo, defina ESPv2_SERVICE_NAME como espv2.

  2. Se quiser configurar os Endpoints para usar opções de arranque do ESPv2 adicionais, como ativar o CORS, pode transmitir os argumentos na variável de ambiente ESPv2_ARGS:

    gcloud run deploy ESPv2_SERVICE_NAME \
  --image="gcr.io/ESPv2_PROJECT_ID/endpoints-runtime-serverless:ESPv2_VERSION-API_NAME.endpoints.ESPv2_PROJECT_ID.cloud.goog-CONFIG_ID" \
  --set-env-vars=ESPv2_ARGS=--cors_preset=basic \
  --platform gke \
  --project ESPv2_PROJECT_ID

    Para mais informações e exemplos sobre a definição da variável de ambiente ESPv2_ARGS, incluindo a lista de opções disponíveis e informações sobre como especificar várias opções, consulte o artigo Flags do proxy de serviço extensível V2.

  3. Conceda autorização ao ESPv2 para chamar o Service Management e o Service Control.

    • Na Google Cloud consola, aceda à página do Cloud Run.

      Aceda à página do Cloud Run

    • Encontre a instância do Cloud Run que implementou e a conta de serviço associada.

    • Conceda as autorizações necessárias à conta de serviço: 

      gcloud projects add-iam-policy-binding PROJECT_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?

O serviço ESPv2 é implementado como um serviço externo, o que significa que pode aceder ao mesmo através de um comando cURL no seguinte formato:

curl -H "Host: espv2.default.example.com" http://IP_ADDRESS

em que IP_ADDRESS é o endereço IP do serviço istio-ingress para o seu cluster.

Para ver este comando cURL, clique no ícone de IMAGEM à direita do URL do ESPv2 no ecrã Revisões do serviço de publicação do Knative ESPv2 implementado.

Agora, pode fazer chamadas API para o seu serviço Endpoints através do serviço ESPv2. Por exemplo, para fazer um pedido a um serviço de Endpoints com um caminho de /hello, pode fazer um pedido no formato:

curl -H "Host: espv2.default.example.com" http://IP_ADDRESS/hello

No entanto, especificar um cabeçalho host em cada pedido ao seu serviço Endpoints não é fácil de usar. Na secção seguinte, configura um mapeamento de domínios para facilitar a chamada ao seu serviço de API Endpoint através do ESPv2.

Criar um mapeamento de domínio para o serviço de publicação do Knative ESPv2

Para poder omitir o cabeçalho host quando fizer um pedido, adicione um mapeamento de domínio para o serviço ESPv2:

  1. Aceda ao Cloud Run

  2. Selecione Gerir domínios personalizados.

  3. Selecione Adicionar mapeamento.

  4. No menu pendente, selecione Adicionar mapeamento de domínio de serviço.

  5. No campo Selecionar um serviço para mapear do pop-up Adicionar mapeamento, selecione o seu serviço ESPv2.

  6. No campo Introduza o nome do domínio, especifique o nome do domínio que quer usar para aceder ao seu serviço Knative serving através dos Endpoints. Por exemplo, especifique:

    API_NAME.endpoints.ESPv2_PROJECT_ID.cloud.goog

    Em que API_NAME é o nome da sua API Endpoints. Para este exemplo, pode usar "hello-api": 

    hello-api.endpoints.ESPv2_PROJECT_ID.cloud.goog

  7. Clique em Continuar. É apresentado um resumo do mapeamento.

  8. Selecione Concluído para guardar o mapeamento.

Enviar pedidos para a API

Use o cURL para enviar um pedido HTTP para a sua API:

curl -X GET "http://hello-api.endpoints.ESPv2_PROJECT_ID.cloud.goog/hello"

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

Configurar a API Endpoints para usar HTTPS

O suporte de TLS automático está desativado por predefinição para o Knative Serving no Google Cloud. Por conseguinte, neste exemplo, quando acede à API Endpoints através do ESPv2, faz a chamada através de HTTP.

Pode configurar o ESPv2 para suportar pedidos através de HTTPS. Tenha em atenção que configura o suporte de HTTPS no ESPv2, o serviço externo, e não em "hello", o serviço de back-end interno.

Para suportar HTTPS com o ESPv2, tem de:

  1. Ter um domínio. Se não tiver um domínio, pode obtê-lo no Cloud Domains ou noutro fornecedor de domínios.

  2. Criou um mapeamento de domínio para o seu serviço ESPv2 e atualizou o registo DNS em conformidade, seguindo as instruções na página de mapeamento de domínios.

    Se obteve o seu domínio a partir do Cloud Domains, use o Cloud DNS, ou um servidor DNS à sua escolha. Usar um domínio do Cloud Domains é a opção mais fácil.

  3. Na especificação OpenAPI dos Endpoints:

    1. Defina o campo host para fazer referência ao seu domínio em vez de a *.cloud.goog.

    2. Remova a etiqueta x-google-endpoints e as respetivas duas propriedades secundárias.

Para ver instruções completas e um tutorial, consulte o artigo Ativar HTTPS e certificados TLS automáticos.

Acompanhamento da atividade da API

  1. Veja os gráficos de atividade da sua API na página Endpoints > Service na Google Cloud consola.

    Veja gráficos de atividade 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. Veja os registos de pedidos de pontos finais

Limpar

Para evitar incorrer em cobranças na sua Google Cloud conta pelos recursos usados nesta página, siga estes passos.

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?