Expanding Apigee to multiple regions

You're viewing Apigee X documentation.
View Apigee Edge documentation.

You can expand an Apigee organization across multiple regions. Multi-region configurations diversify the physical locations of your clusters, which provides failover in case the environments in a single location fail.

This document explains how to add Apigee to a new region and how to remove Apigee from a region.

Adding Apigee to a new region

You can have one runtime instance per region, so to add a new region you must create an entirely new instance in that region.

The general process for adding a new region is as follows:

  1. Ensure that you have an appropriate IP address range in your peering network available, as described in Prerequisites. In addition, be sure that your account can support a new region, as described in Limits.
  2. Define environment variables
  3. Reserve a new address range
  4. Create a new key ring and key
  5. Create a new instance
  6. Attach environments to the new instance
  7. Test your API

Each of these steps is described in the sections that follow.


Ensure that your network has /22 and /28 as non-overlapping IP address ranges available. This is in addition to the ranges used by other regions.


By default, your initial org is typically created with a single region. When deciding whether to create a second (or subsequent region), note that you can only add a region if you purchase an org pack. (Eval accounts are limited to one region and cannot be expanded to a second region.)

For more information, see Apigee Pricing.

No organization can have more than 10 regions.

Define environment variables

Google recommends that you define environment variables to ensure consistency across your commands and so that you can follow along with the documentation. This section uses environment variables you set up in Define environment variables.

In addition to those already created, add the following environment variables:



  • NEW_REGION_LOCATION is the physical location of your new instance. Valid values are any Compute Engine region. For more information, see Compute Engine locations. For example, europe.
  • NEW_INSTANCE_NAME is the name of the new region. It must be unique for your organization. For example, my-instance-2.
  • NETWORK_NAME is the name of your organization's peering network. For example, my-network.

Create a new key ring and key

Each region requires its own disk encryption key for the network. Google recommends that you also create a separate key ring for the new region. You do not need to create a new database encryption key because all instances in an organization share the same database encryption key.

For additional details, see About the Apigee encryption keys.

To create a new disk encryption key ring and key:

  1. Create a new disk key ring using the gcloud command:
    gcloud kms keyrings create my-disk-key-ring-2 \
      --location $NEW_REGION_LOCATION \
      --project $PROJECT_ID

    Your disk key ring must be set to the same location as the instance. Each instance and key ring should have its own location.

  2. Create a new disk key using the kms keys create command; for example:
    gcloud kms keys create my-disk-key-2 --keyring my-disk-key-ring-2 \
      --location $NEW_REGION_LOCATION --purpose "encryption" --project $PROJECT_ID

    The key can be referenced by its key path. You can get the key path with the following command:

    gcloud kms keys list \
      --location=$RUNTIME_LOCATION \
      --keyring=$DISK_KEY_RING_NAME \

    The key path looks like the following:

  3. Grant access for the Apigee Service Agent to use the new key by executing the gcloud kms keys add-iam-policy-binding command; for example:
    gcloud kms keys add-iam-policy-binding my-disk-key-2 \
      --location $NEW_REGION_LOCATION \
      --keyring my-disk-key-ring-2 \
      --member serviceAccount:service-$PROJECT_NUMBER@gcp-sa-apigee.iam.gserviceaccount.com \
      --role roles/cloudkms.cryptoKeyEncrypterDecrypter \
      --project $PROJECT_ID

    This command binds the key to the Apigee Service Agent.

Reserve a new address range

Reserve IP addresses for your peering network's address range:

For more information and important considerations, see also Understanding peering ranges.
  1. Create these environment variables:


    • NEW_RANGE_NAME is the name of the IP address range you are creating. You can name the range anything you want. For example: google-svcs-new
    • NETWORK_NAME is the name of the network resource in which the addresses should be reserved.

      Google creates a default network (named default) for each new project, so you can use that. However, Google does not recommend using the default network for anything other than testing.

  2. Create a network IP range with a CIDR length of /22:
    gcloud compute addresses create $NEW_RANGE_NAME \
      --global \
      --prefix-length=22 \
      --description="Peering range for Apigee services" \
      --network=$NETWORK_NAME \
      --purpose=VPC_PEERING \

    On success, gcloud responds with the following:

    Created [https://www.googleapis.com/compute/v1/projects/PROJECT_NAME/global/addresses/google-svcs-new].

    After you create a range of IP addresses, the addresses are associated with the project until you release them.

  3. Create a network IP range with a CIDR length of /28. This range is required and is used by Apigee for troubleshooting purposes and cannot be customized or changed.
    gcloud compute addresses create google-managed-services-support-2 \
      --global \
      --prefix-length=28 \
      --description="Peering range for supporting Apigee services" \
      --network=$NETWORK_NAME \
      --purpose=VPC_PEERING \
  4. Get the names of the original and new peering ranges:
    gcloud services vpc-peerings list \
      --network=$NETWORK_NAME \
  5. Add the newly reserved range to your peered network with the following command where $NEW_RANGE_NAME, ORIGINAL_RANGE_NAME, google-managed-services-support-1, and google-managed-services-support-2 were the reserved peering range names returned in the previous command:
    gcloud services vpc-peerings update --service=servicenetworking.googleapis.com \
      --network=$NETWORK_NAME \
      --ranges=$NEW_RANGE_NAME,ORIGINAL_RANGE_NAME,google-managed-services-support-1,google-managed-services-support-2, \

Create a new instance

Create a new instance for the region using the Instances API.

Note that each region can only have one instance, just as each instance can only be located in one region.

The following example creates a new instance with a name that matches your $NEW_INSTANCE_NAME environment variable:

curl -X POST -H "$AUTH" \
  -H "Content-Type: application/json" \
  https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/instances \
  -d '{

Where KEY_PATH is the disk encryption key's key path that you created in Create a new key ring and key.

For more details about creating a runtime instance, including additional context and troubleshooting information, see Step 5: Create a runtime instance.

Attach environments to the new instance

After creating the instance, you must attach environments to it, otherwise it cannot respond to API requests.

Environments are shared across instances; therefore, you typically attach existing environments to the new region. You typically do not define new environments for the new region.

When you populate a new region with environments, you do not need to attach the environments to environment groups: they are already attached to their groups. You need only attach the environments to the new instance.

To attach your environments to the new region, use the Instances attachment API as the following example shows:

curl -X POST -H "$AUTH" \
  -H "Content-Type: application/json" \
  https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/instances/$NEW_INSTANCE_NAME/attachments \
  -d '{

If you are not sure of the names of your environments, use the List environments API.

You must attach each environment with a separate call to the Instances Attachment API. You cannot attach more than one environment in a single call.

Test your API

After you finish creating the new region and attaching environments to its instance, you should test the region by sending requests directly to it.

The next step is to test with an API call (going directly to the second region). For information on sending requests directly to a proxy, see Accessing API proxies.

Removing Apigee from a region

If you no longer wish to have an Apigee instance in a particular region, you can simply delete the instance from the region. Deleting the instance effectively removes Apigee from the region. See Deleting an existing instance.