Understanding peering ranges

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

Apigee facilitates communications between client API requests and Apigee and Cloud services through a connection between two networks: the Apigee VPC (or runtime plane) and the Customer VPC. These two networks are tethered together using a private connection in a process known as VPC peering.

The following example shows how VPC peering enables communication between the Apigee VPC and the Customer VPC:

VPC peering between Apigee VPC and Customer VPC

VPC peering enables the Apigee VPC to process requests and responses sent to the Customer VPC:

  • Northbound traffic: Requests sent from clients to the Customer VPC that are passed through to the Apigee VPC for processing.

    This allows Apigee VPC services to process client app requests that are sent to the Customer VPC. These services include logging, identity management, and metrics.

  • Southbound traffic: Northbound requests that must access target APIs or other backend services on the Customer VPC.

    Apigee VPC services receive the northbound requests and send them on to their targets. The services can then process the responses before returning them to the Customer VPC.

Arrows showing where northbound and southbound traffic goes

Network sizing

Google recommends that you allocate a block of IP addresses available to your network (the Customer VPC) that roughly maps to the Apigee VPC. When you set up your VPC, choose one of the following IP address ranges to allocate:

Allocated IP Address Range Size # of Supported Environments Description
/16 65,536 IP addresses (216) Up to 75 environments, although the number of environments you can create depends on your contract (Recommended) Allows for robust scaling and flexibility.
/20 4,096 IP addresses (212) Up to 14 environments (this can be +/- 1, depending on conditions) Suitable for users who do not have large scaling requirements (such as in non-production environments) or do not have sufficient IP addresses in a given region.

Q: Do I need to match the size of the Apigee VPC?
While Apigee doesn't require a precise 1:1 mapping of VMs on the Apigee VPC to your VPC, your VPC should be similar in size to the Apigee VPC. The Apigee VPC can scale up quickly and use a considerable amount of resources (such as VMs) to maintain high availability and scaleability. Apigee requires that your VPC also be able to scale to match the management plane.

Q: How does this affect the number of environments per region?
The IP range defines the maximum number of environments that you can attach to a region. For example, an instance with /20 can have up to 14 attached environments. (This is not a guarantee that you can create that many environments in a region; it is the maximum number of attached environments. The number of environments you can create depends on your contract.)

Q: Why is the number of environments attached to a region important?
Because it affects the number of API calls that are processed in each environment: The cumulative total number of queries per second (QPS) that all environments in a region can process is roughly 8,400 to 11,200 (depending on conditions). As a result, the number of calls processed per environment scales up as the number of environments decreases.

The following table shows an approximate QPS based on the number of environments for a configuration with an IP allocation of /20:

# of Environments in the Region Approximate QPS / Environment*
14 600-785
13 646-846
12 700-916
11 763-1000
10 840-1100
9 933-1222
8 1050-1375
7 1200-1571
6 1400-1833
5 1680-2200
4 2100-2750
3 2800-3666
2 4200-5500
1 8400-11000
* Approximate QPS with /20 IP address allocation.

For example, in a region with 14 environments, no single environment can process beyond 600 to 800 QPS. Similarly, Apigee can process 8,400 to 11,200 QPS in a region with a single environment.

Apigee auto-scales environments. This auto-scaling can restrict the number of new environments that you can add.

For more information, see Limits.

Choosing an IP range

When and whether you can specify the size of your IP range depends on how you provision your org:

  • Paid orgs:
    • Apigee provisioning wizard: Apigee chooses a range size of /16 for you.
    • Command line: Set the peering range using the prefix-length and peeringCidrRange properties during Step 4: Configure service networking and Step 5: Create a runtime instance.

      You must set both properties (prefix-length and peeringCidrRange) to the same value: either /16 or /20. Do not specify two different sizes. If you do not explicitly set either property, the default is /16.

  • Eval orgs: You cannot choose the size of the peering range. Your network must allow for a range of /23.


In addition to the considerations in the Virtual Private Cloud documentation, you should also keep in mind the following when allocating IP addresses:

  • Apigee gateways are assigned IP addresses from within the CIDR range. As a result, it's important that the range is reserved for Apigee and not used by other applications in the Customer VPC.
  • The number of IP addresses used in a region depends on the total number of attached environments in the region and the peak volume of API traffic handled by all API gateways in the region.
  • You can have different sizes of VPC peering ranges for different regions in the same org. For example, an Apigee instance in the us-west1 region can use a /20 range, while the instance in us-east1 can use a /16.
  • After you create an instance, the CIDR range cannot be changed. To change the CIDR range, you must delete the instance and reconfigure a new one. (Be careful if you have only once instance in an org.)