How to use Google API Gateway with Cloud Run

Create an API Gateway that interacts with your Cloud Run backend services.

Disclaimer: Opinions expressed are solely my own.


In this article, you will see how the API Gateway works, understand all its components, and how to create your first deployment integrated with a Cloud Run service.


You can check this repo how you can create the API Gateway and deploy a Cloud Run hello world instance using Terraform.

Why should I use an API Gateway?

Here you can find a few reasons why you should use it:

  • It is a good way to decouple your front end from your backend.
  • It can break the frontend requests into several services.
  • It can help you to move your monolith backend into a microservices architecture.
  • Centralize Authentication access for your API’s.
  • API monitoring, metrics, quotas, and analytics
  • Centralize and manage API versioning


  1. GCP account with the billing activated. If you don’t have one yet you can create a new one using the free tier at $300.

Before starting: Crate your GCP Project

You will need a GCP project, so if you haven’t created yet you can follow these steps:

  1. Go to the Manage resources page in the Cloud Console.
  2. On the Select organization drop-down list at the top of the page, select the organization in which you want to create a project. If you are a free trial user, skip this step, as this list does not appear.
  3. Click Create Project.
  4. In the New Project window that appears, enter a project name and select a billing account as applicable. A project name can contain only letters, numbers, single quotes, hyphens, spaces, or exclamation points, and must be between 4 and 30 characters.
  5. Enter the parent organization or folder in the Location box. That resource will be the hierarchical parent of the new project.
  6. When you’re finished entering new project details, click Create.

Enable the Required API’s

API Gateway requires that you enable the following Google services. You can enable those by going to the menu -> APIs & Services -> Library.

The API Gateway

Google Cloud API Gateway is still in Beta, but I believe it is mature enough for a simple use/investigation.

As a managed service it is easily integrated with Cloud Run, AppEngine, Compute Engine, and GKE. It can also manage Authentication using API_KEY, OAuth2, and JWT.

API Gateway enables you to provide secure access to your services through a well-defined REST API that is consistent across all of your services, regardless of service implementation. A consistent API:

— Makes it easy for app developers to consume your services

— Enables you to change the backend service implementation without affecting the public API

— Enables you to take advantage of the scaling, monitoring, and security features built into the Google Cloud Platform (GCP)

This image shows some clients making requests to different backend services Source: here
This image shows some clients making requests to your backend services through API Gateway. Source: here

The Spec

The API Gateway is configured using an OpenAPI spec 2.0. Below you will see the smallest version you need to get up and running.

You can check the full OpenApi 2.0 spec here and here.

The Components

An API defined on API Gateway consists of two main components:

API config: The API configuration created when you upload an API definition. For the Beta, you create the API definition as an OpenAPI spec. Each time you upload an API definition, API Gateway creates a new API config. That is, you can create an API config but you cannot later modify it. If you later edit the API definition in the OpenAPI spec, and then upload the edited API definition, you create a new API config.

Gateway: An Envoy-based, high-performance, scalable proxy that hosts the deployed API config. Deploying an API config to a gateway creates the external facing URL that your API clients use to access the API.

Is deployed to a specific GCP region. A region is a specific geographical region on GCP where you can deploy resources.

Must host an API config. You cannot create an empty gateway, meaning one without an API config. However, after a gateway is created, you can update the gateway to replace one API config with another.

Can only host a single API config. You cannot deploy multiple API configs to the same gateway.

Using Terraform

First, you will need to make sure Terraform will pick up your credentials. There are a few ways to do that, and the simplest way is to use the Application Default Credentials. You can easily set it with the command below:

gcloud auth application-default login

This command will create .config/gcloud/application_default_credentials.json where Terraform will automatically read from without any extra configuration.

We are not using any Terraform backend at this moment, but I truly recommend you to set up a backend to manage your TF state. Here is how you create the backend using Google Cloud Storage.

Our Cloud Run hello world service

First, we will need to create the Cloud Run service in order to get the URL and update our API Gateway spec later. You can get the URL from the output printed after the terraform finishes.

You will need to run the code above from theterraform/cloud-run folder.

  • terraform init
  • terraform apply

Implementing our API Gateway using Terraform

The API Gateway resources were recently added (2 Nov 2020) into the Google beta provider. The API Gateway contains 3 main resources (differently from what we just saw above):

  • google_api_gateway_api Crates the API Gateway itself.
  • google_api_gateway_api_config Creates the Open API Spec within the API Gateway above.
  • google_api_gateway_gateway Creates the Gateway (Envoy proxy) linked to the API config.

You will need to include the Cloud Run run from theterraform/api-gateway folder.

  • terraform init
  • terraform apply

Check the access

Now you can go to and click on “The API Gateway”…

Then, click on the Gateway tab…

And now you will see your Gateway URL we will use to call our API.

You will need to include the API path we created into the API Gateway spec /v1/hello at the end. It should be something similar to:


…end That’s it!

Clean Up

  • Destroy all terraform resources withterraform destroy
  • Delete the project in case you will not use it anymore.


You can create an API Gateway in a few minutes and it is really easy to integrate with your GCP products.

Some drawbacks are:

  • Using one API Gateway for all your products can be difficult to manage and scale as the OpenAPI spec will be huge.
  • You can’t set your own domain/DNS into the gateway.
  • You will have downtime during the gateway update as Terraform will try to delete the gateway first and recreate it with the new config. Using the terraformlifecycle block doesn’t help either as the gateway complain saying thegateway alreay exists!. A workaround is forcing the current gateway to be updated with the command gcloud beta api-gateway gateways update after run terraform.





A collection of technical articles and blogs published or curated by Google Cloud Developer Advocates. The views expressed are those of the authors and don't necessarily reflect those of Google.

Recommended from Medium

Linux on the iPad.

Training under the guidance of Mr.Vimal Daga- Path to Right Education

How to quarantine Kubernetes Pods?

Serverless Framework —  Develop, deploy, and troubleshoot your serverless!

What makes thinkium special (part 2)

Essentialism and Software Engineering

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Felipe Martinez

Felipe Martinez

Brazilian Software Engineer living in London. Java addicted. Clean Code and Software craftsmanship Enthusiast. Cloud.

More from Medium

Cloud Bigtable: Understanding Bigtables NoSQL 3-dimensional storage model using the Node.js client

Query Cloud Spanner using Federated Query in BigQuery

Log-based Alerting in GCP

Accessing Google Cloud Storage Bucket’s using AWS SDK