Getting started with API Gateway and Cloud Run for gRPC
This page shows you how to set up API Gateway to manage and secure a Cloud Run backend service with gRPC.
Use the following task list as you work through the tutorial. All tasks are required to deploy an API Gateway for your Cloud Run backend service with gRPC.
- Create or select a Google Cloud project.
- If you haven't deployed your own Cloud Run, deploy a sample backend gRPC service. See step 7 in Before you begin.
- Enable the required API Gateway services.
- Create a gRPC API configuration document that describes your API, and configures the routes to your Cloud Run. See Configuring an API config with gRPC.
- Deploy an API Gateway using your API config. See Deploying an API Gateway.
- Test your API deployment by sending a request. 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
In the Google Cloud console, go to the Dashboard page and select or create a Google Cloud 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 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 PROJECT_NUMBER.
Download and install the Google Cloud CLI.
Follow the steps in the gRPC Python quickstart to install gRPC and the gRPC tools.
Deploy the python-grpc-bookstore-server example backend 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
Make a note of the service URL, as well as the region and project ID where your service is deployed.
Enabling required services
API Gateway requires that you enable the following Google services:
||API Gateway API|
||Service Management API|
||Service Control API|
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 apigateway.googleapis.com
gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com
For more information about the
gcloud services, see
Creating an API config with gRPC
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: "*.apigateway.PROJECT_ID.cloud.goog" title: API Gateway + 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, a service named
*.apigateway.PROJECT_ID.cloud.googwhere PROJECT_ID is the name of your Google Cloud project ID.
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 backend 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 backend service created in Before you begin. If necessary, replace this value with the URL of your Cloud Run service.
- Save your gRPC API configuration document.
- Create the API config:
gcloud api-gateway api-configs create CONFIG_ID \ --api=API_ID --project=PROJECT_ID \ --grpc-files=api_descriptor.pb,api_config.yamlwhere:
- CONFIG_ID specifies the name of your API config.
- API_ID specifies the name of your API.
- PROJECT_ID specifies the name of your Google Cloud project.
gcloud api-gateway api-configs create grpc-config \ --api=grpc-test --project=my-test-project \ --grpc-files=api_descriptor.pb,api_config.yaml
Deploying an API Gateway
To deploy the gRPC API config to a gateway, run the following command:
gcloud api-gateway gateways create GATEWAY_ID \ --api=API_ID --api-config=CONFIG_ID \ --location=GCP_REGION --project=PROJECT_ID
- GATEWAY_ID specifies the name of the gateway.
- API_ID specifies the name of the API Gateway API associated with this gateway.
- CONFIG_ID specifies the name of the API config deployed to the gateway.
GCP_REGION is the Google Cloud region for the deployed gateway.
PROJECT_ID specifies the name of your Google Cloud project.
gcloud api-gateway gateways create bookstore-grpc \ --api=grpc-test --api-config=grpc-config \ --location=us-central1 --project=my-project
On successful completion, you can use the following command to view details about the gateway:
gcloud api-gateway gateways describe GATEWAY_ID \ --location=GCP_REGION --project=PROJECT_ID
Note the value of the
defaultHostname property in the output of this command. This is the hostname portion of the gateway URL you use to test your deployment in the next step.
Sending a request 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=DEFAULT_HOSTNAME --port 443 --use_tls true
defaultHostnameproperty of your gateway in DEFAULT_HOSTNAME, without the protocol identifier. For example:
python3 bookstore_client.py --host=my-gateway-a12bcd345e67f89g0h.uc.gateway.dev --port 443 --use_tls true
Tracking API activity
View the activity graphs for your API on the API Gateway page in the Google Cloud console. Click on your API to view its activity graphs on the Overview page. It may take a few moments for the requests to be reflected in the graphs.
Look at the request logs for your API on the Logs Explorer page. A link to the Logs Explorer page can be found on the API Gateway page in the Google Cloud console.
- Select the API to view.
- Click the Details tab.
- Click the link under Logs.
You just deployed and tested an API in API Gateway with gRPC!
To avoid incurring charges to your Google Cloud account for the resources used in this quickstart, you can:
Alternatively, you can also delete the Google Cloud project used for this tutorial.