Apigee Environments, Revisions and Deployment

# Run once per environment, changing ENV and the host. The docs create an HTTPS
# target by setting protocol "http", port 443 and sSLInfo.enabled true.
curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{"name":"orders-backend","host":"orders.test.internal.example.com","protocol":"http","port":443,"isEnabled":true,"sSLInfo":{"enabled":true}}' \
  "https://apigee.googleapis.com/v1/organizations/$ORG/environments/ENV/targetservers"

The same mechanism gives you rotation control: setting isEnabled to false takes a server out of load balancing. The same SSLInfo block configures TLS on a target server or a target endpoint; the docs do not say which wins if both are set, so define it in one place. A health monitor requires a non-zero MaxFailures, and retry needs at least two servers; the default MaxFailures of 0 means Apigee never removes a failing server from rotation.

Key value maps (KVMs). Small configuration and secrets, read at runtime by the KeyValueMapOperations policy. KVMs have three scopes (API proxy, environment, organization); environment is the default, and the console UI manages environment-scoped maps only. Entries are encrypted, and a retrieved value should go into a variable whose name starts with private. so it never shows in Debug sessions. The scope in the policy must match the scope used when the map was created.

<KeyValueMapOperations name="KVM-Get-Backend-Token" mapIdentifier="orders-config">
  <Scope>environment</Scope>
  <Get assignTo="private.backend.token">
    <Key>
      <Parameter>backend-token</Parameter>
    </Key>
  </Get>
</KeyValueMapOperations>

One behaviour to plan for: GET reads from an in-memory cache with a default expiry of 300 seconds, and the docs state that updating a KVM through the UI or API does not reset the cache. A changed value may therefore reach traffic only after the cache expires. Verify with a trace before declaring a config change live.

Shared flows

A shared flow is a reusable bundle of policies that proxies call with a FlowCallout policy. It is deployed to an environment like a proxy, and the shared flow must be deployed first, to the same environment as the proxy that uses it. If it is missing or not deployed, the FlowCallout fails at runtime with flow.SharedFlowNotFound. Some Apigee reference pages describe deploy-time dependency checks, but the documentation is not uniform on this, so treat "shared flow first" as the rule and do not rely on the deployment call to catch a missing one.

Ways to deploy

# Zip the bundle, import it (creates a new revision) and deploy it to dev in one step.
zip -r orders-v1.zip apiproxy
apigeecli apis create bundle -n orders-v1 -p orders-v1.zip -e dev --ovr --wait -o "$ORG" -t "$TOKEN"

# Promote an existing revision to test, then prod.
apigeecli apis deploy -n orders-v1 -e test -v 3 --ovr --wait -o "$ORG" -t "$TOKEN"
apigeecli apis deploy -n orders-v1 -e prod -v 3 --ovr --wait -o "$ORG" -t "$TOKEN"

# Undeploy a revision from an environment.
apigeecli apis undeploy -n orders-v1 -e dev -v 3 -o "$ORG" -t "$TOKEN"

By default apigeecli apis deploy runs a generateDeployChangeReport check first (--safedeploy) and proceeds only if there are no conflicts. The next lesson on CI/CD wires these commands into a pipeline.

How to implement it step by step

You will take a proxy orders-v1 from dev to test to prod with a different backend in each, then roll back.

Step 1: create or choose the environments. In the console open Apigee > Management > Environments and click Create Environment, or call the environments API. Attach each environment to an instance (an environment with no instance serves nothing) and to an environment group (an environment with no group has no hostname). On Pay-as-you-go, charges for an environment start once it is attached to an instance, even before traffic arrives.

Step 2: define the same target server name in every environment, with the host that belongs there, using the call above. The proxy only knows orders-backend.

Step 3: create environment-scoped KVMs for anything else that differs (feature switches, non-secret settings, tokens) and read them with KeyValueMapOperations. Keep secrets out of the bundle.

Step 4: build once and deploy to dev. Import the bundle, which creates a revision, and deploy it to dev. Run integration tests against the dev hostname.

Step 5: promote the same revision. Deploy revision 3 to test, run contract tests, then deploy revision 3 to prod and run a smoke test. Never rebuild the bundle between steps.

