Primeiros passos com Endpoints para Cloud Run para Anthos

Nesta página, mostramos como configurar o Cloud Endpoints para o Cloud Run for Anthos. O Endpoints usa o Extensible Service Proxy V2 Beta (ESPv2 Beta) como um gateway de API (link em inglês). Para fornecer gerenciamento de API para o Cloud Run para Anthos, implante o contêiner pré-construído ESPv2 Beta no Cloud Run for Anthos em execução em um cluster do GKE.

Com essa configuração, o ESPv2 Beta 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 Beta.

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.

  1. Crie um projeto do Google Cloud e, se você não tiver implantado seu próprio Cloud Run for Anthos, implante um serviço de amostra. Consulte Antes de começar.

  2. Crie um cluster do GKE com o Cloud Run for Anthos ativado.

  3. Implante uma amostra do serviço do Cloud Run for Anthos.

  4. Crie um documento do OpenAPI que descreva sua API e configure as rotas para o serviço do Cloud Run for Anthos. Consulte Como configurar o Endpoints.

  5. Implante o documento do OpenAPI para criar um serviço gerenciado. Consulte Como implantar a configuração do Endpoints.

  6. Crie uma nova imagem do Docker do ESPv2 Beta com a configuração do serviço do Endpoints. Consulte Como criar uma nova imagem do ESPv2 Beta.

  7. Implante a nova imagem ESPv2 Beta do Cloud Run for Anthos. Consulte Como implantar a imagem ESPv2 Beta do Cloud Run.

  8. Crie um mapeamento de domínio para o serviço ESPv2 Beta do Cloud Run for Anthos.

  9. Teste sua configuração Como enviar uma solicitação para a API.

  10. Rastrear a atividade para seus serviços. Consulte Como rastrear a atividade da API.

  11. Limpeza.

Antes de começar

  1. Faça login na sua conta do Google.

    Se você ainda não tiver uma, inscreva-se.

  2. No Console do Cloud, na página de seletor de projetos, selecione ou crie um projeto do Cloud.

    Acessar a página do seletor de projetos

  3. Verifique se a cobrança está ativada para o seu projeto do Google Cloud. Saiba como confirmar se a cobrança está ativada para o seu projeto.

  4. 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.
  5. Faça o download e instale o Google Cloud SDK.
  6. 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 linha de comando gcloud do Cloud Run for Anthos para Anthos:

  1. Verifique se o SDK do Cloud tem autorização para acessar seus dados e serviços:

    1. Faça login.

      gcloud auth login

    2. Na nova guia do navegador que é aberta, escolha uma conta que tenha o papel Editor ou Proprietário no projeto do Google Cloud que você criou para implantar o ESPv2 Beta no Cloud Run for Anthos.

  2. Atualize os componentes gcloud instalados:

    gcloud components update
  3. Defina a plataforma como gke e defina a configuração de projeto padrão para gcloud 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 código do projeto que você criou.

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

  5. 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 o Cloud Run for Anthos ativado

Para criar um cluster e ativá-lo no Cloud Run para Anthos no Google Cloud:

  1. 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 o CLUSTER_NAME pelo nome que você quer para o cluster.

    Essas instruções não permitem que o escalonamento automático de clusters redimensione clusters para demanda, mas o Cloud Run for Anthos no Google Cloud escalona automaticamente as instâncias no cluster.

  2. 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 ou 1.14.10-gke.27. Anote a versão do cluster para uso posterior neste documento.

  3. Defina os padrões gcloud para usar o novo cluster e o local do cluster para evitar a necessidade de especificá-los ao usar a linha de comando 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 buscar credenciais para o cluster:

    gcloud container clusters get-credentials CLUSTER_NAME

Como implantar uma amostra de um contêiner do Cloud Run for Anthos

Para implantar o contêiner de amostra "hello" do Cloud Run for Anthos no cluster que você acabou de criar:

  1. Acessar o Cloud Run

  2. Clique em Criar serviço.

  3. Selecione Cloud Run for Anthos como sua plataforma de desenvolvimento.

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

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

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

  7. Clique em Avançar para acessar a segunda página do formulário de criação de serviço:

  8. Especifique gcr.io/cloudrun/hello como o URL da imagem do contêiner.

  9. Clique em Criar para implantar a imagem no Cloud Run for Anthos 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.

  10. 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:

    Tela de revisões.

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

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 Beta 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 do Cloud Run for Anthos. 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:

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

  1. Crie um arquivo de texto chamado openapi-run-anthos.yaml.

  2. Seu serviço de back-end do Cloud Run for Anthos é definido na parte superior do arquivo openapi-run-anthos.yaml, em uma definição de x-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 de info.

  3. No campo host, especifique o nome de domínio da API Endpoints usada para acessar o serviço do Cloud Run for Anthos, no formato:

    API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog

    Exemplo:

    hello-api.endpoints.ESP_PROJECT_ID.cloud.goog
  4. A extensão x-google-endpoints registra uma entrada DNS para o serviço do Endpoints no domínio cloud.goog, no formato:

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

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

    1. Acesse a página do Google Kubernetes Engine no Console do Cloud:

      Acessar o Google Kubernetes Engine

    2. Clique em Serviços e entrada no painel de navegação esquerdo para exibir 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, role para baixo até o serviço istio-ingress. Para todas as outras versões do cluster, role para baixo até o serviço istio-ingressgateway.

    4. Copie o endereço IP externo mostrado ao lado da configuração do Balanceador de carga, sem a porta, se houver. Por exemplo, se o IP for XX.XXX.XX.XXX:15020, omitir o :15020. Ignore os outros endereços IP listados.

  5. No campo address na seção x-google-backend, especifique o nome DNS interno do serviço "hello" do Cloud Run for Anthos e desative a autenticação nesse serviço. Isso é necessário porque a chamada do ESPv2 Beta para o serviço Cloud Run for Anthos é feita como uma chamada interna do cluster e, portanto, a autenticação não é necessária.

  6. Anote o valor da propriedade title no arquivo openapi-run-anthos.yaml:

    title: Cloud Endpoints + Cloud Run 
  7. O valor da propriedade title se tornará o nome do serviço do Endpoints depois que você implantar a configuração.

  8. 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 o Service Management para criar um serviço gerenciado.

