View
Apigee Edge documentation.
This section describes environments and environment groups.
An Apigee environment is a software environment, within an organization, for creating and deploying API proxies. You must deploy an API proxy to an environment before it can be accessed. You can deploy an API proxy to a single environment or to multiple environments.
Each environment is subject to limits on the number of API proxies, shared flows, and other resources that can be deployed to it. These limits vary based on the Apigee organization type (Subscription, Pay-as-you-go, or Apigee hybrid) that uses the environment. For more detailed information, see the Limits documentation.
An environment group (sometimes called an envgroup in the Apigee API) is the basic mechanism for defining the way requests are routed to individual environments. You define hostnames on your environment groups (not on individual environments), and Apigee routes requests to the environments within a group using those hostname definitions.
An environment must be a member of at least one environment group before you can access proxies deployed within it. In other words, you must assign an environment to a group before you can use it.
The logical grouping of environments by environment group provides the following benefits:
Apigee supports the following deployment types in an environment:
| Type | Description |
| Proxy | Develop and test your API proxies in your Apigee development environments, and then deploy them to Apigee integration test and production environments. See Deploying an API proxy. |
| Archive | Develop and test your programmable API proxies using Apigee in VS Code. |
When you enable Archive deployment in an Apigee environment, you will be prevented from performing the following actions within the environment to prevent conflicts:
If you attempt to perform any of the prevented actions listed above, the action will fail with the following error message:
FAILED_PRECONDITION
Proxy deployment units (PDUs) measure the consumption of your Apigee capacity based on the deployment of API proxies and shared flows across your infrastructure.
A proxy deployment unit is defined as one API proxy or shared flow revision deployment, per environment, per instance (region). Because Apigee scales with your infrastructure, a single proxy deployment can count as multiple units if it is deployed to an environment that spans multiple instances.
The total PDUs are calculated by summing the deployment units across all environments in your organization. For each environment, the PDU contribution is the number of deployed revisions multiplied by the number of instances (regions) the environment is attached to.
The general formula for total PDUs is:
Total PDUs = Σ (Deployed Revisions in Envn × Instances for Envn)
Where the sum is over all environments (Envn) where the proxy or shared flow is deployed.
If a proxy or shared flow is deployed to environments that are all attached to the same number of instances, a simplified formula can be used:
PDUs = (Deployed Revisions) × (Environments) × (Instances)
The following table provides examples of how PDUs are calculated in different infrastructure scenarios:
| Scenario | Proxies | Environments | Instances (Regions) | Total PDUs |
|---|---|---|---|---|
| Single Region Small-scale deployment |
1 | 1 | 1 | 1 |
| Multi-Region High Availability Same proxy in two regions |
1 | 1 (attached to 2 instances) | 2 | 2 |
| Multi-Environment Same proxy in Dev and Test |
1 | 2 (Dev, Test) | 1 | 2 |
| Enterprise Scale Global deployment across multiple envs (Assumes both Prod and Staging environments are attached to all 3 instances) |
5 | 2 (Prod, Staging) | 3 (US, EU, Asia) | 30 |
Proxy deployment units count proxies and shared flows deployed to environments per region.
These are the deployment unit types:
Your usage might be subject to deployments quota, which is a limit on how many deployment units you can use at a time. See your entitlements (Pay-as-you-go or Subscription 2024) for details. For information on system limits, see Max proxy deployment units per instance.
For more information on viewing proxy deployment unit usage and deployments quota details for your organization, see View proxy deployment usage.
For Pay-as-you-go users, when you create an environment you will select the environment type: Base, Intermediate, or Comprehensive. Features, functionality, and costs associated with the environment depend on the environment type. See Pay-as-you-go environment types and Pay-as-you-go entitlements for more information.
For Apigee subscription plans, your environment type is always Apigee Comprehensive and you do not need to know about environment types.
Apigee supports forwarding traffic to a specified URI. This feature applies at the environment level and can be used to direct traffic to the internet after initial processing in a proxy.
Incoming requests to proxies in the configured environment process for any included policies (see Forward proxying feature support) and then forward using HTTP to the new URI.
Changes made to the forward proxy setting of an environment are effective immediately for new requests only. Requests already processing complete with the setting that was in place when the request was received.
For instructions to configure forward proxying, see Configure forward proxying in an environment.
Not all generally available proxy features have the same availability or applicability with forward proxying.
Apigee does not currently support Basic Authentication with forward proxying, except in Apigee Hybrid.
This table shows support for additional functionality:
| Feature or policy | Supported/applicable for forward proxying? |
| Target Endpoints | Yes |
| HTTP Health Check | Yes |
| Service Callouts | Yes |
| HTTP calls via JavaScript | Yes |
| Integration targets | Yes |
| Proxy chaining, via local loopbacks | No |
| Publishing messages | No |
| Cloud Logging | No |
| Communication with Synchronizer | No |
| Message logging via Syslog | No |
GoogleToken via an external audience is currently not supported with forward proxying.
The following table lists important points to remember about environments, organizations, and environment groups:
| Element | Rules |
|---|---|
| Organizations |
|
| Environments |
|
| Environment Types |
(See Environment types.) |
| Environment Groups |
|
The following sections show common ways in which environments are structured within environment groups.
The simplest structure is a single environment group with a single environment in it. This is common for organizations that are currently evaluating the product or have not yet set up testing or analytics infrastructure, nor have any proxies deployed in production.
An environment group can contain multiple environments. For example, a single environment group, prod-group, can contain three environments, cart-prod, catalog-prod, and payment-prod.
The environment group has a single hostname, example.com. You can use the
hostname to route requests to a proxy deployed in any of the environments. Note that
hostnames are defined
on the environment group level: they do not route to a specific environment.
See Working with environment groups to learn how to create this environment group.
In the previous example, requests can be routed to proxies in all three environments by a single hostname. If you want to restrict access to proxies in a single environment, say catalog-prod, create another environment group that contains only the environment catalog-prod. Then a hostname defined for that environment group can only access catalog-prod.
For example, the hostname catalog.example.com,
for the environment group catalog-prod-group, can
only route requests to proxies in the environment catalog-prod.
|
Ready to create a group?
|
To learn more about environments:
|
To learn more about environment groups:
|
In a simple configuration, a request to a deployed API proxy is made up of a hostname, base path, and the name of an API resource; for example:
https://www.example.com/shopping/cart/addItem
|_____________| |___________| |_____|
| | |
hostname basepath resource
You define hostnames on the environment group so that multiple environments can share them. Basepaths and API resources are defined on the API proxy.
For more information about base paths and API resources, start with Understanding routes. In addition, check out the Flow configuration reference and Flow variables reference to gain a greater understanding of how these pieces fit together.
When you create an environment group, you attach one or more hostnames to that group. For example, you might have the following environment groups, each with its own hostnames:
| Environment Group Name (Environments) |
prod-group (catalog-prod cart-prod pymnt-prod) |
dev-group (dev-env) |
test-group (test-env) |
|---|---|---|---|
| Hostnames | catalog.example.com payment.example.com |
dev.example.com | test.example.com |
You define base paths on the proxy when you create it.
When you deploy a proxy to an environment within the group, the hostname plus the base path and the resource name together define the endpoint of an API request to that proxy.
You can define more than one hostname on an environment group. They can all be used to call any
proxy deployed to any environment in the group. For example, catalog.example.com/proxy1
and payment.example.com/proxy1 will both call the proxy1 resource if
the hostnames catalog.example.com and payment.example.com are defined on
the same environment group.
For example:
The prod-group environment group contains the following environments:
catalog-prodcart-prodpymnt-prodThe prod-group has the following hostnames defined on it:
catalog.example.compayment.example.comThe following proxies are deployed to these environments:
catalog proxy on catalog-prod with a base path of
/catalogcart proxy on cart-prod with a base path of
/catalog/cartpayment proxy on pymnt-prod with a base path of
/paymentThis creates the following endpoints:
catalog.example.com/catalog routes to the
catalog proxy in the catalog-prod environment.catalog.example.com/catalog/cart routes to the
cart proxy in the cart-prod environment.payment.example.com/payment routes to the
payment proxy in the pymnt-prod environment.The following example shows that the requests are routed to different proxies that are deployed to environments within the group, matching any of the hostnames and the base path:
An environment can belong to multiple environment groups. If you deploy a proxy to such an environment, the proxy will have a multiple addresses, one for each environment group the environment belongs to. This is useful if a customer has wildcard certificates (like *.example.com) for multiple partners.
For example:
shared-env belongs to two environment groups:
partner-1 with host alias api.partner-1.compartner-2 with host alias api.partner-2.comfoo is deployed to shared-env with a base path
/foo. Because shared-env is shared by both environment groups,
foo has two addresses:
api.partner-1.com/fooapi.partner-2.com/fooNote that both of the hostnames route to the same environment. This gives each environment group a unique domain name. For Apigee Hybrid, this scenario can use mTLS with a different certificate for each partner.
The organization provides scope for some Apigee capabilities. For example, key-value-map (KVM) data can be made available at the organization level, meaning that API proxies deployed to any environment within that organization can access the same KVM data.
Similarly, some capabilities can be scoped to environments or environment groups within the organization. For example, Apigee analytics data is partitioned by a combination of organization, environment, and (eventually) environment group.
Every deployment to an environment has the potential to affect the routing of traffic for every environment group to which that environment is attached. When new basepaths are added, they may start capturing entirely new traffic, or they may start capturing a subset of existing traffic already being handled by an existing deployment.
Similarly, when basepaths are removed, they may correspond to endpoints that no longer receive any traffic, or they may cause existing traffic to be rerouted to a different proxy. When traffic is rerouted, it may be to a proxy in the same environment, or when multiple environments share a single environment group, it may be to a proxy in a different environment.
The total number of API proxy basepaths added to an environment, or environment group, should also be considered. For optimal performance, Apigee recommends using no more than 3,000 API proxy basepaths per Apigee environment or environment group. Exceeding this recommendation can result in increased latency for all new and existing API proxy deployments.
The following information describes how to manage your environments and environment groups:
With the Apigee UI:
With the Apigee API:
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2026-07-23 UTC.