Step 6: change configuration without touching the bundle. To point test at a new backend, update the orders-backend target server in test, or edit the environment KVM entry. No new revision, no redeployment. After a KVM edit, wait for the cache expiry (default 300 seconds) or confirm in a debug session.

Step 7: roll back. If revision 4 misbehaves in prod, redeploy revision 3 with override:

gcloud apigee apis deploy 3 --api=orders-v1 --environment=prod --organization="$ORG" --override

Then check the deployment status in the UI (green means no errors or warnings) or through the deployments API, and confirm with a request. Record which revision is live so the next person knows.

Choosing an environment layout

The most common design question is how many organizations and environments to create. The facts that drive it: an organization is one Google Cloud project; API products, apps, developers and users are organization-level; environments are the unit of deployment and of per-environment configuration. You can create more than one organization (with Pay-as-you-go there is no fee for creating one).

Whatever you choose, give each environment its own environment group only if it needs its own hostname; sharing a group between environments means their base paths must not collide.

Use cases

1. Promoting dev to prod with different backends. The proxy calls the target server orders-backend. In dev it points to a mock service, in test to a staging system, in prod to the real one. Promotion is deploy revision 3 to the next environment; the host change lives entirely in each environment's target server.

2. Blue/green style revision switch. Apigee keeps one deployed revision per proxy per environment, so two revisions cannot be live side by side in one environment. You can still get a blue/green effect using documented pieces: run the old and new backends as two target servers, listed in the proxy's LoadBalancer, and flip their isEnabled flags to move traffic with no new deployment; or deploy the new version as a separate proxy with its own base path and switch clients by DNS or hostname. Confirm in a debug session how quickly the flip takes effect before you rely on it for a release.

3. Regional or multi-instance setups. To serve another region, create a new instance there (one instance per region), then attach the existing environments to it, one attachment call per environment. The docs warn against creating a separate environment with the same base paths and hosts, which can cause HTTP 503 errors at runtime. Environment groups need no change because environments stay in them. Evaluation organizations are limited to one region, adding a region depends on your licence entitlements, and a deployment unit is counted per environment, per instance.

4. Hotfix. A prod bug is fixed in revision 5. Import it, deploy to test for a quick check, deploy the same revision to prod. If the check fails, redeploy revision 3. No environment-specific rebuild.

A short note on hybrid

Apigee hybrid keeps the same model of organizations, environments and environment groups, but splits the product: Google hosts the management plane, and you run the runtime plane on Kubernetes you operate. The difference is that you also install, configure and operate the runtime on your own cluster. Check the version-specific hybrid docs before acting (for example on environment groups in the runtime configuration), because hybrid is versioned and these pages differ from Apigee X.

In practice: promoting an orders API from dev to prod

The situation. A team edits the orders-v1 proxy directly in the production organization's UI. Twice, a change that worked in test failed in prod because the backend host was hard-coded into the bundle. Nobody can say which revision is live, and a rollback means re-typing old policy settings.

Starting architecture.

What changes.

1. Create dev, test and prod environments in the organization and attach each to an instance and a group.
2. Replace the hard-coded URL with the target server orders-backend, defined in each environment with its own host.
3. Move per-environment settings into environment KVMs read with KeyValueMapOperations.
4. Build the bundle once, deploy revision 3 to dev, then promote the same revision to test and prod with apigeecli apis deploy ... --ovr --wait.
5. Write down the rollback command: redeploy the previous revision with override.

Result. The bundle that passed tests is byte-for-byte the one running in prod; only the target server differs. The team can state the live revision per environment, and a bad release is undone by redeploying the previous revision rather than by editing policies under pressure.

Architect's notes

