Configurar o Cloud Endpoints OpenAPI para o ambiente padrão com o ESPv2

Configurar o IAP para proteger o aplicativo

Para proteger seu aplicativo do App Engine, você precisa usar o Identity Aware Proxy (IAP) para garantir que as solicitações sejam autenticadas.

Siga as etapas para Ativar o IAP e verifique se você consegue fazer login no seu aplicativo.

Além disso, ao configurar o cliente OAuth, anote o client_id do OAuth, que é chamado de IAP_CLIENT_ID neste tutorial.

Como reservar um nome de host do Cloud Run

É preciso reservar um nome do host do Cloud Run para o serviço ESPv2 para configurar o documento da OpenAPI ou a configuração do serviço gRPC. Para reservar um nome do host, você implantará um contêiner de amostra no Cloud Run. Posteriormente, você implantará o contêiner do ESPv2 no mesmo serviço do Cloud Run.

1. Verifique se a CLI gcloud está autorizada a 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 Google Cloud que você criou para implantar o ESPv2 no Cloud Run.
2. Defina a região.

   gcloud config set run/region us-central1

3. Implantar a imagem de amostra gcr.io/cloudrun/hello no Cloud Run. Substitua CLOUD_RUN_SERVICE_NAME pelo nome do serviço que você quer usar.

   gcloud run deploy CLOUD_RUN_SERVICE_NAME \
       --image="gcr.io/cloudrun/hello" \
       --allow-unauthenticated \
       --platform managed \
       --project=ESP_PROJECT_ID
   

   Após a conclusão, o comando exibirá uma mensagem semelhante à seguinte:

   Service [CLOUD_RUN_SERVICE_NAME] revision [CLOUD_RUN_SERVICE_NAME-REVISION_NUM] has been deployed and is serving traffic at CLOUD_RUN_SERVICE_URL

   Por exemplo, se você definir CLOUD_RUN_SERVICE_NAME para gateway:

   Service [gateway] revision [gateway-00001] has been deployed and is serving traffic at https://gateway-12345-uc.a.run.app

   Neste exemplo, https://gateway-12345-uc.a.run.app é o CLOUD_RUN_SERVICE_URL e gateway-12345-uc.a.run.app é o CLOUD_RUN_HOSTNAME.

4. Anote CLOUD_RUN_SERVICE_NAME e CLOUD_RUN_HOSTNAME. Depois, implante o ESPv2 no serviço CLOUD_RUN_SERVICE_NAME do Cloud Run. Especifique CLOUD_RUN_HOSTNAME no campo host do documento da OpenAPI.

Como configurar o Endpoints

É necessário ter um documento OpenAPI baseado na Especificação OpenAPI v2.0 que descreva a superfície de seus aplicativos e quaisquer requisitos de autenticação. Também é preciso adicionar um campo específico do Google que contenha o URL de cada aplicativo para que o ESPv2 tenha as informações necessárias para invocar um aplicativo. Se você é novo na OpenAPI, consulte a visão geral da OpenAPI para ver mais informações.

1. Crie um arquivo de texto chamado openapi-appengine.yaml. Por conveniência, esta página refere-se ao documento do OpenAPI por esse nome de arquivo, mas é possível usar outro nome se você preferir.
2. Seu aplicativo de back-end do App Engine é definido na parte superior do arquivo openapi-appengine.yaml, em uma definição de x-google-backend. Exemplo:

     swagger: '2.0'
     info:
       title: Cloud Endpoints + App Engine
       description: Sample API on Cloud Endpoints with an App Engine backend
       version: 1.0.0
     host: CLOUD_RUN_HOSTNAME
     schemes:
       - https
     produces:
       - application/json
     x-google-backend:
       address: https://APP_PROJECT_ID.REGION.r.appspot.com
       jwt_audience: IAP_CLIENT_ID
       protocol: h2
     paths:
       /:
         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 address na seção x-google-backend, substitua APP_PROJECT_ID pelo ID do projetoGoogle Cloud , REGION pela região Google Cloud onde você implantou o App Engine e IAP_CLIENT_ID pelo ID do cliente OAuth que você criou ao configurar o IAP.

4. No campo host, especifique CLOUD_RUN_HOSTNAME, a parte do nome do host do URL que foi reservada acima em Como reservar um nome de host do Cloud Run. Não inclua o identificador de protocolo, https://. Exemplo:

   swagger: '2.0'
     info:
       title: Cloud Endpoints + App Engine
       description: Sample API on Cloud Endpoints with an App Engine backend
       version: 1.0.0
     host: gateway-12345-uc.a.run.app

5. Anote o valor da propriedade title no arquivo openapi-appengine.yaml:

   title: Cloud Endpoints + App Engine

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

