This is an automated email from the ASF dual-hosted git repository.
Yilialinn pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix-website.git
The following commit(s) were added to refs/heads/master by this push:
new b427343bfd9 feat(content): add API gateway vs service mesh guide
(#2125)
b427343bfd9 is described below
commit b427343bfd9680ad9f71582544cc6d2f5bc6a112
Author: Yilia Lin <[email protected]>
AuthorDate: Tue Sep 22 09:38:55 2026 +0800
feat(content): add API gateway vs service mesh guide (#2125)
---
.../12/17/exposure-istio-with-apisix-ingress.md | 2 +
.../api-gateway-for-microservices.md | 22 +--
.../learning-center/api-gateway-vs-service-mesh.md | 154 +++++++++++++++++++++
website/learning-center/what-is-an-api-gateway.md | 4 +-
website/src/pages/comparisons.tsx | 6 +
website/static/llms.txt | 1 +
6 files changed, 168 insertions(+), 21 deletions(-)
diff --git a/blog/en/blog/2021/12/17/exposure-istio-with-apisix-ingress.md
b/blog/en/blog/2021/12/17/exposure-istio-with-apisix-ingress.md
index 0413bc33e68..4cbeab8b94b 100644
--- a/blog/en/blog/2021/12/17/exposure-istio-with-apisix-ingress.md
+++ b/blog/en/blog/2021/12/17/exposure-istio-with-apisix-ingress.md
@@ -23,6 +23,8 @@ tags: [Ecosystem]
<!--truncate-->
+For help deciding where each layer should enforce policy, see [API gateway vs
service mesh](/learning-center/api-gateway-vs-service-mesh/). The comparison
covers traffic boundaries, identity, deployment models, and combined
architectures.
+
## Service Mesh
With the hot development of Cloud-Native technology, Service Mesh is gradually
becoming popular in the microservices field. The popular implementations of
Service Mesh are [Istio](https://istio.io/) and [Linkerd](https://linkerd.io/).
diff --git a/website/learning-center/api-gateway-for-microservices.md
b/website/learning-center/api-gateway-for-microservices.md
index d2f9a071d7d..b15e88b2a7f 100644
--- a/website/learning-center/api-gateway-for-microservices.md
+++ b/website/learning-center/api-gateway-for-microservices.md
@@ -41,9 +41,9 @@ Each BFF acts as a specialized gateway layer that transforms
and filters upstrea
### Service Mesh Integration
-In architectures that deploy both an API gateway and a service mesh, the
gateway handles north-south traffic (client to cluster) while the service mesh
manages east-west traffic (service to service). The gateway provides
external-facing features like API key authentication, rate limiting, and
response transformation. The mesh handles internal concerns like mTLS, circuit
breaking, and service-to-service load balancing.
+In architectures that deploy both an API gateway and a service mesh, the
gateway often applies client- and consumer-facing API policies while the mesh
manages workload identity and service-to-service policy. This is a common
division of responsibility, not a strict traffic rule: service meshes can
provide ingress gateways, and API gateways can route internal traffic.
-Most organizations using a service mesh also deploy an API gateway with clear
boundaries between the two components. This separation avoids the complexity of
running a full mesh for external traffic while preserving mesh benefits for
internal communication.
+Whether a team needs both depends on its trust boundaries and policy model.
The [API gateway vs service mesh
comparison](/learning-center/api-gateway-vs-service-mesh/) explains the overlap
and provides a decision checklist for gateway-only, mesh-only, and combined
deployments.
## Key Features for Microservices
@@ -73,24 +73,8 @@ In a microservices architecture, a single client request
might traverse ten or m
APISIX supports trace context propagation to observability backends including
Zipkin, Jaeger, SkyWalking, and OpenTelemetry. With tracing enabled at the
gateway, operations teams gain end-to-end visibility into request flows,
enabling faster incident resolution compared to relying solely on logs and
metrics.
-## API Gateway vs Service Mesh
-
-API gateways and service meshes both manage network traffic in a microservices
architecture, but they target different communication patterns and offer
different feature sets.
-
-| Aspect | API Gateway | Service Mesh |
-|--------|------------|-------------|
-| Traffic direction | North-south (external to internal) | East-west (internal
to internal) |
-| Deployment model | Centralized proxy | Distributed sidecar proxies |
-| Primary focus | API management, external security | Internal networking,
observability |
-| Authentication | API keys, JWT, OAuth, OIDC | mTLS (identity-based) |
-| Rate limiting | Per-consumer, per-route | Per-service (less granular) |
-| Protocol support | HTTP, gRPC, WebSocket, GraphQL | TCP, HTTP, gRPC |
-| Request transformation | Yes | Typically no |
-
For services that use [gRPC](/learning-center/what-is-grpc/), the gateway must
preserve HTTP/2 and streaming behavior or explicitly translate the protocol for
clients that cannot use native gRPC.
-The two technologies are complementary, not competitive. Organizations
deploying both an API gateway and a service mesh generally report improved
overall system reliability compared to using either component alone.
-
## How Apache APISIX Supports Microservices
Apache APISIX is designed for microservices environments, offering dynamic
configuration, multi-protocol support, and native integration with cloud-native
infrastructure.
@@ -109,7 +93,7 @@ Apache APISIX is designed for microservices environments,
offering dynamic confi
### Do I need an API gateway if I already use a service mesh?
-Yes. A service mesh manages internal service-to-service communication but does
not address external API concerns like consumer authentication, API key
management, rate limiting per consumer, request transformation, or
developer-facing documentation. The API gateway handles the north-south
boundary where external clients interact with your microservices. Deploy both
for comprehensive traffic management.
+Not always. If the mesh ingress already provides the external routing and
policy model an application needs, a separate API gateway may add unnecessary
operational work. Add an API gateway when the system needs consumer-oriented
authentication, quotas, request transformation, or an API policy boundary that
is managed separately from workload policy. The [detailed gateway and service
mesh comparison](/learning-center/api-gateway-vs-service-mesh/) covers the
decision factors.
### How does an API gateway handle partial failures across microservices?
diff --git a/website/learning-center/api-gateway-vs-service-mesh.md
b/website/learning-center/api-gateway-vs-service-mesh.md
new file mode 100644
index 00000000000..1ac70cfead0
--- /dev/null
+++ b/website/learning-center/api-gateway-vs-service-mesh.md
@@ -0,0 +1,154 @@
+---
+title: "API Gateway vs Service Mesh: Differences, Overlap, and When to Use
Both"
+description: "Compare API gateways and service meshes by traffic scope,
identity, policy enforcement, deployment model, and operations, and learn when
one or both fit."
+slug: api-gateway-vs-service-mesh
+date: 2026-09-20
+tags: [api-gateway, service-mesh, microservices, architecture]
+hide_table_of_contents: false
+---
+
+An API gateway and a service mesh both control network traffic, but they
usually operate at different boundaries. An API gateway provides an API-facing
entry point and applies policies for clients and consumers. A service mesh
manages communication between workloads and can provide workload identity,
service-to-service encryption, traffic policy, and telemetry across a group of
services.
+
+The boundary is not absolute. Service meshes can include ingress and egress
gateways, while API gateways can route internal traffic. The useful question is
therefore not which product owns a direction of traffic, but which identity,
policy, and operational model each traffic path requires.
+
+## What Is an API Gateway?
+
+An [API gateway](/learning-center/what-is-an-api-gateway/) sits on the request
path between API clients and backend services. It matches requests to routes,
applies configured policies, selects an upstream, and returns the response to
the client.
+
+Common gateway responsibilities include:
+
+- authenticating API consumers with mechanisms such as API keys, JWT, OAuth
2.0, or OpenID Connect;
+- applying consumer- or route-level rate limits and quotas;
+- transforming requests and responses;
+- providing a stable API endpoint while backend locations change; and
+- emitting metrics, logs, or traces for traffic that passes through the
gateway.
+
+An API gateway does not automatically establish identity and encrypted
communication between every workload in an application. Backend services also
remain responsible for business authorization and resource-level access
decisions.
+
+## What Is a Service Mesh?
+
+A service mesh is an infrastructure layer for workload-to-workload
communication. A mesh control plane distributes configuration and identity
information to a data plane that processes service traffic. Depending on the
implementation, that data plane can use sidecar proxies, shared node proxies,
or other deployment models.
+
+Common service mesh responsibilities include:
+
+- assigning and verifying workload identities;
+- encrypting service-to-service traffic with mTLS;
+- applying traffic policies between workloads;
+- collecting telemetry for calls inside the mesh; and
+- controlling service discovery, routing, retries, and failover within the
mesh.
+
+For example, [Istio's
architecture](https://istio.io/latest/docs/ops/deployment/architecture/)
separates a control plane from a data plane that mediates traffic between
services. A mesh can also expose ingress and egress gateways, so it should not
be reduced to an east-west-only proxy layer.
+
+## API Gateway vs Service Mesh
+
+| Dimension | API Gateway | Service Mesh |
+| --- | --- | --- |
+| Primary policy subject | API client, consumer, application, or route |
Workload, service, namespace, or service account |
+| Common traffic scope | Requests entering an API boundary | Calls between
participating workloads |
+| Identity model | Client credentials, tokens, API keys, or client
certificates | Workload identity and service-to-service certificates |
+| Deployment model | Shared or dedicated gateway instances on selected traffic
paths | A control plane plus proxies or data-plane components across
participating workloads |
+| Typical policies | Authentication, consumer quotas, request transformation,
API routing | Workload authorization, mTLS, service routing, retries, and
failover |
+| Observability scope | Requests that pass through the gateway | Calls that
pass through the mesh data plane |
+| Main users | API, platform, application, and security teams | Platform,
infrastructure, and service teams |
+| API consumer semantics | Usually first-class through routes, consumers,
credentials, and quotas | Usually centered on workload and service identity |
+
+These are operating-model differences, not a universal feature checklist. Some
API gateways support mTLS, service discovery, retries, and internal routing.
Some service meshes support ingress gateways, rate limiting integrations, or
Kubernetes Gateway API resources. Product capabilities and deployment choices
determine the actual overlap.
+
+## Where Their Capabilities Overlap
+
+Both layers can influence routing, encryption, retries, timeouts, load
balancing, and observability. That overlap can be useful, but it can also
produce conflicting behavior if the same policy is configured independently in
both places.
+
+### Ingress and Egress
+
+A service mesh ingress gateway can accept traffic from outside the mesh, and
an egress gateway can control selected outbound calls. If a mesh ingress
already provides the external authentication, routing, and policy model an
application needs, a separate API gateway may not be necessary.
+
+Teams often add an API gateway when they need consumer-oriented controls such
as API keys, OAuth or OIDC integration, per-consumer quotas, request
transformation, or a stable API contract that is managed separately from mesh
workload policy.
+
+### Traffic Management
+
+API gateways and service meshes can both perform load balancing, health-aware
routing, retries, and traffic splitting. The appropriate owner depends on the
failure boundary. Gateway policy can protect an API entry point and its
upstreams, while mesh policy can govern calls deeper in a service chain.
+
+Avoid applying retries at every layer without a shared budget. A client retry,
gateway retry, mesh retry, and application retry can multiply requests during
an outage. Define which layer owns retries and timeouts for each path.
+
+### Identity and Encryption
+
+An API gateway can authenticate external callers and terminate or initiate TLS
and mTLS on the connections it owns. A service mesh can issue workload
identities and enforce mTLS between participating services. These controls
protect different trust boundaries and may be used together.
+
+Gateway-side mTLS does not by itself create mesh-wide workload identity.
Likewise, workload mTLS inside a mesh does not replace client authentication or
business authorization for a public API.
+
+## When to Use an API Gateway
+
+Use an API gateway without a service mesh when the main requirement is to
expose and control APIs, and the added operational cost of a mesh is not
justified. This is common when:
+
+- external, partner, mobile, or browser clients need a stable API endpoint;
+- teams need API authentication, consumer quotas, or request transformation;
+- the number of internal services is manageable with existing platform
networking; or
+- only selected traffic paths require centralized policy enforcement.
+
+An API gateway can also support internal APIs, but routing internal traffic
through a gateway does not automatically provide every service with a workload
identity or transparent service-to-service encryption.
+
+## When to Use a Service Mesh
+
+Use a service mesh without a separate API gateway when the primary problem is
communication among many internal workloads and the mesh ingress capabilities
already satisfy external requirements. This can fit environments that need:
+
+- consistent workload identity and service-to-service mTLS;
+- traffic and authorization policy across many services;
+- telemetry for calls that do not pass through an API gateway; or
+- common networking behavior across Kubernetes clusters, virtual machines, or
both.
+
+A mesh adds a control plane, data-plane resources, certificate lifecycle, and
additional troubleshooting paths. Teams should adopt it for explicit
workload-level requirements rather than as a default layer for every
microservices deployment.
+
+## When to Use Both
+
+Use both when the system has distinct API-consumer and workload-policy
requirements. A common arrangement is:
+
+```text
+API clients
+ |
+API gateway
+ |
+Mesh ingress or service endpoint
+ |
+Service mesh workloads
+```
+
+In this design, the API gateway can own client authentication, API routing,
consumer limits, and transformations. The service mesh can own workload
identity, service-to-service mTLS, and policies for calls inside the mesh.
+
+The exact handoff differs by platform. A mesh gateway may receive traffic
directly from the API gateway, or the API gateway may participate in the mesh
through an integration supported by the mesh. Document the trust boundary, the
source identity passed downstream, and which layer owns TLS, retries, timeouts,
and telemetry.
+
+## How Apache APISIX Fits with a Service Mesh
+
+Apache APISIX is an open-source API gateway, not a complete service mesh. It
can provide API-facing routing and policies, then forward requests to services
that participate in a mesh.
+
+For traffic that passes through APISIX, teams can configure:
+
+- [Routes](/docs/apisix/terminology/route/) and
[Consumers](/docs/apisix/terminology/consumer/) for API and caller-oriented
policy;
+- authentication, rate limiting, transformation, and observability plugins;
+- [Upstreams](/docs/apisix/terminology/upstream/) for load balancing and retry
behavior; and
+- [service discovery integrations](/docs/apisix/discovery/) for supported
registries.
+
+APISIX also supports active and passive [upstream health
checks](/docs/apisix/tutorials/health-check/). These gateway capabilities do
not replace mesh-wide workload identity, sidecar or ambient data planes, or
automatic service-to-service mTLS.
+
+If a deployment uses APISIX with a mesh, align the two systems before
production rollout:
+
+1. Choose one owner for client identity and one owner for workload identity.
+2. Decide where TLS terminates and where new encrypted connections begin.
+3. Set one retry and timeout budget for the complete request path.
+4. Preserve request and trace context across the gateway-to-mesh boundary.
+5. Test failure behavior when either the gateway or mesh control plane is
unavailable.
+
+The Apache APISIX blog includes an [APISIX Ingress and Istio integration
walkthrough](/blog/2021/12/17/exposure-istio-with-apisix-ingress/). It
demonstrates the architectural handoff, although its version-specific commands
should be checked against current APISIX Ingress Controller and Istio
documentation before use.
+
+## Decision Checklist
+
+Before choosing one layer or both, answer these questions:
+
+- Are policies attached primarily to API consumers or to workloads?
+- Which traffic paths need identity and encryption?
+- Do internal calls bypass the API gateway?
+- Does the mesh ingress satisfy the required external API policies?
+- Which layer owns retries, timeouts, and traffic splitting?
+- Can the team operate and troubleshoot both control planes?
+- How will identity and trace context cross the gateway-to-mesh boundary?
+
+An API gateway and a service mesh are complementary when they enforce policies
for different identities and traffic paths. They become redundant when both
layers are deployed without a clear ownership model. Start with the required
trust boundaries and operational responsibilities, then add only the
infrastructure needed to enforce them.
diff --git a/website/learning-center/what-is-an-api-gateway.md
b/website/learning-center/what-is-an-api-gateway.md
index 422dfaa2f98..487a123d917 100644
--- a/website/learning-center/what-is-an-api-gateway.md
+++ b/website/learning-center/what-is-an-api-gateway.md
@@ -17,7 +17,7 @@ faq:
An API gateway adds another network hop and executes policies before
forwarding a request, so it always adds some latency. The actual overhead
depends on deployment topology, TLS settings, enabled plugins, request and
response transformations, and logging. Benchmark the gateway with the same
policy chain and traffic profile you expect in production rather than relying
on a universal latency figure.
- q: "Can an API gateway replace a service mesh?"
a: >-
- An API gateway and a service mesh usually serve different traffic
boundaries. The gateway handles north-south traffic from API clients to
services, while a service mesh focuses on east-west service-to-service
communication. Apache APISIX can expose and control APIs at a cluster edge, but
that does not replace mesh capabilities such as workload identity and
service-to-service mTLS.
+ An API gateway and a service mesh usually serve different policy
boundaries. A gateway commonly applies client- and consumer-facing API
policies, while a service mesh focuses on workload identity and
service-to-service communication. Apache APISIX can expose and control APIs at
a cluster edge, but that does not replace mesh capabilities such as workload
identity and service-to-service mTLS.
- q: "Is an API gateway the same as an API management platform?"
a: >-
No. An API gateway is the runtime component that processes API traffic.
API management is a broader category that can include a gateway, developer
onboarding, API documentation, lifecycle governance, and analytics. Apache
APISIX provides the open-source gateway layer; teams can integrate it with the
other tools required for their API lifecycle.
@@ -204,7 +204,7 @@ An API gateway adds another network hop and executes
policies before forwarding
### Can an API gateway replace a service mesh?
-An API gateway and a service mesh usually serve different traffic boundaries.
The gateway handles north-south traffic from API clients to services, while a
service mesh focuses on east-west service-to-service communication. Apache
APISIX can expose and control APIs at a cluster edge, but that does not replace
mesh capabilities such as workload identity and service-to-service mTLS.
+An API gateway and a service mesh usually serve different policy boundaries. A
gateway commonly applies client- and consumer-facing API policies, while a
service mesh focuses on workload identity and service-to-service communication.
Apache APISIX can expose and control APIs at a cluster edge, but that does not
replace mesh capabilities such as workload identity and service-to-service
mTLS. See [API gateway vs service
mesh](/learning-center/api-gateway-vs-service-mesh/) for the areas of [...]
### Is an API gateway the same as an API management platform?
diff --git a/website/src/pages/comparisons.tsx
b/website/src/pages/comparisons.tsx
index 2794c08ddf8..09db0f96af8 100644
--- a/website/src/pages/comparisons.tsx
+++ b/website/src/pages/comparisons.tsx
@@ -68,6 +68,12 @@ const COMPARISONS: Comparison[] = [
'Runtime traffic control vs the broader API lifecycle, and when an
organization needs both.',
to: '/learning-center/api-gateway-vs-api-management/',
},
+ {
+ title: 'API gateway vs service mesh',
+ description:
+ 'API consumer policies vs workload communication, where the capabilities
overlap, and when to use both.',
+ to: '/learning-center/api-gateway-vs-service-mesh/',
+ },
{
title: 'Kubernetes API gateway',
description:
diff --git a/website/static/llms.txt b/website/static/llms.txt
index d077e3379c4..d15dda99dd8 100644
--- a/website/static/llms.txt
+++ b/website/static/llms.txt
@@ -59,6 +59,7 @@
- [What is an API
Gateway?](https://apisix.apache.org/learning-center/what-is-an-api-gateway/):
Definition, benefits, and use cases
- [API Gateway vs API Management: Key
Differences](https://apisix.apache.org/learning-center/api-gateway-vs-api-management/):
Runtime gateway capabilities compared with full API lifecycle management
+- [API Gateway vs Service Mesh: Differences, Overlap, and When to Use
Both](https://apisix.apache.org/learning-center/api-gateway-vs-service-mesh/):
API consumer policies compared with workload communication, including overlap
and combined architectures
- [API Governance: Framework and Best
Practices](https://apisix.apache.org/learning-center/api-governance/):
Design-time and runtime governance, operating models, and implementation
practices
- [API Gateway Authentication: Methods, Best Practices &
Implementation](https://apisix.apache.org/learning-center/api-gateway-authentication/):
Auth at gateway layer (JWT, OAuth2, mTLS, HMAC)
- [API Gateway for Microservices: Architecture, Patterns & Best
Practices](https://apisix.apache.org/learning-center/api-gateway-for-microservices/):
Microservices architecture with API gateway
