Building a proxy is half the job; getting it safely to production across environments is the other half. This page covers Apigee's deployment model and promotion strategy.
The model
flowchart LR
R[Proxy revision - immutable] --> D[dev env]
R --> T[test env]
R --> P[prod env]
EG[Env group / hostnames] --> P
KVM[(Per-env config: KVM / target servers)] -.-> D
KVM -.-> T
KVM -.-> P
- Revision — every change creates a new immutable revision. You deploy a revision to an environment; you don't edit a deployed revision in place.
- Environment —
dev,test,prod(model to your SDLC). - Environment group — binds hostnames/domains to environments (Apigee X), so the same proxy is reachable at env-specific URLs.
Environment-specific configuration
The same proxy bundle must run unchanged across environments. Externalise everything that differs:
- Target servers — backend host/port per environment (proxy refers to a logical name).
- Key Value Maps (KVMs) — environment-scoped config and secrets (encrypted).
- Property sets — non-secret config bundled or per-env.
The proxy reads these at runtime, so promoting a revision needs no code change — only the env's config differs.
Promotion strategy
- Deploy to
dev→ run integration tests against it. - Promote the same revision to
test→ QA / contract tests. - Promote to
prod→ smoke test.
Promote the identical artifact up the chain (build once, deploy many). Never rebuild per environment, and never hand-edit prod.
Safer rollouts
- Revision rollback — if a deploy misbehaves, redeploy the previous known-good revision (fast, because revisions are immutable).
- Override / zero-downtime deploy — Apigee deploys new revisions without dropping traffic; the old revision serves until the new one is ready.
- Canary — route a slice of traffic (via env groups/hostnames or a routing proxy) to a new revision before full cutover.
Tooling
apigeecli— modern CLI: create/deploy proxies, manage KVMs, target servers, env config.- Apigee Maven plugin — bundle + deploy from a Maven build (handy in Java shops/CI).
- Management API — everything is scriptable via REST.
# deploy a bundle to an environment (apigeecli)
apigeecli apis create bundle -f apiproxy -n orders-v1 --org "$ORG" --token "$TOKEN"
apigeecli apis deploy -n orders-v1 -v 3 -e test --org "$ORG" --token "$TOKEN"Best practices & anti-patterns
- ✅ Build once, promote the same revision through environments.
- ✅ Externalise all env differences to target servers / KVMs.
- ✅ Keep secrets in encrypted KVM or Secret Manager — never in the bundle.
- ❌ Editing proxies directly in the prod org UI (untracked, unrepeatable).
- ❌ Per-environment bundles with baked-in URLs (drift, "works in test not prod").
Next: automate all of this → CI/CD Pipelines →