What is Apigee Hybrid?

Apigee hybrid lets you manage APIs across multi-cloud environments:

Manage all your APIs in one place

Apigee Hybrid helps you manage all internal and external APIs with a single platform.

With unified API management, you can provide your developers, partners, and customers a consistent API program experience.

Address security and compliance

If your compliance and security considerations make on-premises deployment a must for your applications, with an enterprise-grade Hybrid gateway, you host and manage the Apigee Hybrid runtime plane on your premises.

You manage and control the runtime, enabling you to leverage your existing compliance, governance, and security infrastructure.

Support your multi‑cloud strategy

Balancing cost and performance may lead you to a multi-cloud strategy.

Whether you are just exploring different cloud providers or have already chosen a multi-cloud strategy, your API management platform should give you the flexibility you need. Host and manage enterprise-grade Hybrid gateways across your clouds of choice.

API programs in a Hybrid/multi-cloud world

Apigee hybrid consists of a management plane maintained by Apigee in the cloud and a runtime plane that you install into Kubernetes on-premises or in a cloud-managed Kubernetes provider. In addition, both planes use Google Cloud Platform services, as the following image shows:


As you can see, Hybrid consists of the following primary components:

  • Apigee-run management plane: A set of services hosted in the cloud and maintained by Apigee. These services include the Edge UI, management API, and analytics.
  • Customer-managed runtime plane: A set of containerized runtime services that you set up and maintain in your own Kubernetes cluster. All API traffic passes through and is processed within the runtime plane.

    You manage the containerized runtime on your Kubernetes cluster for greater agility with staged rollouts, auto-scaling, and other operational benefits of containers.

  • Google Cloud Platform (GCP) Console services: A platform of resources contained in Google's data centers.

One key thing to know about Hybrid is that all API traffic is processed within the boundaries of your network and under your control, while management services such as the UI and API analytics run in the cloud and are maintained by Apigee. For more information, see Where is your data stored?

The following video provides a deep dive into the Hybrid architecture:

About the runtime plane

The runtime plane runs in a Kubenernetes cluster that you own and maintain.

The following image shows the primary services that execute on the runtime plane:


For additional information about the runtime, see:

The following sections describe each of these primary runtime plane services in more detail.

Message Processor

Hybrid Message Processors (MPs) provide API request processing and policy execution on the runtime plane. MPs load all of the deployed proxies, resources, target servers, certificates, and keystores from local storage. You configure an Istio Ingress controller to expose the MPs to requests that come from outside the cluster.


The Synchronizer fetches configuration data about an API environment from the management plane and propagates it across the runtime plane. This downloaded data is also called the contract.

The Synchronizer periodically polls the Management Server for changes and downloads a new configuration whenever changes are detected. The configuration data is retrieved and stored locally as a JSON file in a location where the Message Processors can access it.

The downloaded configuration data allows the runtime plane to function independently from the management plane. With the contract, Message Processors on the runtime plane use the locally stored data as their configuration. If the connection between the management and runtime plane goes down, services on the runtime plane continue to function.

The configuration data downloaded by the Synchronizer includes:

Cassandra datastore

Apache Cassandra is the runtime datastore that provides Core Persistence Services (CPS) for the runtime plane.

Cassandra is a distributed data system that provides data persistence on the runtime plane. You deploy the Cassandra database as a StatefulSet node pool on your Kubernetes cluster. Locating these entities close to the runtime processing services helps support requirements for security and high scalability.

The Cassandra database stores information about the following entities:

  • Key management system (KMS)
  • Key Value Map (KVM)
  • Response cache
  • OAuth
  • Quotas

Management API for Runtime data (MART)

Data that belongs to your organization and is accessed during runtime API calls, such as application configurations, Key Management System (KMS) data, cache, and Key Value Maps (KVMs), are stored by Cassandra in the runtime plane. To access and update that data—for example, to add a new KVM or to remove an environment—you can use the Hybrid UI or the Apigee APIs. The MART server (Management API for Runtime data) processes the API calls against the runtime datastore.

This section describes the role that MART plays when you call the Apigee APIs to access the runtime datastore.

What MART is

To call an Apigee API, you send an authenticated request to the Management Server (MS) on the management plane. The MS authenticates and authorizes the request, and then forwards the request to MART on the runtime plane. Attached to that request is a token that the MS generated using a pre-configured service account.

MART receives the request, authenticates and authorizes it, and then performs business validation on it. (For example, if the app is part of an API product, MART ensures it's a valid request.) After determining that a request is valid, MART then processes it.

Cassandra stores the runtime data that MART processes (it is, after all, a runtime datastore). MART might read data from the Cassandra or it might update that data, depending on the type of request.

Like most Hybrid services, MART is stateless: it does not persist its own state at runtime.

What MART is not

Even though MART exposes a port to the public cloud, you do not call MART directly. (The port must be exposed so that MART can receive calls from the MS via a service account.)

Furthermore, MART does not receive runtime calls from your customers to their API proxies; those calls are handled by the ingress controller and are routed to your cluster’s Message Processors.

It's worth pointing out that both MART and the Message Processors have access to the same runtime datastore (Cassandra), which is how data such as KMS, KVMs, and caches are shared.

The following image shows the flow of an Apigee API call:


About the management plane

The management plane is hosted in the cloud by Apigee. It includes administrative services such as:

  • Hybrid UI: Provides a UI for developers to create and deploy API proxies, configure policies, create API products, and create developer apps. Administrators can use the Edge UI to monitor deployment status.
  • Apigee APIs: Provide a programmatic interface for managing your organization and environments.
  • Unified Analytics Platform (UAP): Receives and processes analytics and deployment status data from the runtime plane.

The following image shows the primary services that execute on the management plane:


About the GCP services

The following table describes the key GCP services that Hybrid leverages:

GCP Service Description
Identity User account authentication uses Google accounts (that have accepted the GCP Terms of Service). Authorization uses GCP service accounts.
Roles Access management for Hybrid uses Google’s roles engine, IAM, and supports default Apigee roles.
Resource Hierarchy Resources are organized in GCP projects (linked to Apigee organizations).
Stackdriver Provides logging and metrics data analysis.

Types of users

Apigee has identified the following primary types of Hybrid users:

Role Typical responsibilities/tasks Areas of interest
System administrators/operators
  • Install and configure services on Hybrid's runtime plane
  • Set up GCP, Apigee, and service accounts
  • Create GCP services and projects
  • Manage the Kubernetes cluster
  • Maintain all of the above
  • Troubleshoot the API proxies
  • Build API proxies using the Hybrid UI or Apigee APIs
  • Deploy API proxies to the runtime plane
  • Troubleshoot the API proxies
  • Test the API proxies


Apigee hybrid has the following advantages:

Reduced cost of ownership
If you are an Apigee Edge for Private Cloud customer, Hybrid allows you to operate your on-premises API runtime with far fewer software services to manage and operate.
Increased agility
Because Hybrid is delivered and runs in containers, you can achieve staged rollouts, auto-scaling, and other operational benefits of a containerized system.
Reduced latency
All communication with the Hybrid management plane is asynchronous and does not happen as part of processing client API requests.
Increased API adoption
Although it is possible to process internal APIs using Edge Cloud, the reduced latency and efficiency you can achieve with Hybrid makes processing internal APIs with Hybrid an attractive option. Part of this efficiency is achieved because your API gateway runs on-premises, in close proximity to your backend services. Also, if you are on Apigee Edge Public Cloud, you can increase your adoption of Apigee by processing internal APIs through Hybrid. If you are using Edge Microgateway, you can expand your API adoption because Hybrid overcomes key limitations of Edge Microgateway.
Multi-cloud and greater control
Many enterprises are embarking on a multi-cloud strategy. The ability to manage API runtimes deployed on multiple clouds (including private data centers) is a key requirement for large enterprises. Currently, the Hybrid runtime plane can be deployed to AWS, Azure, GCP, or in your own data center.

Hybrid concepts for Edge customers

Most of the Hybrid services will sound familiar to Edge for Private Cloud customers. In general, public cloud users did not need to know about these services.

The following table lists common Edge services and how they are presented in the Edge for Public Cloud, Edge for Private Cloud, and Hybrid models:

Service Apigee Product or Feature Area
Hybrid Public Cloud Private Cloud
Analytics A data collection pod in the runtime plane uses fluentd and UDCA (Universal Data Collection Agent) to gather analytics and feed the data to the UAP (Unified Analytics Platform) in the management plane. Managed by Apigee Qpid and Postgres servers
API Proxy Gateway The Message Processor (MP) processes incoming requests. MPs are implemented as one or more containerized apps in the runtime plane. Message Processor
Core Persistence Services (CPS) Cassandra provides persistence for the KMS, KVM, quota, and cache features. Cassandra node or ring
Deployment The Synchronizer ensures that API proxy configurations, environment information, and other data is kept up to date between the management plane and runtime plane. Zookeeper
Administrative User Interface The Hybrid UI is a containerized app hosted on the management plane. The Edge UI is hosted on the Management Server
Load Balancing An Istio Ingress controller hands requests to the Router/Message Processor (RMP) containerized app in the runtime plane. Router
Management APIs Apigee APIs are accessed through the Management Server and MART. MART interacts with the local Cassandra datastore and serves as an API provider for the Apigee APIs to access and manage runtime data entities. Management Server
Metrics Managed by a single Prometheus server per cluster for all services. Each component configured with JMX

Next step

See the Big Picture—an overview of the Hybrid installation process.