Para implantar a configuração do Endpoints:

  1. Verifique se você está no diretório que contém o documento do OpenAPI.

  2. 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 arquivo openapi-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, será exibida uma mensagem parecida com esta:

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

    CONFIG_ID é o ID de configuração exclusivo do serviço do Endpoints criado pela implantação. Exemplo:

    Service Configuration [2019-02-01-r0] 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 ver a configuração do serviço e o histórico de implantação na página Endpoints > Serviços do Console do 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.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 ENDPOINTS_SERVICE_NAME, você pode:

  • Após implantar a configuração do Endpoints, acesse a página Pontos de extremidade no Console do Cloud. A lista de ENDPOINTS_SERVICE_NAME possíveis é mostrada na coluna Nome do serviço.

  • Para OpenAPI, o ENDPOINTS_SERVICE_NAME é o que você especificou no campo host da sua especificação do OpenAPI. Para gRPC, a ENDPOINTS_SERVICE_NAME é o que você especificou no campo name de sua configuração do gRPC Endpoints.

Para mais informações sobre os comandos gcloud, consulte serviços gcloud.

Como criar uma nova imagem ESPv2 Beta do Cloud Run for Anthos

Crie a configuração do serviço do Endpoints em uma nova imagem docker do ESPv2 Beta Depois de criar essa imagem, implante-a no cluster.

Para criar a configuração do serviço em uma nova imagem docker do ESPv2 Beta:

  1. Faça o download deste script em sua máquina local em que o SDK da gcloud está instalado 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 Beta e fazer upload da nova imagem para o registro de contêiner do projeto localizado aqui:

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

Como implantar a imagem ESPv2 Beta do Cloud Run for Anthos

Implante a imagem de serviço Beta do Cloud Run for Anthos no cluster:

  1. Implante o serviço ESPv2 Beta do Cloud Run for Anthos com a nova imagem:

    gcloud run deploy ESP_V2_SERVICE_NAME \
      --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless: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 Beta. Neste exemplo, defina ESP_V2_SERVICE_NAME como espv2.

  2. Se você quiser configurar o Endpoints para usar opções adicionais de inicialização do ESPv2 Beta, como ativar o CORS, por exemplo, 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: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 Beta.

O serviço ESPv2 Beta é 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 Beta na tela Revisões do serviço ESPv2 Beta do Cloud Run for Anthos implantado.

Agora é possível fazer chamadas de API para o serviço do Endpoints por meio do serviço ESPv2 Beta. 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ê configurará um mapa de domínio para facilitar a chamada para o serviço do Endpoint por meio do ESPv2 Beta.

Como criar um mapeamento de domínio para o serviço ESPv2 Beta do Cloud Run for Anthos

Para omitir o cabeçalho host ao fazer uma solicitação, adicione um mapeamento de domínio para o serviço ESPv2 Beta:

  1. Acessar o Cloud Run

  2. Selecione Gerenciar domínios personalizados.

  3. Selecione Adicionar mapeamento.

  4. No menu suspenso, 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 serviço ESPv2 Beta.

  6. No campo Entrar no nome de domínio, especifique o nome de domínio que você quer usar para acessar o serviço do Cloud Run for Anthos por meio do Endpoints. Por exemplo, especifique

    API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog

    Em que API_NAME é o nome da API Endpoints. Neste exemplo, você pode usar "hello-api":

    hello-api.endpoints.ESP_PROJECT_ID.cloud.goog

  7. Clique em Continuar. Um resumo do mapeamento é exibido.

  8. 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 Cloud Run for Anthos no Google Cloud. Portanto, neste exemplo, ao acessar a API Endpoints por meio do ESPv2 Beta, você faz a chamada usando HTTP.

Você pode configurar o ESPv2 Beta para oferecer suporte a solicitações usando HTTPS. Observe que você configura a compatibilidade com HTTPS no ESPv2 Beta, o serviço externo, não no "hello", o serviço de back-end interno.

Para oferecer suporte a HTTPS com o ESPv2 Beta, você precisa:

  1. Tenha um domínio. Se você não tiver um domínio, poderá conseguir um do Google ou de outro fornecedor de domínio.

  2. Crie um mapeamento de domínio para o serviço ESPv2 Beta e atualize o registro DNS seguindo as instruções na página de mapeamento de domínios.

    Se você recebeu seu domínio do Google Domains, use-o como seu servidor DNS. Caso contrário, use Cloud DNS ou um servidor DNS de sua escolha. Usar um domínio do Google Domains é a opção mais fácil.

  3. Na especificação OpenAPI do Endpoints:

    1. Defina o campo host para se referir ao seu domínio em vez de *.cloud.goog.

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

Como rastrear atividade da API

  1. Veja os gráficos de atividade para sua API na página Endpoints > Serviço no Console do Cloud.

    Ver gráficos de atividades 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 "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 para interagir com a API de amostra. Para saber mais, consulte a Visão geral do Portal do Cloud Endpoints.

Limpeza

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados neste guia de início rápido, 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.

A seguir