About environments
Anenvironment provides an isolated context or "sandbox" for running API proxies. In a single organization, you can create multiple environments. For more information, seeAbout environments and environment groups.
The following code shows an example overrides configuration where multiple environments are defined. Note that environmentsprod andtest have different host aliases:
namespace:my-namespaceorg:my-organization...envs:-name:testserviceAccountPaths:synchronizer:"your_keypath/synchronizer-manager-service-account.json udca: "your_keypath/analytic-agent-service-account.json-name:prodserviceAccountPaths:synchronizer:"your_keypath/synchronizer-manager-service-account.json udca: "your_keypath/analytic-agent-service-account.json...
virtualhosts property that maps itsroutingRules to the environment(s).virtualhosts: - name: default hostAliases: ["api.example.com"] sslCertPath: ./certs/fullchain.pem sslKeyPath: ./certs/privkey.pem routingRules: - env: test
virtualhosts: - name: external hostAliases: ["apiprod.example.com"] sslCertPath: ./certs/fullchain.pem sslKeyPath: ./certs/privkey.pem routingRules: - env: prod
Suppose a proxy with the base path/foo1 is deployed to environmenttest. You could call the proxy like this:
curl -k https://api.example.com/foo1
When this call hits the ingress, the ingress knows to send it to the message processor associated with thetest environment, which handles the request.
Similarly, iffoo1 is also deployed to theprod environment, you could make a proxy request like this, to the host aliasapiprod.mydomain.net:
curl -k https://apiprod.example.com/foo1
And the call is routed by the ingress to the MP associated with that host.
NOTE On a request to an API proxy, the ingress compares theHost header of the incoming request to the list of host aliases to determine which virtual host handles the request.curl commands, browsers, and many other utilities automatically set theHost header with the domain of the request. If for any reason your app is not setting theHost header automatically, you must set it manually.Antipattern: Deploy all of your proxies to one hybrid environment.
Best practice: Create multiple environments and deploy a limited number of proxies to each one. You can create routing rules that specify which environments to route specific API proxy basepaths to. For details, seeVirtual host configuration.
Limit the number of proxy deployments
For hybrid, the fact that many environments can share the same virtual host means that you must think carefully about how you manage your proxy deployments to any given environment. In hybrid, the best practice is to create multiple environments and deploy a limited number of proxies to each one.
How many proxies should you deploy to an environment? There is not a set answer to this question; however, the following table provides general guidance on why it's a good idea to limit the number of proxies deployed to each environment and what you need to think about when managing proxy deployments:
NOTE:When deciding how many proxies to deployto an environment, be sure to consider the product configuration limits described inLimits.| Issue to consider | Description |
|---|---|
| Message processor boot-up time | There is a direct correlation between the amount of time a message processor (MP) takes to boot up and the number of proxies deployed to that MP. In an auto-scaling Kubernetes environment, an increase in boot time might be a problem. The more proxies that are deployed to the MP, the longer it will take for that MP to come up if it needs to be scaled or recreated. |
| Scaling performance | If you have several proxies deployed to an environment, and one of the proxies gets a lot of traffic so that it frequently auto-scales, all of the proxies in that environment will scale with it. The performance effect of scaling multiple proxies with a single high-traffic proxy might be a problem. |
| Noisy neighbor | If you have several proxies deployed to the same environment, and one proxy crashes, then all of the proxies in the environment will be taken down while the MPs restart. By limiting the number of proxies deployed to an environment, you minimize the impact of a single proxy crashing. |
Enviroment configuration reference
For a complete list of environment configuration elements, seeenvs in theConfiguration property reference.
Working with environments
For more information about configuration, see the following topics:
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2026-02-18 UTC.