API Gateway Deployment Model

About API components

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

  1. API config: The API configuration created when you upload an API definition. You create the API definition as an OpenAPI spec. If your API manages gRPC services on Cloud Run, you can define your API with a gRPC service definition and configuration.

    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 or gRPC service definition, and then upload the edited API definition, you create a new API config.

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

The following image shows these components:

The API definition on API Gateway pane shows three API config components and three gateway components.

About deploying an API config to a gateway

You deploy an API config to a gateway to make your API accessible to your API clients:

In three sample APIs, an API config is deployed to a gateway, making the APIs accessible to the API clients.

A gateway:

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

You then manage each deployed gateway separately. For each gateway, you can:

  • Start/stop/delete the gateway
  • View logs and metrics
  • View trace information

Choosing a GCP region

Each gateway is deployed to a specific geographical region on GCP. API Gateway supports the following GCP regions for deployment:

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

Defining the endpoint of the deployed API config

When you deploy an API config to a gateway, API Gateway creates a unique URL for the gateway in the gateway.dev domain. Your API clients then use a URL in the form below to access the deployed API config:

https://GATEWAY_ID-HASH.REGION_CODE.gateway.dev

where GATEWAY_ID is the name of the gateway HASH is the unique hash code generated when you deployed the API, and REGION_CODE is the code for the GCP region where you deployed the gateway.

For example:

my-gateway-a12bcd345e67f89g0h.uc.gateway.dev

Configuring a service account for deploying API configs

An API config deployed on a gateway executes with the permissions associated with the roles granted to the service account used to create the API config. Therefore, you typically define a separate service account for creating API configs. That service account is then assigned only to the roles necessary to access the backend service. In this way, you can limit the permissions associated with the API config.

In addition to the roles necessary to access the backend service, the service account is required to be granted the following permissions:

  • The iam.serviceAccounts.actAs permission. This permission is included in the Service Account User role.

  • The permissions necessary to access your backend service. For example, if your backend is implemented as a Cloud Function, then the service account should at the least be assigned to the role of Cloud Functions Invoker. For a Cloud Run backend, the role is Cloud Run Invoker. By limiting the permisisons associated with the API config, you can better secure your backend systems.

See Configuring your development environment for more.

About scale to zero

API Gateway is a scale-to-zero service. That means when there is no traffic, all gateway instances are deleted. When traffic increases, new instances are created on demand to handle the load. Scale-to-zero is controlled automatically by GCP; you are not required to configure or manage it.

Using a load balancer

Each gateway deployed in a region contains an integrated load balancer to manage client requests to the API deployed to the gateway. You are not required to create a separate load balancer for each gateway.

You do have to create a load balancer when you deploy the same API on gateways located in different regions. The load balancer then directs API requests to the different regions. See Deploying an API to multiple regions below for more.

Configuring SSL access to an API

API Gateway supports HTTPS access to an API deployed to a gateway. Because your APIs are deployed to the gateway.dev domain, Google creates and manages the SSL cert on the load balancer integrated with the gateway. You do not have to create or upload your own cert.

Configuring a Domain Name Server

By default, API clients make requests to a gateway.dev domain to access a deployed API, as shown above.

Custom domain names are for API Gateway when used in conjunction with HTTP(S) Load Balancing for API GatewayPREVIEW. To customize the domain name, create a load balancer to use your custom domain name and then direct requests to the gateway.dev domain of your deployed API. For more information, see Use a custom domain with API Gateway.

Deploying multiple API configs in the same API

You can only deploy a single API config to a gateway. However, you can deploy multiple API configs to multiple gateways within the same API.

This section describes two scenarios where you might deploy multiple API configs on multiple gateways within a single API.

Deploying API configs to multiple gateways in the same region

When building an API, API developers often create development, staging, and production environments, where:

  • The development environment is used by developers to create the API.
  • The staging environment is used to test the API in preparation for a release to production.
  • The production environment is where your external API clients are allowed to access the API.

To support this type of development environment, you define multiple API configs. For example, you might have several API configs currently in development, one API config currently being tested on staging, and one API config currently deployed to production.

API Gateway lets you create multiple API configs within a single API, and then deploy each API config to different gateway:

In API 1, three API configs called API Config Dev, API Config Stage, and API Config Prod are deployed to three respective gateways.

In this example, you have three different API configs: dev, stage, and prod. You then deploy each API config to a different gateway, where each gateway defines its own unique endpoint URL.

Deploying an API config to multiple regions

Often you deploy an API to multiple GCP regions. Deploying in multiple regions offers several advantages, including reduced request latency because requests are directed to an API running in a region geographically close to the client, and improved reliability because a failure in one region does not affect APIs running in other regions.

To deploy an API to multiple regions, you deploy an API config to a gateway in each region. Each API config is specific to the deployed region because it has to reference the backend service in that region.

In the following image, APIs 1 and 2 are deployed to a single region and API 3 is deployed across multiple regions:

API 1 and API 2 are deployed to Region 1, and API 3 is deployed across Region 1, Region 2, and Region 3 using a load balancer.

In this example, each API config deployed to a gateway for API 3 has a unique URL endpoint, in the form:

https://my-gateway1-a12bcd345e67f89g0h.uc.gateway.dev
https://my-gateway2-b12cde345f67g89h0i.en.gateway.dev
https://my-gateway3-c12bde345g67h89i0j.uw.gateway.dev

You then configure a load balancer using HTTP(S) Load Balancing for API GatewayPREVIEW to handle requests to the API and forward the request to the appropriate region. For more information, see Creating multi-region deployments for API Gateway.

Updating an API

You can update a deployed API by editing the API definition in the OpenAPI spec, and then uploading the spec. Uploading a new spec creates a new API config.

API Gateway supports a zero-downtime update model, which means your API continues to handle requests during the deployment of the updated API config. However, there is a period of time while the new API config is being deployed when some requests might still be handled by the previous version of the API config.

If you have deployed the API config across multiple regions and gateways, you have to redeploy the updated API config in each region separately.

What's next