6. 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-appengine.yaml \
     --project ESP_PROJECT_ID

   Isso cria um novo serviço do Endpoints com o nome especificado no campo host do arquivo openapi-appengine.yaml. O serviço é configurado de acordo com o documento da OpenAPI.

   Durante a criação e a configuração do serviço, 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 [CLOUD_RUN_HOSTNAME]

   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 [gateway-12345-uc.a.run.app]

   O ID de configuração do serviço consiste em um carimbo de data e um número de revisão. Se você implantar openapi-appengine.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 no Google Cloud console.

   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 doGoogle Cloud atual em que esses serviços foram explicitamente desativados.

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

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 campo name da configuração do gRPC Endpoints.

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

Como criar uma nova imagem do ESPv2

Crie a configuração do serviço do Endpoints em uma nova imagem docker do ESPv2. Em seguida, você implantará essa imagem no serviço reservado do Cloud Run.

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

1. Faça o download deste script em sua máquina local em que a CLI gcloud está instalada.

2. Execute o script com o seguinte comando:

   chmod +x gcloud_build_image
   
   ./gcloud_build_image -s CLOUD_RUN_HOSTNAME \
       -c CONFIG_ID -p ESP_PROJECT_ID

   Para CLOUD_RUN_HOSTNAME, especifique o nome do host do URL que você reservou acima em Como reservar um nome de host do Cloud Run. Não inclua o identificador de protocolo, https://.

   Por exemplo:

   chmod +x gcloud_build_image
   
   ./gcloud_build_image -s gateway-12345-uc.a.run.app \
       -c 2019-02-01r0 -p your-project-id

3. 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 para o registro de contêiner do projeto. O script usa automaticamente a versão mais recente do ESPv2, indicada pela 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-CLOUD_RUN_HOSTNAME-CONFIG_ID

   Exemplo:

   gcr.io/your-project-id/endpoints-runtime-serverless:2.14.0-gateway-12345-uc.a.run.app-2019-02-01r0"

Como implantar o contêiner do ESPv2

1. Implante o serviço do Cloud Run do ESPv2 com a nova imagem que você criou acima. Substitua CLOUD_RUN_SERVICE_NAME pelo mesmo nome de serviço do Cloud Run que você usou quando reservou originalmente o nome do host acima em Como reservar um nome de host do Cloud Run:

   gcloud run deploy CLOUD_RUN_SERVICE_NAME \
     --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \
     --allow-unauthenticated \
     --platform managed \
     --project=ESP_PROJECT_ID

2. Se você quiser configurar o Endpoints para usar opções adicionais de inicialização do ESPv2, como a de ativar o CORS, passe os argumentos na variável de ambiente ESPv2_ARGS:

   gcloud run deploy CLOUD_RUN_SERVICE_NAME \
     --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \
     --set-env-vars=ESPv2_ARGS=--cors_preset=basic \
     --allow-unauthenticated \
     --platform managed \
     --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.

3. Conceda permissão ao ESPv2 para invocar seu app protegido pelo IAP. Execute o seguinte comando para cada serviço. Realize estas etapas no comando a seguir:
   • Substitua APP_PROJECT_ID pelo nome do ID do projeto do App Engine.
   • Substitua ESP_PROJECT_NUMBER pelo número do projeto criado para o ESPv2. Uma maneira de encontrar isso é acessar o Console do IAM e encontrar a conta de serviço padrão do Compute Engine, que é a conta de serviço usada na flag "member".

     gcloud projects add-iam-policy-binding APP_PROJECT_ID \
         --member "serviceAccount:ESP_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
         --role "roles/iap.httpsResourceAccessor"
       

Para mais informações, consulte Como gerenciar o acesso usando o IAM.

Como enviar solicitações à API

Veja nesta seção como enviar solicitações para a API.

1. Crie uma variável de ambiente para o nome do serviço do Endpoints. Este é o nome que você especificou no campo host do documento da OpenAPI. Por exemplo:

   • Linux ou macOS:

     export ENDPOINTS_HOST=gateway-12345-uc.a.run.app

   • Windows PowerShell:

     $Env: ENDPOINTS_HOST="gateway-12345-uc.a.run.app"

curl --request GET \
   --header "content-type:application/json" \
   "https://${ENDPOINTS_HOST}/"

(Invoke-WebRequest -Method GET `
    -Headers @{"content-type"="application/json"} `
    -URI "https://$Env:ENDPOINTS_HOST/").Content

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.

Rastrear a atividade da API

1. Veja os gráficos de atividade para sua API na página 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.

2. Verifique os registros de solicitações da API na página "Visualizador de registros".

   Ver registros de solicitações do Endpoints