• Environments are cheap to reason about, not free. On Pay-as-you-go, charges start when an environment is attached to an instance. Do not create one per feature branch.
• Treat deployment as a routing change in shared groups. Base-path collisions and removals affect everyone in the group; use the change report and sequenced rollout when a deployment moves traffic between environments.
• Prefer target servers over KVMs for hostnames. They are first-class backend definitions with enable/disable, load balancing and TLS settings. Use KVMs for small values and secrets.
• Know your cache. KVM reads are cached. Design operational changes (a kill switch, a flag) with the cache expiry in mind, or use a mechanism that takes effect immediately for the case you care about.
• Automate org-level setup in a two-org layout. Products, developers and apps are not shared between organizations. Script them so non-prod and prod do not drift.
• Do not edit in prod. Everything deployable is code in version control, and the pipeline is the only thing that deploys.
• Check quotas and limits. Apigee recommends no more than 3,000 base paths per environment or environment group, and the Limits documentation lists API call rates and deployments per instance. Check it for current numbers.

Common mistakes

• Hard-coding the backend in the bundle. Use target servers and KVMs so the same revision runs everywhere.
• Rebuilding per environment. It makes "works in test, not in prod" unfalsifiable. Promote the same revision.
• Forgetting override. Deploying a new revision when one is live is rejected unless override is set.
• Assuming undeploy rolls back. It does not. Redeploy the previous revision explicitly.
• Deploying a proxy before its shared flow. Deploy shared flows first, to the same environment.
• Environment with no group or no instance. It has no hostname, or nothing to run on, so calls fail. Attach both.
• Overlapping base paths in a group. A deployment can capture another proxy's traffic. Keep base paths unique per group.
• Expecting an instant KVM change. The read cache means a changed value may take minutes to reach traffic.
• Putting secrets in the bundle. Use encrypted KVMs or a secret manager.

Key takeaways

• An organization maps to one Google Cloud project and contains environments; hostnames live on environment groups; instances are regional runtimes.
• An environment needs a group to be reachable and an instance to serve traffic.
• Revisions are immutable; deploy one revision per proxy per environment, with override to replace a live one.
• Successful deployments are zero-downtime, but propagation is eventually consistent; verify after deploying.
• Rollback is redeploying the previous revision; undeploy alone does not restore it.
• Keep environment differences in target servers and KVMs so the same bundle is promoted dev to prod.
• Deploy shared flows before the proxies that call them, into the same environment.
• Pick the organization layout by isolation needs, and automate organization-level objects if you split them.

Practice exercises

Starter (about 30 minutes). In an evaluation organization, create an environment, attach it to an instance and a group, deploy any sample proxy, and call it through the group's hostname. Note the deployment status indicator and what happens when you deploy a second revision with and without override.

Intermediate (about 2 hours). Create dev and test environments. Define orders-backend target servers pointing to two different public sample services, deploy one bundle to both, and prove each environment calls its own backend. Add an environment KVM value and read it with KeyValueMapOperations into a private. variable. Change the KVM and measure how long the change takes to appear. Then roll back by redeploying the previous revision.

Advanced (half a day). Script the full promotion with apigeecli or gcloud plus the REST API: import, deploy to dev, run a test, promote the same revision, and roll back on a failed check. Write a one-page decision record for your organization layout using the flowchart in this lesson, and list the organization-level objects you would need to script if you used two organizations. Add a second instance in another region in an evaluation or sandbox organization if your entitlement allows, and document the attachment calls.

Related reading

• Apigee Fundamentals: Architecture and Request Flow — the runtime these environments sit on
• Building Apigee API Proxies: Flows, Endpoints, Policies — what a bundle contains
• Apigee CI/CD: Lint, Test and Promote Proxies — automating the promotion path shown here
• Fault Handling, Debugging and Monitoring in Apigee — verifying a release and diagnosing a bad one
• Apigee as an AI Gateway and Best Practices — environment practices for LLM traffic
• API gateway and service mesh — the broader gateway pattern
• Apigee API management for microservices — Apigee X in a service landscape

Official documentation

• About environments and environment groups
• Working with environments
• Understanding organizations
• Deployment overview and Deploying an API proxy
• REST method: deployments.deploy
• gcloud apigee apis deploy
• apigeecli on GitHub
• Apigee networking options
• Expanding Apigee to multiple regions
• Load balancing across backend servers and REST resource: targetservers
• Using key value maps and KeyValueMapOperations policy
• Creating reusable shared flows
• What is Apigee hybrid?