Configurar a OpenAPI do Cloud Endpoints para Knative serving com o ESPv2
Nesta página, mostramos como configurar o Cloud Endpoints para o Knative serving. O Endpoints usa o Extensible Service Proxy V2 (ESPv2) como um gateway de API. Para fornecer gerenciamento de API para o serviço Knative, implante o contêiner ESPv2 pré-construído no serviço Knative em execução em um cluster do GKE.
Com essa configuração, o ESPv2 intercepta todas as solicitações e executa as verificações necessárias, como a autenticação, antes de invocar o serviço. Quando o serviço responde, a telemetria é coletada e relatada pelo ESPv2.
Para uma visão geral do Endpoints, consulte Sobre o Endpoints e Arquitetura do Endpoints.
Lista de tarefas
Ao seguir o tutorial, use a lista de tarefas abaixo. Todas as tarefas são necessárias para concluir este tutorial.
Crie um projeto do Google Cloud e, se você não tiver implantado seu próprio Knative serving, implante um serviço de amostra. Consulte Antes de começar.
Crie um cluster do GKE com a exibição do Knative ativada.
Implante um serviço de amostra do Knative serving.
Crie um documento da OpenAPI que descreva sua API Endpoints e configure as rotas para o serviço do Knative serving. Consulte Como configurar o Endpoints.
Implante o documento do OpenAPI para criar um serviço gerenciado. Consulte Como implantar a configuração do Endpoints.
Crie uma nova imagem do Docker do ESPv2 com a configuração do serviço do Endpoints. Consulte Como criar uma nova imagem do ESPv2.
Implante a nova imagem de veiculação do Knative do ESPv2. Consulte Como implantar a imagem ESPv2 Beta do Cloud Run.
Crie um mapeamento de domínio para o serviço de veiculação do Knative ESPv2.
Teste sua configuração em Como enviar uma solicitação para a API.
Rastrear a atividade para seus serviços. Consulte Como rastrear a atividade da API.
Custos
Neste documento, você usará os seguintes componentes faturáveis do Google Cloud:
Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços.
Ao concluir as tarefas descritas neste documento, é possível evitar o faturamento contínuo excluindo os recursos criados. Saiba mais em Limpeza.
Antes de começar
- 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.
-
Verifique se a cobrança está ativada para o seu projeto do Google Cloud.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Verifique se a cobrança está ativada para o seu projeto do Google Cloud.
- Anote o ID do projeto, porque ele será necessário mais tarde. No restante desta página, esse ID do projeto é chamado de ESP_PROJECT_ID.
- Faça o download e instale o SDK Google Cloud.
- Instale cURL se quiser enviar uma solicitação para o serviço de amostra implantado.
Como configurar a linha de comando gcloud
Para configurar a CLI gcloud para o Knative serving for Anthos:
Verifique se o SDK do Google Cloud tem autorização para acessar seus dados e serviços.
Faça login.
gcloud auth login
Na nova guia do navegador que é aberta, escolha uma conta que tenha o papel de Editor ou Proprietário no projeto do Google Cloud que você criou para implantar o ESPv2 no serviço Knative.
Atualize os componentes do
gcloud
instalados:gcloud components update
Defina a plataforma como
gke
e defina a configuração de projeto padrão paragcloud
como a que você acabou de criar:gcloud config set run/platform gke
gcloud config set project ESP_PROJECT_ID
Substitua ESP_PROJECT_ID pelo ID do projeto que você criou.
Defina a zona que você quer para o novo cluster. É possível usar qualquer zona compatível com o GKE, por exemplo:
gcloud config set compute/zone ZONE
Substitua ZONE pela sua zona. Por exemplo, use
us-central1-a
. É possível usar qualquer zona compatível com o GKE.Ative as APIs do projeto a seguir, necessárias para criar um cluster, compilar e publicar um contêiner no Google Container Registry:
gcloud services enable container.googleapis.com containerregistry.googleapis.com cloudbuild.googleapis.com
Como criar um cluster do GKE com a exibição do Knative ativada
Para criar um cluster e ativá-lo para o Knative serving no Google Cloud:
Crie um cluster novo usando 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 do seu cluster.
Embora essas instruções não ativem o escalonamento automático de cluster para redimensionar clusters para demanda, o serviço Knative no Google Cloud escalona automaticamente as instâncias no cluster.
Aguarde a conclusão da criação do cluster. Durante o processo de criação, você verá mensagens semelhantes a estas:
Creating cluster CLUSTER_NAME...done. Created [https://container.googleapis.com/v1/projects/ESP_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
ou1.14.10-gke.27
. Anote a versão do cluster para uso posterior neste documento.Defina os padrões do
gcloud
para usar o novo cluster e o local do cluster para não precisar especificá-los ao usar a CLI gcloud:gcloud config set run/cluster CLUSTER_NAME
gcloud config set run/cluster_location ZONE
Use o seguinte comando para ver detalhes sobre o novo cluster:
gcloud container clusters describe CLUSTER_NAME
Use o seguinte comando para buscar credenciais para o cluster:
gcloud container clusters get-credentials CLUSTER_NAME
Como implantar um contêiner de amostra do Knative
Para implantar o "hello" Contêiner de amostra do Knative serving no cluster que você acabou de criar:
Clique em Criar serviço.
Selecione o Knative serving como sua plataforma de desenvolvimento.
No menu suspenso de clusters disponíveis, selecione o cluster que você acabou de criar.
Use hello como o nome do serviço. É possível usar outro nome. Porém, se fizer isso, use o mesmo nome mais tarde. Nessas instruções, supõe-se que você use hello.
Selecione Interno em Conectividade para que o serviço não seja acessível externamente.
Clique em Avançar para acessar a segunda página do formulário de criação de serviço:
Especifique
gcr.io/cloudrun/hello
como o URL da imagem do contêiner.Clique em Criar para implantar a imagem no Knative serving e aguarde a conclusão da implantação.
Quando terminar, a tela Revisão será exibida. Observe que o URL do serviço implantado é:
http://hello.default.svc.cluster.local
Quando você cria um serviço Interno, o GKE cria um nome DNS que só pode ser resolvido para solicitações originadas no próprio cluster, não para solicitações externas. Não é possível acessar esse link externamente a partir do cluster. Consulte Serviços do Cloud Run para saber mais.
Para verificar se o serviço está funcionando corretamente usando cURL, configure um túnel da área de trabalho para o cluster. Para ver estas instruções, clique no ícone à direita do URL na tela Revisão:
Um painel é aberto mostrando os dois comandos que você usa para acessar o serviço interno. Execute esses comandos em duas janelas de terminal separadas porque o primeiro comando configura o encaminhamento de porta usado pelo segundo comando.
Ao executar o comando cURL, você verá a saída do serviço no formulário:
<!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> ...
Como configurar o Endpoints
É necessário ter um documento da OpenAPI baseado na especificação OpenAPI v2.0 (em inglês) que descreve a superfície do seu serviço de back-end e quaisquer requisitos de autenticação. Também é preciso adicionar um campo específico do 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 você é novo na OpenAPI, consulte a visão geral da OpenAPI para ver mais informações
Sobre a configuração do campo host da especificação da OpenAPI
No campo host
da especificação OpenAPI, especifique o nome do serviço do Endpoints usado para acessar o serviço de veiculação do Knative. O nome do serviço do Endpoints está na forma de um nome de domínio:
API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog
Como o nome do serviço do Endpoints corresponde a um nome de domínio, o nome precisa seguir estas regras:
- Precisa conter apenas letras minúsculas, números, pontos ou traços.
- Não pode começar com um traço.
- Não pode conter um sublinhado.
Exemplo:
hello-api.endpoints.ESP_PROJECT_ID.cloud.goog
Como criar a especificação OpenAPI
Crie um arquivo de texto chamado
openapi-run-anthos.yaml
.Seu serviço de back-end do Knative serving é definido na parte superior do arquivo
openapi-run-anthos.yaml
, em uma definiçãox-google-backend
. 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.ESP_PROJECT_ID.cloud.goog x-google-endpoints: - name: API_NAME.endpoints.ESP_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
deve estar no mesmo nível deinfo
.No campo
host
, especifique o nome de domínio da API Endpoints usada para acessar o serviço de veiculação do Knative, no formato:API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog
Exemplo:
hello-api.endpoints.ESP_PROJECT_ID.cloud.goog
A extensão
x-google-endpoints
registra uma entrada DNS para o serviço do Endpoints no domíniocloud.goog
, no formato:x-google-endpoints: - name: "API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog" target: "IP_ADDRESS"
IP_ADDRESS é o IP do serviço
istio-ingress
do cluster. Para determinar esse endereço IP:Acesse a página do Google Kubernetes Engine no console do Google Cloud:
Clique em Serviços e entrada no painel de navegação esquerdo para exibir uma lista de serviços.
Se a versão do cluster for
1.15.3-gke.19
ou superior,1.14.3-gke.12
ou superior, ou1.13.10-gke.8
ou superior, role para baixo até o serviçoistio-ingress
. Para todas as outras versões do cluster, role para baixo até o serviçoistio-ingressgateway
.Copie o endereço IP externo mostrado ao lado do Balanceador de carga, sem a configuração de porta, se houver. Por exemplo, se o IP for
XX.XXX.XX.XXX:15020
, omitir o:15020
. Ignore os outros endereços IP listados.
No campo
address
, na seçãox-google-backend
, especifique o nome DNS interno do serviço de back-end Knative "hello" e desative a autenticação para esse serviço. Isso é necessário porque a chamada do ESPv2 para o serviço do Knative serving é feita como uma chamada interna do cluster. Portanto, a autenticação não é necessária.Anote o valor da propriedade
title
no arquivoopenapi-run-anthos.yaml
:title: Cloud Endpoints + Cloud Run
O valor da propriedade
title
se tornará o nome do serviço do Endpoints depois que você implantar a configuração.Salve o documento do OpenAPI.
Para mais informações sobre os campos no documento da OpenAPI exigido pelo Endpoints, consulte Como configurar o Endpoints.
Como implantar a configuração do Endpoints
Para implantar a configuração do Endpoints, use o comando gcloud endpoints services deploy. Ele utiliza a Service Management para criar um serviço gerenciado.
Para implantar a configuração do Endpoints:
Verifique se você está no diretório que contém o documento do OpenAPI.
Faça upload da configuração e crie um serviço gerenciado:
gcloud endpoints services deploy openapi-run-anthos.yaml \ --project ESP_PROJECT_ID
Isso cria um novo serviço do Endpoints com o nome especificado no campo
host
do arquivoopenapi-run-anthos.yaml
. O serviço do Endpoints é configurado de acordo com o documento da OpenAPI.Durante a criação e a configuração do serviço do Endpoints, o Service Management envia informações ao terminal. Quando a implantação for concluída, uma mensagem parecida com esta será exibida:
Service Configuration [CONFIG_ID] uploaded for service [API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog]
CONFIG_ID é o ID exclusivo de configuração de serviço do Endpoints criado pela implantação. Exemplo:
Service Configuration [2019-02-01r0] uploaded for service [hello-api.endpoints.ESP_PROJECT_ID.cloud.goog]
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
openapi-run-anthos.yaml
novamente no mesmo dia, o número de revisão aumentará no ID de configuração do serviço. É possível conferir a configuração do serviço e o histórico de implantação 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
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 |
endpoints.googleapis.com |
Google Cloud Endpoints |
Na maioria dos casos, o comando gcloud endpoints services deploy
ativa os serviços necessários. No entanto, o comando gcloud
é concluído com êxito, mas não ativa os serviços necessários nas seguintes circunstâncias:
Você usou um aplicativo de terceiros, como o Terraform, e não incluiu esses serviços.
Você implantou a configuração do Endpoints em um projeto do Google Cloud existente, em que esses serviços foram desativados explicitamente.
Use o seguinte comando para confirmar se os serviços necessários estão ativados:
gcloud services list
Se você não encontrar os serviços necessários listados, ative-os:
gcloud services enable servicemanagement.googleapis.comgcloud services enable servicecontrol.googleapis.com
gcloud services enable endpoints.googleapis.com
Ative também seu serviço do Endpoints:
gcloud services enable ENDPOINTS_SERVICE_NAME
Para determinar o ENDPOINTS_SERVICE_NAME, é possível:
Depois de implantar a configuração do Endpoints, acesse a página Endpoints no console do Cloud. A lista de ENDPOINTS_SERVICE_NAME possíveis é mostrada na coluna Nome do serviço.
Para a OpenAPI, o ENDPOINTS_SERVICE_NAME é o que você especificou no campo
host
da especificação do OpenAPI. Para gRPC, o ENDPOINTS_SERVICE_NAME é o que você especificou no camponame
da configuração do gRPC Endpoints.
Para mais informações sobre os comandos gcloud
, consulte serviços gcloud
.
Como criar uma nova imagem do Knative serving do ESPv2
Crie a configuração do serviço do Endpoints em uma nova imagem docker do ESPv2. Depois de criar essa imagem, implante-a no cluster.
Para criar a configuração do serviço em uma nova imagem docker do ESPv2:
Faça o download deste script na máquina local em que a CLI gcloud está instalada e execute-o como:
chmod +x gcloud_build_image
./gcloud_build_image -s API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog \ -c CONFIG_ID -p ESP_PROJECT_ID
O script usa o comando da
gcloud
para fazer o download da configuração do serviço, criar essa configuração em uma nova imagem do ESPv2 e fazer upload da nova imagem no registro de contêiner do projeto. O script usa automaticamente a versão mais recente do ESPv2, indicada pelo ESP_VERSION no nome da imagem de saída. O upload da imagem de saída é feito para:gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog-CONFIG_ID
Como implantar a imagem de fornecimento do Knative do ESPv2
Implante a imagem do serviço ESPv2 Knative serving no cluster:
Implante o serviço de fornecimento Knative do ESPv2 com a nova imagem:
gcloud run deploy ESP_V2_SERVICE_NAME \ --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog-CONFIG_ID" \ --platform gke \ --project=ESP_PROJECT_ID
Em ESP_PROJECT_ID, especifique o nome que você quer usar para o serviço ESPv2. Neste exemplo, defina ESP_V2_SERVICE_NAME como
espv2
.Se você quiser configurar o Endpoints para usar opções adicionais de inicialização do ESPv2, como a de como ativar o CORS, passe os argumentos na variável de ambiente
ESPv2_ARGS
:gcloud run deploy ESP_V2_SERVICE_NAME \ --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog-CONFIG_ID" \ --set-env-vars=ESPv2_ARGS=--cors_preset=basic \ --platform gke \ --project ESP_PROJECT_ID
Para mais informações e exemplos sobre como configurar a 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 Sinalizações do Extensible Service Proxy V2.
O serviço ESPv2 é implantado como um serviço externo, o que significa que você pode acessá-lo usando um comando cURL no formulário:
curl -H "Host: espv2.default.example.com" http://IP_ADDRESS
em que IP_ADDRESS é o endereço IP do serviço istio-ingress
do cluster.
Para ver esse comando cURL, clique no ícone IMAGE à direita do URL do ESPv2 na tela Revisões do serviço de veiculação Knative do ESPv2 implantado.
Agora é possível fazer chamadas de API para o serviço do Endpoints por meio do serviço ESPv2. Por exemplo, para fazer uma solicitação a um serviço do Endpoints com um caminho /hello
, você pode fazer uma solicitação no formulário:
curl -H "Host: espv2.default.example.com" http://IP_ADDRESS/hello
No entanto, especificar um cabeçalho host
em todas as solicitações para o serviço do Endpoints dificulta o uso. Na próxima seção, você irá configurar um mapa de domínio para facilitar a realização de uma chamada ao serviço de endpoint por meio do ESPv2.
Como criar um mapeamento de domínio para o serviço ESPv2 Knative serving
Para poder omitir o cabeçalho host
ao fazer uma solicitação, adicione um mapeamento de domínio para o serviço ESPv2:
Selecione Gerenciar domínios personalizados.
Selecione Adicionar mapeamento.
No menu suspenso, selecione Adicionar mapeamento de domínio de serviço.
No campo Selecionar um serviço para mapear do pop-up Adicionar mapeamento, selecione o serviço ESPv2.
No campo Enter domain name, especifique o nome de domínio que você quer usar para acessar o serviço de veiculação do Knative pelo Endpoints. Por exemplo, especifique:
API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog
Em que API_NAME é o nome da API do Endpoints. Neste exemplo, você pode usar "hello-api":
hello-api.endpoints.ESP_PROJECT_ID.cloud.goog
Clique em Continuar. Um resumo do mapeamento é exibido.
Selecione Concluído para salvar o mapeamento.
Como enviar solicitações à API
Use o cURL para enviar uma solicitação HTTP para sua API:
curl -X GET "http://hello-api.endpoints.ESP_PROJECT_ID.cloud.goog/hello"
Se não receber uma resposta bem-sucedida, consulte Como solucionar problemas em erros de resposta.
Como configurar a API Endpoints para usar HTTPS
O suporte automático a TLS está desativado por padrão para o Knative serving no Google Cloud. Portanto, neste exemplo, ao acessar a API Endpoints por meio do ESPv2, você faz a chamada usando HTTP.
Você pode configurar o ESPv2 para oferecer suporte a solicitações usando HTTPS. Observe que você configura a compatibilidade com HTTPS no ESPv2, o serviço externo, não no "hello", o serviço de back-end interno.
Para oferecer suporte a HTTPS com o ESPv2, você precisa:
Tenha um domínio. Se você não tiver um domínio, poderá conseguir um no Cloud Domains ou em outro fornecedor de domínios.
Crie um mapeamento de domínio para o serviço ESPv2 e atualize o registro DNS seguindo as instruções na página de mapeamento de domínios.
Se você recebeu seu domínio do Cloud Domains, use o Cloud DNS ou um servidor DNS de sua escolha. Usar um domínio do Cloud Domains é a opção mais fácil.
Na especificação da OpenAPI do Endpoints:
Defina o campo
host
para se referir ao seu domínio em vez de*.cloud.goog
.Remova a tag
x-google-endpoints
e as duas propriedades filho.
Para instruções completas e um tutorial, consulte Como ativar certificados HTTPS e TLS automáticos.
Rastrear a atividade da API
Confira os gráficos de atividade da sua API em Endpoints > Serviço no console do Google Cloud.
Ver gráficos de atividades do Endpoints
Pode levar alguns instantes até a solicitação aparecer nos gráficos.
Verifique os registros de solicitações da API na página "Visualizador de registros". Ver registros de solicitações do Endpoints
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 que você pode usar para interagir com a API de amostra. Para saber mais, consulte a Visão geral do Portal do Cloud Endpoints.
Limpar
Para evitar cobranças na conta do Google Cloud pelos recursos usados nesta página, siga estas etapas.
Consulte Como excluir uma API e as instâncias relacionadas para mais informações sobre como interromper os serviços usados neste tutorial.