About API components
An API defined on API Gateway consists of two main components:
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.
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:
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:
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:
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:
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.
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:
iam.serviceAccounts.actAspermission. 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
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 not supported for API Gateway.
If you want to customize the domain name, you have to create a load balancer
to use your custom domain name and then direct requests to the
of your deployed API.
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 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:
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 to handle requests to the API and forward the request to the appropriate region.
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.