This page shows you how to set up Cloud Endpoints for Cloud Run with a gRPC backend. Endpoints uses the Extensible Service Proxy V2 Beta (ESPv2 Beta) as an API gateway. To provide API management for Cloud Run, you deploy the prebuilt ESPv2 Beta container to Cloud Run. You then secure your services by using Cloud Run IAM so that ESPv2 Beta can invoke them.
With this set up, ESPv2 Beta intercepts all requests to your services and performs any necessary checks (such as authentication) before invoking the service. When the service responds, ESPv2 Beta gathers and reports telemetry. You can view metrics for your service on the Endpoints > Services page in the Google Cloud Console.
Migrating to ESPv2 Beta
Previous releases of Cloud Endpoints did not support gRPC on Cloud Run with ESP. Please migrate to Extensible Service Proxy V2 Beta to use this feature.
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 gRPC service. See Before you begin.
- Deploy the ESPv2 Beta container to Cloud Run. See Deploying ESPv2 Beta.
- Create a gRPC API configuration document that describes your API, and configure the routes to your Cloud Run. See Configuring Endpoints.
- Deploy the gRPC API configuration document to create a managed service. See Deploying the Endpoints configuration.
- Build and deploy a new ESPv2 Beta Docker image with your Endpoints service configuration. Then grant ESPv2 Beta the Cloud Identity and Access Management (Cloud IAM) permission to invoke your service. See Building a new ESPv2 Beta image.
- 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.
Before you begin
To get set up:
In the Cloud Console, go to the Manage resources page and create a project.
Make sure that billing is enabled for your project.
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
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
Download and install the Cloud SDK.
Follow the steps in the gRPC Python quickstart to install gRPC and the gRPC tools.
Deploy the python-grpc-bookstore-server example gRPC Cloud Run service for use with this tutorial. The gRPC service uses the following container image:
Follow the steps in Quickstart: Deploy a Prebuilt Sample Container to deploy the service. Make sure to replace the container image specified in that quickstart with
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
Deploying ESPv2 Beta
To deploy the ESPv2 Beta container to Cloud Run:
Make sure that Cloud SDK is authorized to access your data and
- Log in.
gcloud auth login
- 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 Beta to Cloud Run.
- Log in.
Set the region.
gcloud config set run/region us-central1
Deploy ESPv2 Beta to Cloud Run. Replace
CLOUD_RUN_SERVICE_NAMEwith the name that you want to use for the service.
gcloud run deploy CLOUD_RUN_SERVICE_NAME \ --image="gcr.io/endpoints-release/endpoints-runtime-serverless:2" \ --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
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.appis the CLOUD_RUN_SERVICE_URL and
gateway-12345-uc.a.run.appis the CLOUD_RUN_HOSTNAME.
- Make a note of CLOUD_RUN_HOSTNAME. You specify the CLOUD_RUN_HOSTNAME in the
namefield of your gRPC API configuration document (in a later step).
- You can verify that the initial version of ESPv2 Beta is deployed on Cloud Run by visiting the CLOUD_RUN_SERVICE_URL in your web browser. You should see a warning message about a missing environment variable. This warning message is expected, and will appear until the Building a new ESPv2 Beta image step is complete.
- Your Cloud Run service is public on the internet. If you want to add authentication capabilities, we recommend that you use one of the authentication methods supported by Endpoints.
sample contains the files that you need to copy locally and configure.
- Create a self-contained protobuf descriptor file from your service
- Save a copy of
bookstore.protofrom the example repository to your current working directory. This file defines the Bookstore service's API.
- Create the following directory under your working directory:
- Create the descriptor file,
api_descriptor.pb, by using the
protocprotocol buffers compiler. Run the following command in the directory where you saved
python3 -m grpc_tools.protoc \ --include_imports \ --include_source_info \ --proto_path=. \ --descriptor_set_out=api_descriptor.pb \ --python_out=generated_pb2 \ --grpc_python_out=generated_pb2 \ bookstore.proto
In the preceding command,
--proto_pathis set to the current working directory. In your gRPC build environment, if you use a different directory for
.protoinput files, change
--proto_pathso the compiler searches the directory where you saved
- Save a copy of
Create a text file called
api_config.yamlin your current working directory (the same directory that contains
bookstore.proto). For convenience, this page refers to the gRPC API configuration document by that file name, but you can name it something else if you prefer. Add the following contents to the file:
# The configuration schema is defined by the service.proto file. # https://github.com/googleapis/googleapis/blob/master/google/api/service.proto type: google.api.Service config_version: 3 name: CLOUD_RUN_HOSTNAME title: Cloud Endpoints + Cloud Run gRPC apis: - name: endpoints.examples.bookstore.Bookstore usage: rules: # ListShelves methods can be called without an API Key. - selector: endpoints.examples.bookstore.Bookstore.ListShelves allow_unregistered_calls: true backend: rules: - selector: "*" address: grpcs://python-grpc-bookstore-server-HASH-uc.a.run.appIndentation is important for yaml format. For example the
namefield must be at the same level as
namefield, specify the CLOUD_RUN_HOSTNAME, the hostname portion of the URL that Cloud Run created when you deployed ESPv2 Beta above in Deploying ESPv2 Beta. Don't include the protocol identifier,
addressfield in the
backend.rulessection, replace grpcs://python-grpc-bookstore-server-HASH-uc.a.run.app with the actual URL of the python-grpc-bookstore-server example gRPC Cloud Run service, where HASH is the unique hash code generated when you created the service.
This example assumes that you are using the gRPC Bookstore service created in Before you begin. If necessary, replace this value with the URL of your Cloud Run service.
Note the value of the
titleproperty in the
title: Cloud Endpoints + Cloud Run gRPC
The value of the
titleproperty becomes the name of the Endpoints service after you deploy the configuration.
- Save your gRPC API configuration document.
See Configuring Endpoints for more information.
Deploying the Endpoints configuration
- Make sure you are in the directory where the
api_config.yamlfiles are located.
- Confirm that the default project that the
gcloudcommand-line tool is currently using is the Google Cloud project that you want to deploy the Endpoints configuration to. Validate the project ID returned from the following command to make sure that the service doesn't get created in the wrong project.
gcloud config list project
If you need to change the default project, run the following command:
gcloud config set project YOUR_PROJECT_ID
- Deploy the
proto descriptorfile and the configuration file by using the
gcloud endpoints services deploy api_descriptor.pb api_config.yaml
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 [bookstore.endpoints.example-project.cloud.goog]
CONFIG_ID is the unique Endpoints service configuration ID created by the deployment. For example:
Service Configuration [2017-02-13r0] uploaded for service [bookstore.endpoints.example-project.cloud.goog]
In the previous example,
2017-02-13r0is the service configuration ID and
bookstore.endpoints.example-project.cloud.googis the service name. The service configuration ID consists of a date stamp followed by a revision number. If you deploy the Endpoints configuration again on the same day, the revision number is incremented in the service configuration ID.
Checking required servicesAt a minimum, Endpoints and ESP require the following Google services to be enabled:
||Service Management API|
||Service Control API|
||Google Cloud Endpoints|
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
gcloud services enable endpoints.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
hostfield of your OpenAPI spec. For gRPC, the ENDPOINTS_SERVICE_NAME is what you specified in the
namefield of your gRPC Endpoints configuration.
For more information about the
gcloud commands, see
If you get an error message, see Troubleshooting Endpoints configuration deployment.
See Deploying the Endpoints configuration for additional information.
Building a new ESPv2 Beta image
Build the Endpoints service config into a new ESPv2 Beta docker image and redeploy the ESPv2 Beta Cloud Run service with the image. Then grant ESPv2 Beta the Cloud IAM permission to invoke your services.
To build the service config into a new ESPv2 Beta docker image:
Download this script to your local machine where the gcloud SDK is installed and run it as:
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 Cloud Run created when you deployed ESPv2 Beta above in Deploying ESPv2 Beta. Don't include the protocol identifier,
chmod +x gcloud_build_image ./gcloud_build_image -s gateway-12345-uc.a.run.app \ -c 2019-02-01-r0 -p ESP_PROJECT_ID
The script uses the gcloud command to download the service config, build the service config into a new ESPv2 Beta image, and upload the new image to your project container registry located here:
Redeploy the ESPv2 Beta Cloud Run service with the new image. Replace
CLOUD_RUN_SERVICE_NAMEwith the same Cloud Run service name you used when you originally deployed it above in Deploying ESPv2 Beta:
gcloud run deploy CLOUD_RUN_SERVICE_NAME \ --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:CLOUD_RUN_HOSTNAME-CONFIG_ID" \ --allow-unauthenticated \ --platform managed \ --project=ESP_PROJECT_ID
If you want to configure Endpoints to use additional ESPv2 Beta startup options, such as enabling CORS, you can pass the arguments in the
gcloud run deploy CLOUD_RUN_SERVICE_NAME \ --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless: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_ARGSenvironment variable, including the list of available options and information on how to specify multiple options, see Extensible Service Proxy V2 Beta flags.
- Grant ESPv2 Beta permission to invoke your Cloud Run services.
Run the following command for each service. In the following command:
BACKEND_SERVICE_NAMEwith the name of the Cloud Run service being invoked. If you are using the service created by deploying `gcr.io/endpointsv2/python-grpc-bookstore-server:2`, then use
python-grpc-bookstore-serveras this value.
ESP_PROJECT_NUMBERwith the project number of the project that you created for ESPv2 Beta. One way to find this is to go to the IAM 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_NUMBERfirstname.lastname@example.org" \ --role "roles/run.invoker" \ --platform managed \ --project BACKEND_PROJECT_ID
For more information, see Managing Access via Cloud IAM.
Sending requests to the API
To send requests to the sample API, you can use a sample gRPC client written in Python.
Clone the git repo where the gRPC client code is hosted:
git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
Change your working directory:
pip3 install virtualenv
pip3 install -r requirements.txt
Send a request to the sample API:
python3 bookstore_client.py --host CLOUD_RUN_HOSTNAME --port 443 --use_tls true
Specify the hostname of your ESPv2 Beta Cloud Run service in CLOUD_RUN_HOSTNAME, without the protocol identifier. For example:
python3 bookstore_client.py --host espv2-grpc-HASH-uc.a.run.app --port 443 --use_tls true
If you don'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 Cloud Console.
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 Viewer page.
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.
To avoid incurring charges to your Google Cloud account for the resources used in this quickstart, follow these steps.
See Deleting an API and API instances for information on stopping the services used by this tutorial.