Set up Cloud Endpoints OpenAPI for Cloud Run with ESPv2

OpenAPI | gRPC

This page shows you how to set up Cloud Endpoints for Cloud Run. Endpoints uses the Extensible Service Proxy V2 (ESPv2) as an API gateway. To provide API management for Cloud Run, you deploy the prebuilt ESPv2 container to Cloud Run. You then secure your services by using Cloud Run IAM so that ESPv2 can invoke them.

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

Endpoints architecture

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

Migrating to ESPv2

Previous releases of Cloud 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 to complete this tutorial.

Create a Google Cloud project, and if you haven't deployed your own Cloud Run, deploy a sample backend service. See Before you begin.
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 Cloud Run. 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 a service. See Sending a request to the API.
Track activity to your services. 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 ESP_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 ESP_PROJECT_NUMBER.
Download and install the Google Cloud CLI.
Download the gcloud CLI
If you haven't deployed your own Cloud Run backend service, follow the steps in Quickstart: Deploy a Prebuilt Sample Container to select or create a Google Cloud project and deploy a sample backend. Make a note of the region and project ID where your service is deployed. On the rest of this page, this project ID is referred to as BACKEND_PROJECT_ID. The name of the deployed service is referred to as BACKEND_SERVICE_NAME.

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. Later, you will deploy the ESPv2 container onto the same 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 CLOUD_RUN_SERVICE_NAME with the name that you want to use for the service.

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

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

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

For example, if you set 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, https://gateway-12345-uc.a.run.app is the CLOUD_RUN_SERVICE_URL and gateway-12345-uc.a.run.app is the CLOUD_RUN_HOSTNAME.

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

Configuring Endpoints

You must have an OpenAPI document based on OpenAPI Specification v2.0 that describes the surface of your backend service and any authentication requirements. You also need to add a Google-specific field that contains the URL for each service so that ESPv2 has the information it needs to invoke a service. If you are new to OpenAPI, see OpenAPI overview for more information

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

Your Cloud Run backend service is defined at the top of the openapi-run.yaml file, in an x-google-backend definition. For example:

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: CLOUD_RUN_HOSTNAME
schemes:
  - https
produces:
  - application/json
x-google-backend:
  address: BACKEND_SERVICE_NAME
  protocol: h2
paths:
  /hello:
    get:
      summary: Greet a user
      operationId: hello
      responses:
        '200':
          description: A successful response
          schema:
            type: string

Indentation is important for yaml format. For example the host field must be at the same level as info.

In the address field in the x-google-backend section, replace BACKEND_SERVICE_NAME with the actual URL of your backend Cloud Run service, created in Step 6 of Before you Begin.

This example assumes that you are using the hello backend service created in Quickstart: Deploy a Prebuilt Sample Container. If you are using a different backend Cloud Run service, replace BACKEND_SERVICE_NAME with the URL of your Cloud Run service.
In the host field, specify CLOUD_RUN_HOSTNAME, the hostname portion of the URL that was reserved above in Reserving a Cloud Run hostname. Don't include the protocol identifier, https://. For example:
```
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: gateway-12345-uc.a.run.app
```
Note the value of the title property in the openapi-run.yaml file:
```
title: Cloud Endpoints + Cloud Run
```
The value of the title property becomes the name of the Endpoints service after you deploy the configuration.
Save your OpenAPI document.

For information about the fields in the OpenAPI document that Endpoints requires, see Configuring Endpoints.

Deploying the Endpoints configuration

To deploy the Endpoints configuration, you use the gcloud endpoints services deploy command. This command uses Service Management to create a managed service.

To deploy the Endpoints configuration:

Make sure you are in the directory that contains your OpenAPI document.
Upload the configuration and create a managed service.
```
gcloud endpoints services deploy openapi-run.yaml \
  --project ESP_PROJECT_ID
```
This creates a new Endpoints service with the name that you specified in the host field of the openapi-run.yaml file. The service is configured according to your OpenAPI document.

