Set up Endpoints OpenAPI for standard environment with ESPv2

This page shows you how to set up Cloud Endpoints for App Engine. Endpoints uses the Extensible Service Proxy V2 (ESPv2) as an API gateway. To provide API management for App Engine, you deploy the prebuilt ESPv2 container to Cloud Run. You then secure your app by using Identity Aware Proxy (Identity-Aware Proxy (IAP)) so that only ESPv2 can invoke it.

With this set up, ESPv2 intercepts all requests to your app and performs any necessary checks (such as authentication) before invoking the app. When the app responds, ESPv2 gathers and reports telemetry, as shown in the following figure. You can view metrics for your app on the Endpoints > Services page in the Google Cloud console.

Architecture diagram showing how ESPv2 proxies requests to App Engine.

For an overview of Cloud Endpoints, see About Endpoints and Endpoints architecture.

Migrating to ESPv2

Previous releases of Endpoints supported the use of the Extensible Service Proxy (ESP) with Cloud Run. If you have existing APIs that you want to migrate to ESPv2, see Migrate to Extensible Service Proxy V2 for more.

Task List

Use the following task list as you work through the tutorial. All tasks are required for Endpoints to manage your app.

Create a Google Cloud project, and if you haven't deployed your own App Engine, deploy a sample backend app. See Before you begin.
Configure IAP to secure your app. See Configure IAP.
Reserve a Cloud Run hostname for the ESPv2 service. See Reserving a Cloud Run hostname.
Create an OpenAPI document that describes your API, and configure the routes to your App Engine. See Configuring Endpoints.
Deploy the OpenAPI document to create a managed service. See Deploying the Endpoints configuration.
Build a new ESPv2 Docker image with your Endpoints service configuration. See Building a new ESPv2 image.
Deploy the ESPv2 container onto Cloud Run. Then grant ESPv2 the Identity and Access Management (IAM) permission to invoke your service. See Deploying the ESPv2 container.
Invoke the app. See Sending a request to the API.
Track activity to your apps. See Tracking API activity.
Avoid incurring charges to your Google Cloud account. See Clean up.

Costs

In this document, you use the following billable components of Google Cloud:

To generate a cost estimate based on your projected usage, use the pricing calculator.

New Google Cloud users might be eligible for a free trial.

When you finish the tasks that are described in this document, you can avoid continued billing by deleting the resources that you created. For more information, see Clean up.

Before you begin

To get set up:

In the Google Cloud console, go to the Manage resources page and create a project.
Go to the Manage resources page
Make sure that billing is enabled for your project.
Learn how to enable billing
Make a note of the project ID because it is needed later. On the rest of this page, this project ID is referred to as ESPv2_PROJECT_ID.
Make a note of the project number because it is needed later. On the rest of this page, this project number is referred to as ESPv2_PROJECT_NUMBER.
Download and install the Google Cloud CLI.
Download the gcloud CLI
If you haven't deployed your own backend App Engine, follow the steps in the App Engine Quickstart. Make a note of the region and project ID where your apps are deployed. On the rest of this page, this project ID is referred to as APP_PROJECT_ID.

Configure IAP to secure your app

In order to secure your App Engine app, you must use the Identity Aware Proxy (IAP) to ensure that requests are authenticated.

Follow the steps to Enable IAP, and ensure that you are able to sign in to your application.

Additionally, when configuring the OAuth client, make note of the OAuth client_id, which is referred to as IAP_CLIENT_ID in this tutorial.

Reserving a Cloud Run hostname

You must reserve a Cloud Run hostname for the ESPv2 service in order to configure the OpenAPI document or gRPC service configuration. To reserve a hostname, you will deploy a sample container to Cloud Run, and use a portion of the generated URL as the hostname. Later, you will deploy the ESPv2 container onto the same sample Cloud Run service.

Make sure that gcloud CLI is authorized to access your data and services.
1. Log in.
```
gcloud auth login
```
2. On the new browser tab that opens, choose an account that has the Editor or Owner role in the Google Cloud project that you created for deploying ESPv2 to Cloud Run.

Set the region.

gcloud config set run/region us-central1

Deploy the sample image gcr.io/cloudrun/hello to Cloud Run. Replace ESPv2_CLOUD_RUN_SERVICE_NAME with the name that you want to use for the service.

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

On successful completion, the command displays a message similar to the following:

Service [ESPv2_CLOUD_RUN_SERVICE_NAME] revision [ESPv2_CLOUD_RUN_SERVICE_NAME-REVISION_NUM] has been deployed and is serving traffic at ESPv2_CLOUD_RUN_SERVICE_URL

For example, if you set ESPv2_CLOUD_RUN_SERVICE_NAME to gateway:

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

In this example:

ESPv2_CLOUD_RUN_SERVICE_URL is the service URL https://gateway-12345-uc.a.run.app
ESPv2_CLOUD_RUN_HOSTNAME is the hostname gateway-12345-uc.a.run.app.

Make a note of ESPv2_CLOUD_RUN_SERVICE_NAME and ESPv2_CLOUD_RUN_HOSTNAME. You later deploy ESPv2 onto the ESPv2_CLOUD_RUN_SERVICE_NAME Cloud Run service. You specify ESPv2_CLOUD_RUN_HOSTNAME in the host field of your OpenAPI document.

Configuring Endpoints

You must have an OpenAPI document based on either OpenAPI 2.0 or OpenAPI 3.x that describes the surface of your apps and any authentication requirements. To learn more, see Supported OpenAPI versions.

You also need to add a Google-specific field that contains the URL for each app so that ESPv2 has the information it needs to invoke an app. If you are new to OpenAPI, see OpenAPI overview for more information.

Create a text file called openapi-appengine.yaml. For convenience, this page refers to the OpenAPI document by that filename, but you can name it something else if you prefer.

Your App Engine backend app is defined in the openapi-appengine.yaml file, either in an x-google-backend definition (for OpenAPI 2.0) or an x-google-api-management definition (for OpenAPI 3.x). For example:

OpenAPI 2.0

  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':