Deploying an API to a gateway

Prerequisites

Before you can deploy an API config on API Gateway, ensure that you have:

Gateway ID requirements

Many of the gcloud commands shown below require you to specify the ID of the gateway, in the form: GATEWAY_ID. API Gateway enforces the following requirements for the gateway ID:

  • Must have a maximum length of 49 characters.
  • Must contain only lowercase letters, numbers, or dashes.
  • Must not start with a dash.
  • Must not contain an underscore.

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:

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

Deploy an API config to a gateway

Use the gcloud command-line tool to deploy an API config to a gateway. When you deploy the API config, you are required to specify the name of the API. If the gateway does not already exist for the API, then this command also creates it.

To deploy an API config to a gateway:

  1. Validate the project ID returned from the following command to make sure that the gateway isn't created in the wrong project.

    gcloud config list project

    If you need to change the default project, run the following command and replace PROJECT_ID with the Google Cloud project ID in which you want to create the service::

    gcloud config set project PROJECT_ID
  2. View help for the gateway create command:

    gcloud api-gateway gateways create --help
  3. Run the following command to deploy the API config to the 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 ID of the new gateway. If the gateway does not already exist then this command creates it.
    • API_ID specifies the ID of the API Gateway API associated with this gateway.
    • CONFIG_ID specifies the ID of the API config deployed to the gateway. You must specify an API config when creating a gateway.
    • GCP_REGION specifies the GCP region for the deployed gateway.

    • PROJECT_ID specifies the Google Cloud project ID.

    As it is creating the gateway, gcloud outputs information to the terminal.

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

    This command returns the following:

    apiConfig: projects/PROJECT_ID/locations/global/apis/API_ID/configs/CONFIG_ID
    createTime: '2020-02-05T13:44:12.997862831Z'
    defaultHostname: my-gateway-a12bcd345e67f89g0h.uc.gateway.dev
    displayName: GATEWAY_ID
    name: projects/PROJECT_ID/locations/GCP_REGION/gateways/GATEWAY_ID
    serviceAccount:
      email: gateway-111111@222222-tp.iam.gserviceaccount.com
    state: ACTIVE
    updateTime: '2020-02-05T13:45:00.844705087Z'

    Note the value of the defaultHostname property. This is the hostname portion of the gateway URL. To access an API config deployed to this gateway, you use a URL in the form:

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

The gcloud command-line tool takes many options, including those described in the gcloud Reference. In addition, for API Gateway, you can set the following options when creating a gateway:

  • --async: Return control to the terminal immediately, without waiting for the operation to complete.
  • --display-name=NAME: Specifies the display name of the gateway, meaning the name shown in the UI. Do not use spaces in the name. Use hyphens and underscores instead. The default value is GATEWAY_ID.
  • --labels=KEY1=VALUE1,KEY2=VALUE2,...: Specifies labels associated with the gateway.

Listing gateways

To list gateways for a specific project:

gcloud api-gateway gateways list --project=PROJECT_ID

This command returns output in the form:

NAME                                                          DISPLAY_NAME  STATE
projects/PROJECT_ID/locations/GCP_REGION/gateways/GATEWAY_ID  GATEWAY_ID    ACTIVE

To list gateways for a specific project and region:

gcloud api-gateway gateways list --location=GCP_REGION --project=PROJECT_ID

Use a filter expression to list the gateways associated with a specific API:

gcloud api-gateway gateways list \
  --filter="apiConfig:projects/PROJECT_ID/locations/global/apis/API_ID/*" \
  --project=PROJECT_ID

Or use this filter to list gateways for a specific API config:

gcloud api-gateway gateways list \
  --filter="apiConfig:projects/PROJECT_ID/locations/global/apis/API_ID/configs/CONFIG_ID" \
  --project=PROJECT_ID

Use the project, region, and gateway IDs to obtain detailed information about the gateway, including the identity of the API config deployed to the gateway:

gcloud api-gateway gateways describe GATEWAY_ID \
  --location=GCP_REGION --project=PROJECT_ID

Updating a gateway

Update a gateway to:

  • Deploy a different API config to the gateway
  • Update the display name
  • Update the labels

Use the following gcloud command to update an existing gateway:

gcloud api-gateway gateways update GATEWAY_ID \
  UPDATE_OPTIONS --api=API_ID --location=GCP_REGION --project=PROJECT_ID  

For example, to update the API config deployed to the gateway:

gcloud api-gateway gateways update GATEWAY_ID \
  --api-config=NEW_CONFIG_ID --api=API_ID --location=GCP_REGION --project=PROJECT_ID 

where NEW_CONFIG_ID specifies the new API config to deploy to the gateway.

To update the display name, use the --display-name option. To update the labels, use:

  • --update-labels=KEY=VALUE,...
  • --clear-labels
  • --remove-labels=KEY,...

Use the following command to view all update options:

gcloud api-gateway gateways update --help

Deleting a gateway

Use the following gcloud command to delete an existing gateway:

gcloud api-gateway gateways delete GATEWAY_ID \
  --location=GCP_REGION --project=PROJECT_ID

What's next