As it is creating and configuring the service, Service Management outputs information to the terminal. When the deployment completes, a message similar to the following is displayed:
```
Service Configuration [CONFIG_ID] uploaded for service [CLOUD_RUN_HOSTNAME]
```
CONFIG_ID is the unique Endpoints service configuration ID created by the deployment. For example:
```
Service Configuration [2019-02-01r0] uploaded for service [gateway-12345-uc.a.run.app]
```
The service configuration ID consists of a date stamp followed by a revision number. If you deploy openapi-run.yaml again on the same day, the revision number is incremented in the service configuration ID. You can view the service configuration and the deployment history on the Endpoints > Services page in the Google Cloud console.

If you get an error message, see Troubleshooting Endpoints configuration deployment.

Checking required services

At a minimum, Endpoints and ESP require the following Google services to be enabled:

Name	Title
`servicemanagement.googleapis.com`	Service Management API
`servicecontrol.googleapis.com`	Service Control API

In most cases, the gcloud endpoints services deploy command enables these required services. However, the gcloud command completes successfully but doesn't enable the required services in the following circumstances:

If you used a third-party application such as Terraform, and you don't include these services.
You deployed the Endpoints configuration to an existing Google Cloud project in which these services were explicitly disabled.

Use the following command to confirm that the required services are enabled:

gcloud services list

If you do not see the required services listed, enable them:

gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

Also enable your Endpoints service:

gcloud services enable ENDPOINTS_SERVICE_NAME

To determine the ENDPOINTS_SERVICE_NAME you can either:

After deploying the Endpoints configuration, go to the Endpoints page in the Cloud console. The list of possible ENDPOINTS_SERVICE_NAME are shown under the Service name column.
For OpenAPI, the ENDPOINTS_SERVICE_NAME is what you specified in the host field of your OpenAPI spec. For gRPC, the ENDPOINTS_SERVICE_NAME is what you specified in the name field of your gRPC Endpoints configuration.

For more information about the gcloud commands, see gcloud services.

Building a new ESPv2 image

Build the Endpoints service config into a new ESPv2 docker image. You will later deploy this image onto the reserved Cloud Run service.

Note:

This step is required.

The service config must be built into a new docker image because Cloud Run is a scale-to-zero service. That means when there is no traffic, all instances are deleted. When traffic increases, new instances are created on-demand. This type of service instance creation is also called cold start. See the Cloud Run Concurrency documentation for more.

If the docker image did not have the service config built into it, Cloud Run would have to make two API calls to Google ServiceManagement at cold start. These calls count against your Google ServiceManagement API quota.

By building the service config into the ESPv2 docker image, you remove the two API calls and avoid impacting the quota count for the Google ServiceManagement service. This step also speeds up the new service instance creation and reduces the latency for the requests waiting for the new instance.

You must re-run this entire step and redeploy the new container:

Every time you modify and redeploy the Endpoints service configuration. Otherwise, changes to the service configuration will not be propagated to ESPv2.
When a new version of ESPv2 is released. Otherwise, the older version of ESPv2 will remain deployed.

To build the service config into a new ESPv2 docker image:

Download this script to your local machine where the gcloud CLI is installed.

Note:
This script requires bash. If you are not using macOS/Linux, you can run it on Cloud Shell, Compute Engine, or Windows Subsystem for Linux.

Run the script with the following command:

chmod +x gcloud_build_image

./gcloud_build_image -s CLOUD_RUN_HOSTNAME \
    -c CONFIG_ID -p ESP_PROJECT_ID

For CLOUD_RUN_HOSTNAME, specify the hostname of the URL that you reserved above in Reserving a Cloud Run hostname. Don't include the protocol identifier, https://.

For example:

chmod +x gcloud_build_image

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

The script uses the gcloud command to download the service config, build the service config into a new ESPv2 image, and upload the new image to your project container registry. The script automatically uses the latest release of ESPv2, denoted by the ESP_VERSION in the output image name. The output image is uploaded to:
```
gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID
```
For example:
```
gcr.io/your-project-id/endpoints-runtime-serverless:2.14.0-gateway-12345-uc.a.run.app-2019-02-01r0"
```
Note:
Pass the -z flag to the script to generate the image in a different registry location.

For example, to push the generated ESPv2 image to a Euopean Union data center, pass -z eu to the script.

Deploying the ESPv2 container

