Multi-Cluster API Gateways After Karmada Graduation

Multi-cluster Kubernetes becomes easier to reason about when platform teams stop treating it as one feature. Workload placement, cross-cluster connectivity, public request routing, and API policy are separate control loops. Each can succeed while another is broken.

That boundary is timely because the Cloud Native Computing Foundation announced Karmada's graduation in September 2026. Karmada extends Kubernetes-style APIs across clusters and clouds, with placement, propagation, failover, and autoscaling capabilities. Graduation is evidence of project maturity and governance; it is not a guarantee that any particular multi-cluster application or traffic path is correctly configured.

For API teams, the useful architecture is not “Karmada versus an API gateway.” Karmada can decide where Kubernetes resources should exist. A service-networking layer can make backends reachable across clusters. An API gateway can authenticate clients, apply request policy, choose an in-scope upstream, and record the traffic it handles. Production reliability depends on testing the handoffs between those layers.

Key Takeaways

Separate workload placement from request routing and API policy.
Pin Karmada behavior to a version; this article uses v1.19 documentation.
Treat MultiClusterService as a v1alpha1, feature-gated option with network prerequisites, not the only multi-cluster service path.
Keep gateway policy distribution and backend discovery observable independently.
Test cluster loss, stale endpoints, policy drift, and rollback as different failure modes.
Start with one service across two clusters before standardizing a fleet-wide pattern.

Three Planes, Three Questions

A multi-cluster API architecture has at least three planes:

Plane	Primary question	Example owner
Workload placement	In which clusters should the application resources run?	Karmada policies and scheduler
Service reachability	How can a caller or gateway reach healthy backends across cluster networks?	Cluster-local Services, MultiClusterService, service networking, DNS, or another discovery layer
API traffic governance	Which external request may reach which API, under what policy, and with what evidence?	API gateway and management control plane

These planes interact, but none automatically replaces the others. A successful Karmada propagation event does not prove that a public route points to the new endpoint. A reachable cross-cluster Service does not prove that every cluster enforces the same authentication policy. A synchronized gateway policy does not prove that the selected backend is ready.

flowchart LR
    P[Karmada placement policy] --> W[Workloads in member clusters]
    W --> S[Service discovery and network reachability]
    C[API clients] --> G[Gateway policy and routing]
    G --> S
    G --> O[Request and policy evidence]

The diagram intentionally gives placement and gateway policy separate inputs. It does not imply that Karmada distributes API gateway configuration or that a gateway creates cross-cluster connectivity.

Pin the Karmada Contract to v1.19

Karmada's PropagationPolicy is namespace-scoped, while ClusterPropagationPolicy can select namespace-scoped and cluster-scoped resources. Both express placement intent, but their scope is different. The v1.19 FAQ is explicit about this distinction.

That choice is not merely stylistic. A namespace team may own a PropagationPolicy for its application, while a platform team may use a ClusterPropagationPolicy for shared resources. Before automating either path, define who can select gateway Deployments, Services, Secrets, and configuration objects. An overly broad cluster policy can propagate more than the application team expected.

Karmada v1.19 also introduced or promoted behavior with its own gates. The v1.18-to-v1.19 upgrade notes state that priority-based scheduling is Beta and enabled by default. By contrast, MultiplePodTemplatesScheduling has been available since v1.16 as an Alpha feature that is disabled by default; using it requires enabling the feature gate on karmada-controller-manager, karmada-scheduler, and karmada-webhook. Do not present that optional path—or any one scheduling path—as exhaustive when the workload type and enabled features change the result.

The PR #952 lesson applies here: keep a platform condition and its alternatives beside the main conclusion. A policy example is evidence for that resource scope and feature state, not proof that every multi-cluster deployment uses the same mechanism.

Cross-Cluster Service Access Is an Explicit Choice

Karmada v1.19 documents MultiClusterService as a networking.karmada.io/v1alpha1 resource. In the cross-cluster Service tutorial, the feature is disabled by default and must be enabled on karmada-controller-manager with MultiClusterService=true.

The same tutorial lists prerequisites that materially limit the claim:

at least two member clusters are registered;
container networks between participating clusters are connected;
Pod and Service CIDRs do not overlap;
the feature gate is enabled;
provider and consumer clusters are selected correctly.

The example uses MultiClusterService to collect and distribute EndpointSlices so a native Service name in a consumer cluster can reach provider-cluster backends. That is one documented approach. Teams may instead keep gateways and backends cluster-local, use a different multi-cluster networking project, publish regional endpoints behind DNS or a global load balancer, or integrate an external service registry. The correct choice depends on latency, fault isolation, data residency, and network ownership.

Do not enable cross-cluster endpoints merely to make every backend globally reachable. A regional API may need local processing or legal isolation. Provider and consumer selectors should encode that intent, and network policy must permit only the required flows.

Choose a Gateway Topology Deliberately

Three common gateway topologies solve different problems.

Gateway per Cluster

Each cluster runs a gateway close to its backends. DNS, a global load balancer, or another edge selects the cluster.

This topology limits the blast radius of a gateway or cluster failure and keeps most upstream traffic local. The cost is policy and certificate distribution across clusters. A central management plane can reduce drift, but each data plane still needs local readiness, connectivity, and rollback evidence.

Regional Gateways with Cross-Cluster Backends

A gateway in one cluster may reach services in several clusters through MultiClusterService or another network layer.

This can simplify the public edge, but it couples availability to inter-cluster networking. A stale or unreachable remote EndpointSlice can affect requests even when the gateway process is healthy. Timeouts and retry ownership must be explicit so a network partition does not multiply attempts across layers.

Central Gateway for Several Clusters

A shared gateway routes to backends in multiple clusters or clouds.

Centralization can simplify policy and public DNS, but it creates a larger failure and latency domain. It may also conflict with data-residency or regional isolation requirements. High availability requires more than multiple gateway replicas: the control plane, discovery inputs, secrets, network paths, and telemetry sinks all have their own failure modes.

API7 Enterprise supports centralized API management and multi-cluster operations around Apache APISIX data planes. That management scope does not remove the need to test each cluster's runtime path or Karmada's placement decisions.

Keep Policy Distribution Separate from Discovery

Gateway configuration usually includes routes, upstream references, authentication, rate limits, TLS material, and observability settings. Backend discovery tells the gateway where a service currently lives. They change at different rates and fail differently.

Track at least these states:

Desired workload placement: the Karmada policy and selected clusters.
Observed workload state: ready replicas in each member cluster.
Service discovery state: the endpoints visible to the gateway or local Service.
Gateway policy state: the route and plugins loaded by each data plane.
Traffic evidence: requests, errors, latency, policy decisions, and selected upstream.

Karmada's v1.19 event reference distinguishes policy matching, resource dispatch, MultiClusterService synchronization, and EndpointSlice dispatch events. A successful event at one stage should not close an incident at another. Pair events with metrics and an actual request through the public route.

For gateway operations, use configuration status and request telemetry rather than assuming a control-plane write reached every data plane. If a cluster is disconnected, define whether it continues serving the last accepted policy, rejects traffic, or is removed from public routing.

Test the Failure Matrix

Run counterexamples before calling the design production-ready:

Failure	Expected evidence	Decision to define
Member cluster becomes unreachable	Karmada cluster condition, missing/stale endpoints, gateway upstream errors	Remove cluster, fail over, or fail closed
Karmada control plane is unavailable	Existing workloads continue or degrade as designed	How long stale placement is acceptable
Gateway policy update fails in one cluster	Configuration status differs by data plane	Block rollout or isolate the cluster
EndpointSlice propagation lags	Ready workload exists but route cannot reach it	Readiness gate and timeout
Public edge sends traffic to an unhealthy region	Gateway may be healthy locally but API fails	Health signal consumed by edge routing
Retry occurs in edge, gateway, and client	Attempts exceed intended budget	Which layer owns retries
Rollback removes a resource too early	Old route has no reachable backend	Ordering and preservation policy

Also test a partial failure. For example, disconnect only the service network while keeping Karmada and the gateway control plane available. This catches dashboards that show green control loops while user traffic fails.

Roll Out One Service End to End

A safe pilot is deliberately small:

Select one stateless API with a clear owner and low-risk rollback.
Pin Karmada v1.19 and record the enabled feature gates.
Choose PropagationPolicy or ClusterPropagationPolicy based on the real ownership scope.
Choose cluster-local discovery, MultiClusterService, or another explicit service-networking path.
Deploy one gateway data plane per intended topology and verify its loaded policy.
Send synthetic and real canary traffic through the public entry point.
Remove one cluster or network path and confirm the documented failure behavior.
Roll back placement and gateway routing independently.

The success condition is not “the Deployment exists in two clusters.” It is that an authenticated client receives the expected API behavior, the platform can identify the serving path, and operators can recover from each failed control loop without guessing.

Treat Multi-Cluster as a Tested System

Karmada's graduation gives platform teams a mature Kubernetes-native option for multi-cluster orchestration. It does not collapse workload placement, service networking, and API governance into one product or one availability guarantee.

Use Karmada to express where resources should run. Use an explicit networking and discovery design to make selected backends reachable. Use an API gateway to enforce and observe the external request contract. Then test their handoffs under failure.

For the API layer, review API7's multi-cluster API management guidance and begin with one service, two clusters, and a failure matrix that keeps every version boundary and alternative path visible.