Apigee API Management, Hybrid & Edge Migrations

Why You Can’t Just Leave Legacy Edge or Hybrid Alone

Nobody wakes up wanting to migrate an API gateway. If it routes traffic and doesn’t page your on call team at 3am, the temptation is to leave it alone.

The problem is that Google is actively decommissioning older Apigee hybrid versions and retiring legacy Apigee Edge tooling. If you are on Apigee Edge (SaaS or Private Cloud OPDK) or an older Apigee hybrid runtime tied to deprecated Kubernetes and Istio releases, staying put stops being an option. Once your runtime version drops out of support, you lose security patches, bug fixes, and GKE version compatibility. If you are in a regulated industry in Australia, running an unpatched edge gateway in front of customer or clinical data is a massive compliance risk.

We have just gone through this exact migration for a large Australian healthcare company, helping them transition off legacy infrastructure onto the new Apigee platform as Google decommissioned their old hybrid setup. Moving live healthcare APIs handling patient and clinical data without dropping a single request takes proper engineering, not a lift and shift script.

The stuff that breaks when you migrate

Teams often assume migrating from Apigee Edge or an old hybrid install to the new Apigee platform is just exporting proxy bundles and importing them into the new org. If you have actually tried it in staging, you know that falls apart fast. Here is what actually trips teams up:

• HTTP/1.1 headers get forced to lowercase. The new Apigee runtime converts all HTTP/1.1 header field names to lowercase when forwarding requests to your backend target servers. If you have a crusty legacy backend that expects X-Customer-ID in mixed case, it will silently break until you fix it.
• No more Node.js proxies or SOAP wizards. Legacy Node.js API proxies are gone. Google expects you to run Node.js apps as separate containers on Kubernetes or Cloud Run. The old SOAP proxy wizard is gone too, so you have to use the open source wsdl2apigee utility instead.
• Envoy replaces the old Istio adapter. The Apigee Adapter for Istio is deprecated. Everything now runs on the Apigee Adapter for Envoy.
• One MP pod per environment. In the new architecture, a Message Processor (MP) pod can only serve a single environment. You organise routing through environment groups, and deployments are asynchronous based on when the runtime plane last checked in with the management plane.
• Payload and API changes on apigee.googleapis.com. Query parameters prefixed with an underscore (like _optimal=true) are no longer supported, properties like created_by, modified_by, and self are stripped from payloads, timestamps in keys are strings ({"createdAt": "1234"}), and cache API operations only support list and delete (returning 204 No Content).

How We Implement Apigee, Edge, and Hybrid

We work across all three setups depending on where your workloads live and what your network team will allow:

Apigee Technical Feature Summary (Apigee vs Apigee Hybrid)

If you are comparing Apigee (fully managed on Google Cloud) and Apigee hybrid, both share the same modern API (apigee.googleapis.com) and feature set. The difference comes down to who runs the runtime plane.

Product	Where Hosted	Managed By
Apigee	Google Cloud	Apigee manages both the management plane and the runtime plane
Apigee hybrid	Both Google Cloud and your private data centre or cloud	Apigee manages the management plane and you manage the runtime plane

Platform Feature Breakdown

Here is a practical look at how the core features work across Apigee and Apigee hybrid, and what you need to know when building on them:

Feature	How It Works in Apigee & Hybrid	What Our Engineers Do With It
API Proxy Revisions	Revisions are immutable once deployed. You cannot edit a live revision in place.	We enforce strict GitOps CI/CD pipelines so every change deploys a new versioned revision.
Deployments	Asynchronous deployments. Status is based on the last time the runtime plane checked in with the management plane.	We script deployment polling checks into Cloud Build and GitHub Actions before shifting traffic.
Environments & Topology	Supports environment groups via UI and APIs. Each Message Processor (MP) pod can only serve one environment.	We size MP pod pools per environment so a noisy staging test never starves production pods.
gRPC Proxy Support	Processes unary gRPC protocol API requests to a gRPC target server.	Lets us front high speed internal Go and Python gRPC services alongside standard REST APIs.
Encrypted KVMs & Property Sets	Environment scoped KVMs are always encrypted. You cannot view or edit KVM entries in the UI; you use the keyvaluemaps.entries API or KeyValueMapOperations policy with a dynamic <MapName> element, or use property sets.	We prefix all sensitive KVM lookups with private. during GET operations so secrets never leak in decrypted form during a debug (Trace) session.
Keystores & Truststores	Northbound TLS keys and certs are managed as Kubernetes secrets in hybrid (via Anthos Service Mesh), or via instance HTTPS endpoints in Apigee.	We automate certificate rotation through Secret Manager and Kubernetes secrets so certs never expire silently.
Identity, Roles & OAuth	Roles and permissions are managed through Google Cloud IAM (curated and custom roles). Includes the new RevokeOAuthv2 policy to revoke tokens by end user ID, app ID, or both.	Ties Apigee access directly into your Google Cloud landing zone IAM and gives you an instant kill switch for compromised user or agent tokens.
App Ownership & Monetization	Organise client apps using AppGroups or developer app associations. Full API Monetization is supported in both Apigee and hybrid.	Cleanly separates B2B partner teams and internal business units for chargeback or commercial billing.
Trace & Debug Sessions	Asynchronous debug sessions via the Debug Session API and UI. Supports AND / OR filter logic on flow variables, up to 15 requests per MP, 5 min (API) or 10 min (UI) default timeout, with hybrid deleting trace data after 24 hours.	We make sure Synchronizer clocks are NTP synced so debug session creation requests don’t get dropped by the runtime plane.
Caching & Metrics APIs	Short lived L1 cache is created automatically when you deploy a proxy. Metrics and custom reports run on apigee.googleapis.com (userId, createdBy, and lastModifiedBy are omitted from async query and report responses).	We wire custom analytics exports into BigQuery and Looker rather than relying on deprecated daily analytics emails.

