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

  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:

    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:

Name Title 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
gcloud services enable
gcloud services enable

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 \

      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.
    type: google.api.Service
    config_version: 3
    name: "*"
    title: API Gateway + Cloud Run gRPC
      - name: endpoints.examples.bookstore.Bookstore
      # ListShelves methods can be called without an API Key.
      - selector: endpoints.examples.bookstore.Bookstore.ListShelves
        allow_unregistered_calls: true
        - selector: "*"
          address: grpcs://
    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 * where PROJECT_ID is the name of your Google Cloud project ID.

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

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

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.

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:

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

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