Deploy the ESPv2 Cloud Run service with the new image you built above. Replace CLOUD_RUN_SERVICE_NAME with the same Cloud Run service name you used when you originally reserved the hostname above in Reserving a Cloud Run hostname:
```
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
```
Note:
If you want ESPv2 to manage access, use the --allow-unauthenticated flag to ensure that ESPv2 verifies the JWT token. If the flag is not used, the JWT token is intercepted and verified by Cloud Run access control IAM server. Since the IAM and ESPv2 use the same Authorization header, they don't work together, make sure only use one of them. Recommend to use IAM instead of ESPv2 for managing access.
If you want to configure Endpoints to use additional ESPv2 startup options, such as enabling CORS, you can pass the arguments in the ESPv2_ARGS environment variable:
```
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
```
For more information and examples on setting the ESPv2_ARGS environment variable, including the list of available options and information on how to specify multiple options, see Extensible Service Proxy V2 flags.
Grant ESPv2 permission to call Service Management and Service Control.

In the Google Cloud console, go to the Cloud Run page.

Go to the Cloud Run page

You can see the Cloud Run instance you deployed and the service account associated with it.
Grant required permissions to the service account:

gcloud projects add-iam-policy-binding PROJECT_NAME \
       --member "serviceAccount:SERVICE_ACCOUNT" \
       --role roles/servicemanagement.serviceController

What are roles and permissions?

Grant ESPv2 permission to invoke your Cloud Run services. Run the following command for each service. In the following command:
Note:
This step is not needed if ESPv2 Cloud Run service is deployed without using the flag --service-account and the backend service BACKEND_SERVICE_NAME is deployed in the ESP_PROJECT_NUMBER project.
- Replace BACKEND_SERVICE_NAME with the name of the Cloud Run service being invoked. If you are using the backend service created in the Quickstart: Deploy a Prebuilt Sample Container, then use hello as this value.
- Replace ESP_PROJECT_NUMBER with the project number of the project that you created for ESPv2. One way to find this is to go to the IAM page in the Google Cloud console and find the Default compute service account, which is the service account used in the `member` flag.
```
gcloud run services add-iam-policy-binding BACKEND_SERVICE_NAME \
  --member "serviceAccount:ESP_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
  --role "roles/run.invoker" \
  --platform managed \
  --project BACKEND_PROJECT_ID
```

For more information, see Managing access using IAM.

Sending requests to the API

This section shows how to send requests to your API.

Create an environment variable for your Endpoints service name. This is the name that you specified in the host field of your OpenAPI document. For example:
- Linux or macOS:
  
  export ENDPOINTS_HOST=gateway-12345-uc.a.run.app
- Windows PowerShell:
  
  $Env: ENDPOINTS_HOST="gateway-12345-uc.a.run.app"

Linux or Mac OS

Use curl to send an HTTP request by using the ENDPOINTS_HOST environment variable you set in the previous step.

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

PowerShell

Use Invoke-WebRequest to send an HTTP request by using the ENDPOINTS_HOST environment variable you set in the previous step.

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

In the previous example, the first two lines end in a backtick. When you paste the example into PowerShell, make sure there isn't a space following the backticks. For information about the options used in the example request, see Invoke-WebRequest in the Microsoft documentation.

Third-party app

You can use a third-party application such as the Chrome browser extension Postman request.

Select GET as the HTTP verb.
For the header, select the key content-type and the value application/json.
Use the actual URL instead of the environment variable, for example:
```
https://gateway-12345-uc.a.run.app/hello
```

If you didn't get a successful response, see Troubleshooting Response Errors.

You just deployed and tested an API in Endpoints!

Tracking API activity

View the activity graphs for your API on the Endpoints > Service page in the Google Cloud console.

View Endpoints activity graphs

It may take a few moments for the request to be reflected in the graphs.
Look at the request logs for your API on the Logs Explorer page. View Endpoints request logs

Creating a developer portal for the API

You can use Cloud Endpoints Portal to create a developer portal, a website that you can use to interact with the sample API. To learn more, see Cloud Endpoints Portal Overview.

Clean up

To avoid incurring charges to your Google Cloud account for the resources used on this page, follow these steps.

See Deleting an API and API instances for information on stopping the services used by this tutorial.