About environments and environment groups

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

This section describes environments and environment groups.

Overview

An environment is a runtime execution context for the API proxies and shared flows in an organization. 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 limited to 50 deployed API proxies plus shared flows (combined).

An environment group (sometimes called an envgroup in the Apigee APIs) 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 by using those hostname definitions.

An environment must be a member of at least one environment group before you can access resources defined 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:

  • Centralized hostname management: Environment groups provide a centralized place to manage hostnames.
  • Aggregate insights: With groups, you can analyze errors by looking at reports for an entire environment group at once rather than individual environments.
  • Conflict avoidance: By grouping environments, you can ensure that the base paths for your environments don't exist under the same hostname.

Number of environments you can create

Apigee and Apigee hybrid have limits on the number of environments and environment groups you can create per organization and per region. See Limits: Environment and organization.

In Apigee, the number of environments you can create in a region depends on the number of IP addresses allocated for your VPC network (the CIDR range):

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.

Key points

The following table lists important points to remember about environments, organizations, and environment groups:

Element Rules
Organizations
  • Can contain multiple environment groups
  • Must have at least one environment group
Environments
  • Must be in at least one environment group
  • Can be in more than one group
  • Share hostnames with all other environments in the same group
Environment Groups
  • Can have multiple hostnames
  • Contain one or more environments
  • Hostnames assigned to a group must be unique to that group (they cannot be used by other groups)

Examples

The following sections show common ways in which environments are structured within environment groups.

One environment group and one environment

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.

One environment group for one environment

Multiple environments in a single group

An organization can contain multiple environment groups. For example, you might define the dev, test, and prod environment groups in an organization, and map each of those to a single hostname (or IP address). Within each group, there might be one or more environments:

One environment group for multiple environments

Environment groups aligned with access

Because you can assign the same environment to more than one group, you can organize your environments by access. For example, you can make your production environments accessible on a single internal environment group, but limit access to some of those environments on a public group, which would be open to the internet:

One environment group for internal resources and one for external resources

Environment groups aligned with business units

With a larger, more mature set of actively deployed proxies, it is common to align environment groups with business units. For example, you might have environment groups for your testing, production, and development teams:

One environment group per business unit

 

Ready to create a group?

Open the Console

 

 

To learn more about environments:

Keep Reading

 

 

To learn more about environment groups:

Keep Reading

 

Routing and base paths

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.

Hostnames

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.

To support multiple hostnames on a single environment group that is shared by multiple environments, Apigee routes API requests to different proxies in different ways.

Routing example

For example:

  • The prod-group environment group contains the following environments:

    • catalog-prod
    • cart-prod
    • pymnt-prod
  • The prod-group has the following hostnames defined on it:

    • catalog.example.com
    • payment.example.com
  • The following proxies are deployed to these environments:

    • The catalog proxy on catalog-prod with a base path of /catalog
    • The cart proxy on cart-prod with a base path of /catalog/cart
    • The payment proxy on pymnt-prod with a base path of /payment

This 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, depending on the hostname and the base path:

API requests are routed to different environments within the group based on the hostname
  and base path

Shared environments and routing

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.com
    • partner-2 with host alias api.partner-2.com
  • Proxy foo 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/foo
    • api.partner-2.com/foo

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

About environment scope

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.

Considerations

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 some proxy in the same environment, or when multiple environments share a single environment group, it may be to a proxy in a different environment.

Additional resources

The following information describes how to manage your environments and environment groups: