Why legacy Edge and hybrid can’t be left alone
If an API gateway routes traffic and doesn’t page anyone at 3am, it is tempting to leave it. But Google is decommissioning older Apigee hybrid versions and retiring legacy Apigee Edge tooling. If you run Apigee Edge (SaaS or Private Cloud OPDK) or an older hybrid runtime tied to deprecated Kubernetes and Istio releases, staying put stops being an option. Once your version drops out of support you lose security patches, bug fixes and GKE compatibility, which is a real compliance risk in front of customer or clinical data.
We recently completed this migration for a large Australian healthcare provider, moving them onto the new Apigee platform as Google decommissioned their old hybrid environment. We moved their clinical and patient APIs across with zero cutover downtime and full Australian Privacy Act compliance.
What breaks when you migrate
Migrating from Edge or an old hybrid install is not just exporting proxy bundles and importing them into a new org. These are the issues that usually catch teams out:
- HTTP/1.1 headers are forced to lowercase. The new runtime lowercases all HTTP/1.1 header names sent to backend targets. A legacy backend that expects
X-Customer-IDin mixed case will silently break. - No Node.js proxies or SOAP wizard. Legacy Node.js proxies are gone; Node.js apps run as separate containers on Kubernetes or Cloud Run. The SOAP proxy wizard is gone too, so you use the open source
wsdl2apigeeutility. - Envoy replaces the Istio adapter. The Apigee Adapter for Istio is deprecated in favour of the Apigee Adapter for Envoy.
- One MP pod per environment. A Message Processor (MP) pod serves a single environment. Routing is organised 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. Underscore query parameters (like_optimal=true) are not supported,created_by,modified_byandselfare stripped from payloads, key timestamps are strings ({"createdAt": "1234"}), and cache API operations only support list and delete (returning204 No Content).
How we implement Apigee, Edge and hybrid
We work across all three setups, depending on where your workloads run and what your network team allows.
Apigee (hosted on Google Cloud)
Google hosts and manages both the management and runtime planes. We connect it to your VPC with Private Service Connect, so there are no Kubernetes clusters for you to run.
Apigee hybrid upgrades and builds
The management plane runs in Google Cloud and you run the runtime plane on Kubernetes in your own data centre or cloud. We upgrade old hybrid clusters before they go out of support and automate the runtime in Terraform.
Apigee Edge migrations
Moving off Apigee Edge SaaS or Private Cloud (OPDK). We assess your proxies, rewrite deprecated policies, migrate encrypted KVMs and developer apps, and shift traffic gradually with zero downtime.
Apigee and Apigee hybrid compared
Apigee (fully managed on Google Cloud) and Apigee hybrid share the same API (apigee.googleapis.com) and feature set. The difference is 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 features
How the core features work in both, and what we do with 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 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 & Monetisation | 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. |
Inside the Apigee hybrid runtime plane
When we deploy or upgrade Apigee hybrid in your Kubernetes cluster, these are the components we set 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
StatefulSetto 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.
Apigee between your data warehouse and AI
The most common mistake we see is a well governed BigQuery data warehouse wired straight to a Vertex AI agent or third party LLM with a broad service account. It works in a proof of concept. In production there is no token rate limiting, no prompt injection screening, no caching when twenty users ask the same question, and no way to show a regulator what data left the warehouse and why.
We put Apigee in the middle:
- Data boundaries: BigQuery, FHIR clinical stores and transactional databases stay inside a VPC Service Controls perimeter with no direct agent access. Every agent request authenticates with its own OAuth2 identity, and Model Armor screens prompts and responses so PII does not leak into an LLM context window.
- Warehouse queries as MCP tools: Instead of letting agents write raw SQL against production tables, we expose curated views and APIs as Model Context Protocol (MCP) tools. Agents only see the tools they are allowed to call, and can discover them in Apigee API Hub.
- Token quotas and semantic caching: Token limit policies stop a looping agent before it runs up a large BigQuery and Vertex AI bill, and semantic caching answers similar prompts from cache.
- Audit trails: Every tool call, data lookup and model response is logged with a correlation ID and sent to Cloud Logging and Google SecOps.
More detail is on our Apigee AI Gateway page.
How we run a migration
- Audit your current estate: Automated assessment of your Edge or hybrid setup. We map every proxy, shared flow, KVM, target server and policy, and flag what will break on the new platform (lowercase HTTP/1.1 headers, Istio adapters, Node.js proxies).
- Build the new platform in Terraform: A new Apigee org or upgraded hybrid runtime (Cassandra StatefulSets, Synchronizer, MART, UDCA and Envoy or Anthos Service Mesh ingress), connected to Google Cloud IAM and Cloud Armor.
- Refactor proxies and set up CI/CD: We refactor incompatible proxies, migrate encrypted KVMs and AppGroups, load your specs into API Hub, and add automated regression tests in Cloud Build or GitHub Actions.
- Parallel run and cutover: The new platform runs alongside the old one while we shift traffic in stages with canary routing, until all production traffic has moved and the old servers can be switched off.
Who this is for
- Teams on Apigee Edge or older hybrid versions that need to move before Google’s end of support dates.
- Healthcare, finance and other regulated organisations that need Australian data residency, Privacy Act or APRA CPS 234 compliance, and a team that has done this migration in Australian healthcare.
- Data and AI teams that need a governance layer between BigQuery and their AI agents.
Why Aviato
Aviato is a Google Cloud Premier Partner and the 2026 Google Cloud Australia and New Zealand Partner of the Year. Our practice is led by former 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 Terraform in your repositories, avoid vendor lock in, and our managed SRE team can run the platform afterwards if you want.
Related
- Apigee AI Gateway: governing LLM traffic, enforcing Model Armor and turning enterprise APIs into MCP tools for agents.
- Enterprise app modernisation: breaking up legacy monoliths and mainframes behind an Apigee strangler fig routing layer.
- Healthcare and life sciences: compliant health data platforms, FHIR integrations and Australian Privacy Act controls on Google Cloud.
- Data and analytics on Google Cloud: BigQuery lakehouses and governed data products ready for API and AI use.
- How to enforce enterprise API standards on a tiered budget: API consistency, idempotency and edge abuse protection.
Talk to an architect
Book a 20 minute call with a senior Google Cloud architect. Tell us which version of Edge or hybrid you run, and we will tell you how to migrate it, what will break and what it will cost.
Talk to an architect who has done this before.
Bring your current setup and the outcome you need. You will get a view on the approach, the risks and roughly what it costs.
Straight to a senior GCP architect. No SDR, no slide deck.
Not ready to talk? See how we migrated Hapana off AWS →
Or call +61 2 8359 9507 · Hello@aviato.consulting