Getting started with API Gateway and Cloud Run

This page shows you how to set up API Gateway to manage and secure a Cloud Run backend service.

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.

1. Create or select a Google Cloud project.
2. If you haven't deployed your own Cloud Run, deploy a sample service. See step 7 in Before you begin.
3. Enable the required API Gateway services.
4. Create an OpenAPI spec that describes your API, and configure the routes to your Cloud Run backend service. See Creating an API config.
5. Deploy an API Gateway using your API config. See Deploying an API Gateway.
6. Track activity to your services. See Tracking API activity.
7. 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 you want to use for this tutorial. On the rest of this page, this project ID is referred to as PROJECT_ID.

4. Download and install the Google Cloud CLI.

   Download the gcloud CLI

5. Update gcloudcomponents:

   gcloud components update

6. Set the default project. Replace PROJECT_ID with your Google Cloud project ID

   gcloud config set project PROJECT_ID

7. If you haven't deployed your own Cloud Run service, follow the steps in Quickstart: Deploy a Prebuilt Sample Container to select or create a Google Cloud project and deploy a sample backend. Make a note of the app URL, as well as the region and project ID where your apps are 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

Before API Gateway can be used to manage traffic to your deployed Cloud Run backend, it needs an API config.

You can create an API config using an OpenAPI spec that contains specialized annotations to define the desired API Gateway behavior. You will need to add a Google-specific field that contains the URL for each Cloud Run app so that API Gateway has the information it needs to invoke an app.

1. Create a text file called openapi2-run.yaml. (For convenience, this page refers to the OpenAPI spec by that file name, but you can name it something else if you prefer.)
2. List each of your apps in the paths section of the openapi2-run.yaml file, as shown below:

   # openapi2-run.yaml
   swagger: '2.0'
   info:
     title: API_ID optional-string
     description: Sample API on API Gateway with a Cloud Run backend
     version: 1.0.0
   schemes:
   - https
   produces:
   - application/json
   x-google-backend:
     address: APP_URL
   paths:
     /assets/{asset}:
       get:
         parameters:
           - in: path
             name: asset
             type: string
             required: true
             description: Name of the asset.
         summary: Assets
         operationId: getAsset
         responses:
           '200':
             description: A successful response
             schema:
               type: string
     /hello:
       get:
         summary: Cloud Run hello world
         operationId: hello
         responses:
           '200':
             description: A successful response
             schema:
               type: string

3. In the title field, replace API_ID with the name of your API and replace optional-string with a brief description of your choosing. If your API does not already exist, the command to create the API Config will also create the API with the name you specify. The value of the title field is used when minting API keys that grant access to this API. See API ID requirements for API naming guidelines.
4. In the address field in the x-google-backend section, replace APP_URL with the actual URL of your Cloud Run service (the full path of the called API). For example: https://hello-abc1def2gh-uc.a.run.app.
   Note: If you plan to use revision tags to version your Cloud Run service backend, you must specify the jwt_audience field under address in the x-google-backend section. The value of the jwt_audience field should be the Cloud Run service URL. For example:

   ...
     x-google-backend:
         address: https://VERSION_TAG---SERVICE_HOSTNAME/PATH
         jwt_audience: https://SERVICE_HOSTNAME
   ...

   If the jwt_audience field is not present, the x-google-backend extension defaults to the value of the address field for the JWT audience claim. This can result in an unexpected JWT audience claim for Cloud Run if the revision tag URL is used for address and no jwt_audience is specified.
5. Enter the following command, where:
   • CONFIG_ID specifies the name of your API config.
   • API_ID specifies the name of your API. If the API does not already exist then this command creates it.
   • PROJECT_ID specifies the name of your Google Cloud project.
   • SERVICE_ACCOUNT_EMAIL specifies the service account used to sign tokens for backends with authentication configured. For more information, see Creating a service account.
     Note: The service account used to create an API config for a Cloud Run backend must have the run.invoker role assigned.

   gcloud api-gateway api-configs create CONFIG_ID \
     --api=API_ID --openapi-spec=openapi2-run.yaml \
     --project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

   This operation may take several minutes to complete as the API config is propagated to downstream systems. Creation of a complex API config could take up to ten minutes to complete successfully.

6. After the API config is created, you can view its details by running this command:

   gcloud api-gateway api-configs describe CONFIG_ID \
     --api=API_ID --project=PROJECT_ID

Deploying an API Gateway

Now you can deploy your API on API Gateway. Deploying an API on API Gateway also defines an external URL that API clients can use to access your API.

Run the following command to deploy the API config you just created to API Gateway:

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.

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.

Testing your API deployment

Now you can send requests to your API using the URL generated upon deployment of your gateway.

Enter the following URL in your web browser, where:

• DEFAULT_HOSTNAME specifies the hostname portion of your deployed gateway URL.
• hello is the path specified in your API config.

https://DEFAULT_HOSTNAME/hello

For example:

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

You should see your Cloud Run container running your app in the browser.

Success! Your API Gateway is managing access to your Cloud Run backend service.

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.

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.