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.

Task List

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.

1. Create or select a Google Cloud project.
2. If you haven't deployed your own Cloud Run, deploy a sample backend gRPC service. See step 7 in Before you begin.
3. Enable the required API Gateway services.
4. 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.
5. Deploy an API Gateway using your API config. See Deploying an API Gateway.
6. Test your API deployment by sending a request. See Sending a request to the API.
7. Track activity to your services. See Tracking API activity.
8. Avoid incurring charges to your Google Cloud account. See Clean up.

Before you begin

1. In the Google Cloud console, go to the Dashboard page and select or create a Google Cloud project.

   Go to the Dashboard page

   Note: If you don't plan to keep the resources you create in this tutorial, create a new project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

2. Make sure that billing is enabled for your project.

   Learn how to enable billing

3. 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.

4. 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.

5. Download and install the Google Cloud CLI.

   Download the gcloud CLI

6. Follow the steps in the gRPC Python quickstart to install gRPC and the gRPC tools.

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

   gcr.io/endpointsv2/python-grpc-bookstore-server:2

   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 gcr.io/endpointsv2/python-grpc-bookstore-server:2

   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:

Name	Title
apigateway.googleapis.com	API Gateway API
servicemanagement.googleapis.com	Service Management API
servicecontrol.googleapis.com	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 gcloud services.

Creating an API config with gRPC

The bookstore-grpc sample contains the files that you need to copy locally and configure.

1. Create a self-contained protobuf descriptor file from your service .proto file:
   1. Save a copy of bookstore.proto from the example repository to your current working directory. This file defines the Bookstore service's API.
   2. Create the following directory under your working directory: mkdir generated_pb2
   3. Create the descriptor file, api_descriptor.pb, by using the protoc protocol buffers compiler. Run the following command in the directory where you saved bookstore.proto:

      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_path is set to the current working directory. In your gRPC build environment, if you use a different directory for .proto input files, change --proto_path so the compiler searches the directory where you saved bookstore.proto.

2. Create a text file called api_config.yaml in 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.app
   

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

3. In the name field, a service named *.apigateway.PROJECT_ID.cloud.goog where PROJECT_ID is the name of your Google Cloud project ID.

4. In the address field in the backend.rules section, 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.

   Note: To use gRPC with TLS on Cloud Run, the address field must have the scheme grpcs:// instead of https://.

   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.

5. Save your gRPC API configuration document.
6. 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.yaml

   where:
   • 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.
   For example:

   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

where:

• 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.

  Note: Allowed values are:

  • asia-northeast1
  • australia-southeast1
  • europe-west1
  • europe-west2
  • us-east1
  • us-east4
  • us-central1
  • us-west2
  • us-west3
  • us-west4

  Support for API Gateway gateways previously created in asia-east1 will end on November 1, 2022. You should review any gateways currently running in asia-east1 and delete or recreate them in a new location as needed.

• PROJECT_ID specifies the name of your Google Cloud project.

For example:

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.

For example:

https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev

Sending a request to the API

To send requests to the sample API, you can use a sample gRPC client written in Python.

1. Clone the git repo where the gRPC client code is hosted:

   git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git

2. Change your working directory:

   cd python-docs-samples/endpoints/bookstore-grpc/

3. Install dependencies:

   pip3 install virtualenv
   virtualenv env
   source env/bin/activate
   pip3 install -r requirements.txt

4. Send a request to the sample API:

   python3 bookstore_client.py --host=DEFAULT_HOSTNAME --port 443 --use_tls true

   Specify the defaultHostname property 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

1. 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.

2. 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.

   Go to the API Gateway page

   Once on the API Gateway page:
   1. Select the API to view.
   2. Click the Details tab.
   3. Click the link under Logs.

You just deployed and tested an API in API Gateway with gRPC!

Clean up

To avoid incurring charges to your Google Cloud account for the resources used in this quickstart, you can:

• Delete your gateways
• Delete your API

Alternatively, you can also delete the Google Cloud project used for this tutorial.