Under the Hood of the Apigee Hybrid Runtime Plane

When we deploy or upgrade Apigee hybrid in your Kubernetes cluster, here is the actual plumbing we stand up and manage:

• API Proxy Gateway (RMP): An Istio Ingress controller (via Anthos Service Mesh) hands incoming traffic to containerised Router / Message Processor (RMP) pods in the runtime plane.
• Synchronizer: Containerised pods that pull API proxy configurations, environment settings, and policy updates from the Google Cloud management plane to keep the local runtime in sync.
• Persistence (Cassandra StatefulSet): Apache Cassandra runs in Kubernetes as a StatefulSet to persist KMS, KVM, quota, and cache state on disk.
• MART (Management API Runtime Data): Apigee APIs talk to the Management Server and MART, which interacts with your local Cassandra datastore to manage runtime data entities.
• Analytics & Metrics: A data collection pod in the runtime plane uses Fluentd and UDCA (Universal Data Collection Agent) to ship analytics to the UAP (Unified Analytics Platform) in the management plane, while a single Prometheus server per cluster handles runtime metrics.

Using Apigee Between Your Data Warehouse and AI

Right now, everyone is rushing to hook AI agents and LLMs up to their enterprise data. The most common mistake we see is teams taking a well governed BigQuery data warehouse and wiring a Vertex AI agent or third party LLM straight into it with a broad service account.

That works fine in a proof of concept. In production, it is a mess. You have no token rate limiting, no prompt injection screening, no caching when twenty users ask the same question, and no way to prove to a regulator what data left the warehouse and why.

Putting Apigee between your data warehouse and your AI gives you the governance and control your security team needs to actually sign off on production AI:

1. Governance and Data Boundaries: Apigee sits in front of BigQuery and your core APIs. Every request from an AI agent has to authenticate with its own OAuth2 identity, and Model Armor screens prompts and responses so PII and sensitive records don’t leak into an LLM context window.
2. Turning Warehouse Queries into MCP Tools: Instead of letting agents write raw SQL against production tables, we expose curated data warehouse views and enterprise APIs through Apigee as Model Context Protocol (MCP) tools. Agents only see the tools they are allowed to call.
3. Token Quotas & Semantic Caching: If an agent gets stuck in a loop, Apigee’s token limit policies cut it off before it racks up a massive BigQuery and Vertex AI bill. Semantic caching serves cached answers for similar prompts in milliseconds.
4. Audit Trails for the Regulators: Every tool call, data lookup, and model response is logged with a correlation ID and streamed to Cloud Logging and Google SecOps.

We have built a dedicated page on how we use Apigee as an AI gateway. Check out our Apigee AI Gateway page under AI & Machine Learning →

How We Run an Apigee Migration

Who This Is For

• Teams on Apigee Edge or older Apigee hybrid versions that need to migrate to the new platform before Google’s decommission and end of support dates hit.
• Healthcare, finance, and regulated businesses that need strict Australian data residency, Privacy Act or APRA CPS 234 compliance, and an engineer team that has already done this at scale in Australian healthcare.
• Data and AI teams that need a proper governance and control layer sitting between BigQuery and their AI agents.

---

Why Aviato

Aviato is a Google Cloud Premier Partner and the 2026 Google Cloud Australia & New Zealand Partner of the Year. Our practice is led by ex Google Cloud architects, including our founder Ben King, who spent 6.5 years at Google Cloud leading App Modernisation for APAC Professional Services. We write clean Terraform in your repos, we don’t do vendor lock in, and if you want us to run the platform afterwards, our Managed SRE team can carry the pager.

---

Related

• Apigee AI Gateway: How we use Apigee to govern LLM traffic, enforce Model Armor, and turn enterprise APIs into MCP tools for AI agents.
• Enterprise App Modernization: Decomposing legacy monoliths and mainframes behind an Apigee Strangler Fig routing layer.
• Healthcare & Life Sciences Cloud Solutions: Compliant health data platforms, FHIR integrations, and Australian Privacy Act controls on Google Cloud.
• Data & Analytics on Google Cloud: BigQuery lakehouses and governed data products ready for API and AI consumption.
• How to Enforce Enterprise API Standards on a Tiered Budget: Our engineering guide to API consistency, idempotency, and edge abuse protection.

---

Ready to Sort Out Your Apigee Migration?

Book a 20 minute call with one of our senior Google Cloud architects. Tell us what version of Edge or hybrid you are running today, and you will walk away with a straight answer on how to migrate it, what will break, and what it will cost.

Book a Free 20 Min Architecture Call →