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 e43c5f91179 fix(seo): consolidate microservices content and improve
rate-limit discovery (#2130)
e43c5f91179 is described below
commit e43c5f9117982439f7bf441b094983f6090b547d
Author: Yilia Lin <[email protected]>
AuthorDate: Mon Sep 28 18:02:04 2026 +0800
fix(seo): consolidate microservices content and improve rate-limit
discovery (#2130)
---
.htaccess | 3 +-
.../19/why-do-microservices-need-an-api-gateway.md | 152 ---------------------
.../2024/07/25/different-rate-limits-apisix.md | 4 +-
next/scripts/check-historical-doc-signals.mjs | 6 +-
.../fixtures/non-indexed-content-decisions.mjs | 5 +
.../api-gateway-for-microservices.md | 89 +++++++++---
.../learning-center/api-gateway-rate-limiting.md | 2 +-
7 files changed, 83 insertions(+), 178 deletions(-)
diff --git a/.htaccess b/.htaccess
index 5e324a00f93..ff239e7de1b 100644
--- a/.htaccess
+++ b/.htaccess
@@ -167,7 +167,8 @@ RedirectMatch 301
"^/zh/docs/java-plugin-runner/0\.1/the-internal-of-apisix-java
RedirectMatch 301 "^/blog/2023/12/01/datavisor-uses-apisix/?$"
"/blog/2023/12/19/datavisor-uses-apisix/"
RedirectMatch 301
"^/zh/blog/2021/08/16/using-the-apache-apisix-openid-connect-plugin-for-centralized-authentication/?$"
"/zh/blog/2021/08/25/using-the-apache-apisix-openid-connect-plugin-for-centralized-authentication/"
RedirectMatch 301 "^/zh/blog/2021/10/29/extension-guide/?$"
"/zh/blog/2021/10/26/extension-guide/"
-RedirectMatch 301
"^/blog/2023/03/08/why-do-microservices-need-an-api-gateway/?$"
"/blog/2023/05/19/why-do-microservices-need-an-api-gateway/"
+RedirectMatch 301
"^/blog/2023/03/08/why-do-microservices-need-an-api-gateway/?$"
"/learning-center/api-gateway-for-microservices/"
+RedirectMatch 301
"^/blog/2023/05/19/why-do-microservices-need-an-api-gateway/?$"
"/learning-center/api-gateway-for-microservices/"
RedirectMatch 301
"^/zh/blog/2020/12/16/another-way-to-implement-envoy-filter/?$"
"/blog/2020/12/16/another-way-to-implement-envoy-filter/"
RedirectMatch 301 "^/blog/2023/12/08/zhengcaiyun-uses-apisix/?$"
"/blog/2023/12/26/zhengcaiyun-uses-apisix/"
RedirectMatch 301 "^/blog/2021/09/29/release-apache-apisix-2\.10-en/?$"
"/blog/2021/09/29/release-apache-apisix-2.10/"
diff --git
a/blog/en/blog/2023/05/19/why-do-microservices-need-an-api-gateway.md
b/blog/en/blog/2023/05/19/why-do-microservices-need-an-api-gateway.md
deleted file mode 100644
index b5a39504855..00000000000
--- a/blog/en/blog/2023/05/19/why-do-microservices-need-an-api-gateway.md
+++ /dev/null
@@ -1,152 +0,0 @@
----
-title: Why Microservices Use an API Gateway
-authors:
- - name: API7.ai
- title: Author
- url: https://github.com/api7
- image_url: https://avatars.githubusercontent.com/u/61078451?s=200&v=4
-keywords:
- - Apache APISIX
- - Microservices
- - Microservices API Gateway
- - API Gateway Architecture
-description: Learn when microservices need an API gateway, which
responsibilities belong at the gateway, and when a simpler alternative is
enough.
-tags: [Ecosystem]
-image:
https://static.apiseven.com/uploads/2023/02/16/CHqaC3Xw_Ecosystem%20%E6%A8%A1%E6%9D%BF1.png
----
-
-An API gateway can give clients one entry point to a set of microservices and
apply shared traffic policies before requests reach those services. It is
useful in many microservice systems, but it is not a requirement for every
architecture. The decision depends on client exposure, traffic policies, team
ownership, and operational complexity.
-
-<!--truncate-->
-
-## What Is a Microservice Architecture?
-
-A microservice architecture divides an application into independently
deployable services organized around business capabilities. Services commonly
communicate through synchronous APIs, asynchronous messages, or both.
-
-This approach can let teams release and scale parts of a system independently.
It also introduces distributed-system concerns: network failures, service
discovery, end-to-end observability, identity propagation, versioning, and
consistency across service boundaries. A gateway addresses some edge-traffic
concerns, but it does not solve every microservice challenge.
-
-## What Does an API Gateway Do?
-
-An API gateway receives client traffic, matches it to a route, and proxies it
to an upstream service. Depending on the gateway and its configuration, it can
also apply policies such as:
-
-- client authentication and coarse-grained authorization;
-- rate limits, request-size limits, and other traffic controls;
-- TLS termination and certificate management;
-- request or response transformation;
-- load balancing and health-based routing;
-- metrics, access logs, and tracing integration;
-- canary or weighted routing between service versions.
-
-The gateway is part of the request path. Its availability, capacity,
configuration security, and failure behavior therefore need the same
engineering attention as other production infrastructure.
-
-## Why Put a Gateway in Front of Microservices?
-
-### Give external clients a stable entry point
-
-Without a gateway or another edge proxy, clients may need to know the location
and interface of each exposed service. A gateway can keep internal service
addresses private and present stable public routes while services move or scale
behind it.
-
-This indirection helps, but it is not a substitute for API versioning and
compatibility. A gateway can route versions; service owners still need to
design and deprecate interfaces deliberately.
-
-### Apply shared edge policies consistently
-
-Authentication, traffic limits, request validation, and telemetry often need a
consistent enforcement point. Implementing the same edge policy independently
in every service can produce drift and repeated maintenance.
-
-Centralization should be selective. Business authorization rules usually
require domain context and often belong in the service as well. A gateway check
does not remove the need for service-to-service identity, authorization, or
input validation behind the gateway.
-
-### Protect upstream capacity
-
-Rate limits, concurrency controls, timeouts, and circuit-breaking policies can
reject or contain some harmful traffic before it consumes service capacity.
These policies must be based on measured service limits and realistic failure
modes. A rate limit alone cannot guarantee availability, and an incorrectly
configured retry policy can amplify an outage.
-
-### Improve traffic visibility
-
-A gateway can generate consistent access logs and traffic metrics for requests
that pass through it. Distributed traces can then connect gateway spans with
downstream services when trace context is propagated correctly.
-
-Gateway telemetry is only one view. It does not reveal internal asynchronous
work or service-to-service calls that bypass the gateway, so services and
message infrastructure still need their own instrumentation.
-
-### Change routing without changing clients
-
-Gateways can support weighted traffic splitting, header-based routing, and
controlled migration between upstream versions. This is useful for canary
releases and service decomposition, provided that the configuration is
reviewed, tested, and easy to roll back.
-
-## When You May Not Need an API Gateway
-
-A gateway adds another component and another policy layer. A simpler option
may be sufficient when:
-
-- the system has one internal client and only a few services;
-- no API is exposed outside a trusted network boundary;
-- an existing ingress proxy already provides the required routing and TLS
features;
-- service-mesh ingress or a cloud load balancer covers the current use case;
-- the team cannot yet operate the gateway reliably.
-
-Direct client-to-service access, a reverse proxy, an ingress controller, and a
gateway are design choices with overlapping capabilities. Start from concrete
requirements rather than adding a gateway because the architecture is called
“microservices.”
-
-## Gateway Responsibilities vs Service Responsibilities
-
-Clear ownership prevents a gateway from becoming a monolithic business-logic
layer.
-
-| Concern | Typical gateway role | Typical service role |
-| --- | --- | --- |
-| Authentication | Validate supported client credentials or tokens | Enforce
identity requirements for internal calls where needed |
-| Authorization | Apply route- or consumer-level policy | Enforce resource-
and domain-level permissions |
-| Rate limiting | Protect shared entry points and upstream capacity | Apply
business quotas or workload-specific limits |
-| Validation | Enforce basic protocol, size, or schema constraints | Validate
domain rules and state transitions |
-| Observability | Record edge traffic and propagate trace context | Instrument
internal work and business outcomes |
-| Composition | Perform limited protocol or payload adaptation | Own workflows
and business orchestration |
-
-Avoid putting long-running orchestration or domain decisions in gateway
plugins merely to centralize them. That increases coupling and makes the
traffic layer harder to operate and test.
-
-## Common Architecture Risks
-
-### A single unmanaged gateway failure domain
-
-Deploy enough data-plane capacity across appropriate failure domains, define
health checks, and test behavior when the control plane or configuration store
is unavailable. “Using a gateway” does not itself create high availability.
-
-### One policy for every service
-
-Different upstreams have different latency, capacity, data sensitivity, and
client behavior. Use route- or consumer-specific controls where the risk
justifies them, and preserve an auditable default policy.
-
-### Treating the gateway as the only security boundary
-
-Protect administrative APIs and configuration stores, restrict network access,
rotate secrets, and secure service-to-service communication. Services should
not blindly trust client-controlled identity headers; the architecture must
ensure those headers are removed or set only by a trusted component.
-
-### Unbounded gateway customization
-
-Plugins run in a critical traffic component. Review custom code, constrain
network and secret access, test failure behavior, and keep expensive or
blocking work out of the request path.
-
-## Using Apache APISIX with Microservices
-
-[Apache APISIX](https://apisix.apache.org/) is an open-source API gateway that
provides dynamic routing and a plugin model for traffic management,
authentication, observability, and protocol handling. It can run as a gateway
for services deployed on virtual machines, containers, or Kubernetes, depending
on the selected deployment architecture.
-
-A practical evaluation should verify:
-
-1. how routes and upstreams are configured and promoted between environments;
-2. which authentication and authorization model protects each API;
-3. how APISIX discovers or receives updates about service endpoints;
-4. what telemetry is exported and how sensitive data is handled;
-5. how the data plane behaves during upstream, network, and control-plane
failures;
-6. how upgrades, backups, rollbacks, and incident response are performed.
-
-Start with the [APISIX getting-started
guide](https://apisix.apache.org/docs/apisix/getting-started/) and evaluate
only the [plugins](https://apisix.apache.org/docs/apisix/plugins/) required by
the workload. Fewer well-tested policies are safer than enabling features
without a clear owner.
-
-## Frequently Asked Questions
-
-### Do all microservices need to pass through one gateway?
-
-No. External or north-south traffic commonly enters through a gateway, while
internal service-to-service traffic may use direct discovery, a service mesh,
or another controlled path. The topology should reflect trust boundaries and
operating requirements.
-
-### Is an API gateway the same as a service mesh?
-
-No. Their capabilities can overlap, but a gateway usually focuses on
client-to-service entry traffic and API policies. A service mesh generally
focuses on communication between workloads. Some systems use both; smaller
systems may need only one.
-
-### Does a gateway remove authentication code from every service?
-
-It can centralize supported client authentication, but services may still need
authorization and identity checks, especially for internal calls and
resource-level permissions. Design explicit trust and identity propagation
rules.
-
-### Can an API gateway orchestrate multiple microservices?
-
-Some gateways can transform or chain requests through plugins, but business
workflows are usually easier to test and own in an application or orchestration
service. Keep gateway composition limited and measurable.
-
-## Conclusion
-
-Microservices do not automatically require an API gateway. A gateway is
valuable when a system needs a stable entry point, consistent edge policies,
upstream protection, traffic observability, or controlled routing across many
services. It is unnecessary overhead when simpler infrastructure already
satisfies those requirements.
-
-Define the boundary, assign each policy to the gateway or service
deliberately, and test the complete failure model before making the gateway a
critical production dependency.
diff --git a/blog/en/blog/2024/07/25/different-rate-limits-apisix.md
b/blog/en/blog/2024/07/25/different-rate-limits-apisix.md
index 2ce7de63c7a..6ee257b0a09 100644
--- a/blog/en/blog/2024/07/25/different-rate-limits-apisix.md
+++ b/blog/en/blog/2024/07/25/different-rate-limits-apisix.md
@@ -1,5 +1,5 @@
---
-title: Differentiating rate limits in Apache APISIX
+title: Rate Limiting by Consumer and Consumer Group in Apache APISIX
authors:
- name: Nicolas Fränkel
title: Author
@@ -11,7 +11,7 @@ keywords:
- Consumer
- Consumer Groups
description: >
- In my talk Evolving your APIs, I mention that an API Gateways is a Reverse
Proxy "on steroids". One key difference between the former and the latter is
that the API Gateway is not unfriendly to business logic. The poster child is
rate-limiting.
+ Configure route-level, per-consumer, and shared consumer-group rate limits
in Apache APISIX with key authentication and the limit-count plugin.
tags: [Ecosystem]
image:
https://static.apiseven.com/uploads/2024/07/27/U4BZicm8_speedometer-1249610.jpg
---
diff --git a/next/scripts/check-historical-doc-signals.mjs
b/next/scripts/check-historical-doc-signals.mjs
index 7f0d445cf83..4bf788907b7 100644
--- a/next/scripts/check-historical-doc-signals.mjs
+++ b/next/scripts/check-historical-doc-signals.mjs
@@ -71,7 +71,8 @@ const coverageRedirects = [
['^/blog/2023/12/01/datavisor-uses-apisix/?$',
'/blog/2023/12/19/datavisor-uses-apisix/'],
['^/zh/blog/2021/08/16/using-the-apache-apisix-openid-connect-plugin-for-centralized-authentication/?$',
'/zh/blog/2021/08/25/using-the-apache-apisix-openid-connect-plugin-for-centralized-authentication/'],
['^/zh/blog/2021/10/29/extension-guide/?$',
'/zh/blog/2021/10/26/extension-guide/'],
- ['^/blog/2023/03/08/why-do-microservices-need-an-api-gateway/?$',
'/blog/2023/05/19/why-do-microservices-need-an-api-gateway/'],
+ ['^/blog/2023/03/08/why-do-microservices-need-an-api-gateway/?$',
'/learning-center/api-gateway-for-microservices/'],
+ ['^/blog/2023/05/19/why-do-microservices-need-an-api-gateway/?$',
'/learning-center/api-gateway-for-microservices/'],
['^/zh/blog/2020/12/16/another-way-to-implement-envoy-filter/?$',
'/blog/2020/12/16/another-way-to-implement-envoy-filter/'],
['^/blog/2023/12/08/zhengcaiyun-uses-apisix/?$',
'/blog/2023/12/26/zhengcaiyun-uses-apisix/'],
['^/blog/2021/09/29/release-apache-apisix-2\\.10-en/?$',
'/blog/2021/09/29/release-apache-apisix-2.10/'],
@@ -90,7 +91,8 @@ const coverageRedirects = [
const coverageRedirectCases = [
['/blog/2021/09/29/release-apache-apisix-2.10-en',
'/blog/2021/09/29/release-apache-apisix-2.10/'],
['/blog/2022/10/28/apisix-ingress-with-horizon-ai/',
'/zh/blog/2022/10/28/apisix-ingress-with-horizon-ai/'],
- ['/blog/2023/03/08/why-do-microservices-need-an-api-gateway/',
'/blog/2023/05/19/why-do-microservices-need-an-api-gateway/'],
+ ['/blog/2023/03/08/why-do-microservices-need-an-api-gateway/',
'/learning-center/api-gateway-for-microservices/'],
+ ['/blog/2023/05/19/why-do-microservices-need-an-api-gateway/',
'/learning-center/api-gateway-for-microservices/'],
['/blog/2023/07/12/2023-apisix-meetup-malaysia/',
'/blog/2023/07/11/2023-apisix-meetup-malaysia/'],
['/blog/2023/12/01/datavisor-uses-apisix/',
'/blog/2023/12/19/datavisor-uses-apisix/'],
['/blog/2023/12/08/zhengcaiyun-uses-apisix/',
'/blog/2023/12/26/zhengcaiyun-uses-apisix/'],
diff --git a/next/tests/fixtures/non-indexed-content-decisions.mjs
b/next/tests/fixtures/non-indexed-content-decisions.mjs
index d298495e3ab..1eb7ff5f5f0 100644
--- a/next/tests/fixtures/non-indexed-content-decisions.mjs
+++ b/next/tests/fixtures/non-indexed-content-decisions.mjs
@@ -9,6 +9,11 @@ export const NON_INDEXED_CONTENT_DECISIONS = [
destination: '/learning-center/open-source-api-gateway-comparison/',
removedFile:
'blog/en/blog/2022/09/13/why-is-apache-apisix-the-best-api-gateway.md',
},
+ {
+ source: '/blog/2023/05/19/why-do-microservices-need-an-api-gateway/',
+ destination: '/learning-center/api-gateway-for-microservices/',
+ removedFile:
'blog/en/blog/2023/05/19/why-do-microservices-need-an-api-gateway.md',
+ },
{
source: '/blog/2024/02/13/apisix-owasp-coraza-core-ruleset/',
destination: '/blog/2023/09/08/APISIX-integrates-with-Coraza/',
diff --git a/website/learning-center/api-gateway-for-microservices.md
b/website/learning-center/api-gateway-for-microservices.md
index b829111435e..5d18e97ad0a 100644
--- a/website/learning-center/api-gateway-for-microservices.md
+++ b/website/learning-center/api-gateway-for-microservices.md
@@ -1,23 +1,35 @@
---
title: "API Gateway for Microservices: Architecture, Patterns & Best Practices"
-description: "Learn why microservices need an API Gateway and how Apache
APISIX handles routing, discovery, load balancing, retries, and traffic
control."
+description: "Learn when microservices benefit from an API gateway, when a
simpler alternative is enough, how responsibilities split, and how to evaluate
Apache APISIX."
slug: api-gateway-for-microservices
date: 2026-04-14
tags: [microservices, architecture, api-gateway]
hide_table_of_contents: false
---
-Microservices architectures often use an [API
gateway](/learning-center/what-is-an-api-gateway/) as a single entry point for
API consumers and to route requests to the correct backend services. For
high-traffic REST APIs, the gateway can keep a stable client-facing endpoint
while it applies routing, load balancing, retries, and traffic control behind
the scenes. It also centralizes access control, authentication and
authorization, protocol translation, rate limiting, and observability, s [...]
+Microservices architectures often use an [API
gateway](/learning-center/what-is-an-api-gateway/) as a stable entry point for
API consumers and to route requests to the correct backend services. The
gateway can apply shared edge policies such as client authentication, rate
limiting, protocol translation, and traffic observability. Services still own
business authorization, domain validation, and telemetry for work that happens
behind or outside the gateway.
## Why Microservices Need a Gateway
A microservices architecture decomposes a monolithic application into
independently deployable services, each owning a specific business domain.
While this approach improves development velocity and scaling flexibility, it
introduces operational challenges that compound as the number of services grows.
-Without a gateway, every client must know the network location of every
service it needs. A single mobile application screen might require data from
five different services, forcing the client to manage multiple connections,
handle partial failures, and aggregate responses. As organizations scale their
microservices fleets, client-side orchestration becomes impractical.
+Without a gateway or an equivalent edge or composition layer, clients may need
to know and coordinate calls to several service endpoints. A single mobile
application screen might require data from five different services, which can
force the client to manage multiple connections, handle partial failures, and
aggregate responses. As organizations scale their microservices fleets, keeping
that orchestration in every client can become difficult.
-The API gateway pattern, first described by Chris Richardson and widely
adopted since, solves this by interposing a single component between clients
and the service fleet. The gateway accepts all client requests, routes them to
the appropriate services, and returns consolidated responses. The pattern has
become a standard component in production microservices architectures.
+The API gateway pattern addresses this by placing a routing and policy layer
between clients and the service fleet. The gateway accepts client requests,
routes them to the appropriate services, and returns their responses. Some
systems also use a separate composition service or backend-for-frontend when
one client operation requires data from several services.
-The gateway also addresses a second fundamental problem: cross-cutting concern
duplication. Authentication, logging, rate limiting, CORS handling, and request
validation must be applied consistently across all services. Without a gateway,
each service team implements these independently, leading to drift,
inconsistency, and duplicated effort. Centralizing cross-cutting concerns at
the gateway significantly reduces per-service boilerplate code.
+The gateway can also reduce duplication of shared edge concerns.
Authentication, logging, rate limiting, CORS handling, and request validation
may otherwise be implemented through service code, libraries, sidecars,
proxies, or platform services. A gateway provides one policy point for traffic
that crosses it, reducing duplication when those policies belong at the edge;
services still retain business-specific controls.
+
+## When a Simpler Alternative Is Enough
+
+Microservices do not automatically require an API gateway. A reverse proxy,
ingress controller, service-mesh ingress, cloud load balancer, or direct
client-to-service access may be sufficient when:
+
+- the system has one internal client and only a few services;
+- no API is exposed outside a trusted network boundary;
+- an existing ingress proxy already provides the required routing and TLS
features;
+- service-mesh ingress or a cloud load balancer covers the current traffic and
policy requirements; or
+- the team cannot yet operate another critical traffic component reliably.
+
+Choose from concrete routing, security, client, and operating requirements
rather than from the use of microservices alone. A gateway becomes useful when
the system needs a stable client-facing entry point, shared edge policies,
upstream protection, or traffic controls that simpler infrastructure does not
provide.
## Core Gateway Patterns
@@ -25,19 +37,19 @@ The gateway also addresses a second fundamental problem:
cross-cutting concern d
The most fundamental gateway pattern routes incoming requests to the correct
upstream service based on URL paths, headers, methods, or other request
attributes. A gateway might route `/api/users/*` to the user service,
`/api/orders/*` to the order service, and `/api/products/*` to the catalog
service.
-Dynamic routing takes this further by reading route configurations from a
control plane or configuration store, allowing routes to be updated without
restarting the gateway. Apache APISIX supports dynamic route configuration
through its Admin API and etcd-backed configuration store, enabling
zero-downtime route changes.
+Dynamic routing takes this further by reading route configurations from a
control plane or configuration store, allowing accepted route changes to be
applied without restarting gateway processes. Apache APISIX supports dynamic
route configuration through its Admin API and etcd-backed configuration store;
rollout safety still depends on validation, control-plane availability, and
rollback practices.
### API Composition (Aggregation)
-API composition combines responses from multiple microservices into a single
response for the client. Instead of requiring a mobile application to make five
separate API calls to render a dashboard, the gateway fetches data from all
five services in parallel and returns a unified response.
+API composition combines responses from multiple microservices into a single
response for the client. Instead of requiring a mobile application to make five
separate API calls to render a dashboard, a composition-capable gateway,
backend for frontend (BFF), or separate composition service can fetch data from
all five services in parallel and return a unified response.
-This pattern reduces client-side complexity and network round trips.
Consolidating multiple API calls into a single gateway request significantly
decreases page load time, especially on mobile networks where each round trip
adds noticeable latency.
+This pattern can reduce client-side complexity and network round trips. It
also adds orchestration logic and failure handling to the composition layer, so
teams should measure whether the extra hop improves the target client
experience.
### Backend for Frontend (BFF)
The BFF pattern creates gateway configurations tailored to specific client
types. A mobile BFF provides compact responses optimized for bandwidth
constraints and small screens. A web BFF returns richer data structures suited
to desktop layouts. An internal BFF serves admin tools with elevated access.
-Each BFF acts as a specialized gateway layer that transforms and filters
upstream service responses for its target client. Netflix, Spotify, and
SoundCloud have publicly documented their BFF implementations. The pattern
prevents a one-size-fits-all API from forcing compromises on every client type.
+Each BFF acts as a specialized API layer that transforms and filters upstream
service responses for its target client. The pattern can keep client-specific
response shaping out of general-purpose services, but each BFF still needs
clear ownership, authentication, observability, and lifecycle management.
### Service Mesh Integration
@@ -45,33 +57,48 @@ In architectures that deploy both an API gateway and a
service mesh, the gateway
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.
+## Gateway and Service Responsibilities
+
+Clear ownership prevents the gateway from becoming a business-logic layer and
prevents services from assuming that all traffic passed through the gateway.
+
+| Concern | Typical gateway role | Typical service role |
+| --- | --- | --- |
+| Authentication | Validate supported client credentials or tokens | Enforce
identity requirements for internal calls where needed |
+| Authorization | Apply route- or consumer-level policy | Enforce resource-
and domain-level permissions |
+| Rate limiting | Protect shared entry points and upstream capacity | Apply
business quotas or workload-specific limits |
+| Validation | Enforce protocol, request-size, or basic schema constraints |
Validate domain rules and state transitions |
+| Observability | Record edge traffic and propagate trace context | Instrument
internal work and business outcomes |
+| Composition | Perform limited protocol or payload adaptation | Own workflows
and business orchestration |
+
+Long-running orchestration and domain decisions are usually easier to own and
test in an application, BFF, or orchestration service than in gateway plugins.
The exact boundary should reflect the trust model and failure behavior of the
system.
+
## Key Features for Microservices
### Service Discovery
-In a microservices environment, services scale dynamically and their network
locations change frequently. Static configuration of upstream addresses becomes
impractical at scale. Service discovery enables the gateway to automatically
detect available service instances and their health status.
+In a microservices environment, services scale dynamically and their network
locations change frequently. Static configuration of upstream addresses becomes
impractical at scale. A configured service-discovery integration lets the
gateway resolve service instances from a registry. Endpoint discovery and
health checking are separate concerns unless the selected integration
explicitly combines them.
-Apache APISIX integrates with multiple service discovery systems, documented
in its [discovery configuration guide](/docs/apisix/discovery/). Supported
registries include Consul, Eureka, Nacos, and Kubernetes-native service
discovery. When a new service instance registers or an existing instance
becomes unhealthy, APISIX updates its routing table automatically.
+Apache APISIX integrates with multiple service discovery systems, documented
in its [discovery configuration guide](/docs/apisix/discovery/). Supported
options include Consul, Eureka, Nacos, DNS, and Kubernetes. Each discovery
implementation has its own refresh and filtering behavior. APISIX [active and
passive health checks](/docs/apisix/tutorials/health-check/) can separately
mark upstream nodes unhealthy when their checks and thresholds are configured.
-In Kubernetes environments, APISIX can read Service and Endpoint resources
directly, eliminating the need for a separate discovery system.
Kubernetes-native service discovery typically provides faster routing updates
compared to polling-based approaches.
+In Kubernetes environments, the APISIX Ingress Controller can translate
supported Kubernetes resources into APISIX configuration. Verify the controller
version, resource type, and reconciliation behavior required by the deployment
rather than assuming that every discovery integration has the same update model.
### Circuit Breaking
Circuit breaking prevents cascading failures by stopping requests to an
unhealthy upstream service. When error rates exceed a configured threshold, the
circuit opens and the gateway returns a fast failure response instead of
forwarding requests to the struggling service. After a cooldown period, the
circuit enters a half-open state and allows a limited number of test requests
through. If those succeed, the circuit closes and normal traffic resumes.
-Without circuit breaking, a single unhealthy service can consume all available
connections and thread pools in the gateway, causing failures to cascade across
the entire system. Organizations using circuit breakers typically experience
significantly shorter outage durations.
+Without bounded timeouts, retries, and failure controls, an unhealthy service
can consume gateway and client resources and contribute to cascading failures.
Circuit-breaker thresholds must be tuned from real error, latency, and recovery
behavior; an overly sensitive policy can reject healthy traffic.
### Canary Deployment
Canary deployment routes a small percentage of production traffic to a new
service version while the majority continues to hit the stable version. The
gateway controls the traffic split, enabling teams to validate new releases
with real traffic before committing to a full rollout.
-APISIX supports traffic splitting through weighted upstream configurations. A
typical canary deployment starts with 5% of traffic routed to the new version,
gradually increasing to 25%, 50%, and finally 100% as metrics confirm
stability. If errors spike, the gateway reverts the traffic split without any
service redeployment.
+APISIX supports traffic splitting through weighted upstream configurations.
Teams can begin with a small share of traffic and increase it only when
service-level metrics remain within the rollout criteria. Reverting the traffic
split still requires an explicit, tested configuration or deployment action.
### Distributed Tracing
-In a microservices architecture, a single client request might traverse ten or
more services. Distributed tracing tracks the request's path through the entire
service chain, recording latency at each hop. The gateway plays a critical role
by injecting trace context headers (W3C Trace Context or B3) into every request
it forwards.
+In a microservices architecture, a client request can traverse several
services. Distributed tracing can connect spans from those hops when each
participating component propagates compatible trace context and emits spans. A
configured gateway tracing plugin can start or continue trace context for
requests that pass through APISIX.
-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.
+APISIX provides plugins for tracing and exporting gateway-visible spans to
systems such as Zipkin, SkyWalking, and OpenTelemetry-compatible backends.
End-to-end traces still require compatible context propagation and
instrumentation in downstream services; gateway telemetry alone covers only
traffic and processing visible to APISIX.
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.
@@ -85,9 +112,31 @@ Apache APISIX is designed for microservices environments,
offering dynamic confi
**Kubernetes-native operation.** The [APISIX Ingress
Controller](/docs/ingress-controller/concepts/gateway-api/) deploys APISIX as a
Kubernetes-native gateway, supporting both the legacy Ingress resource and the
newer Gateway API specification. This allows platform teams to manage gateway
configuration using familiar Kubernetes declarative workflows.
-**Service discovery integration.** APISIX's [service
discovery](/docs/apisix/discovery/) capabilities connect directly to Consul,
Nacos, Eureka, and Kubernetes DNS, ensuring the gateway always routes to
healthy, available service instances without manual configuration updates.
+**Service discovery integration.** APISIX's [service
discovery](/docs/apisix/discovery/) capabilities can resolve upstream nodes
through configured integrations such as Consul, Nacos, Eureka, DNS, and
Kubernetes. Refresh behavior depends on the selected integration, while
excluding unhealthy nodes requires an appropriate registry policy or APISIX
health-check configuration.
+
+**Observability.** Built-in plugins can export gateway metrics, traces, and
logs to configured external systems. These signals describe requests processed
by APISIX; services, queues, and other internal paths need their own
instrumentation for end-to-end operational visibility.
+
+## Operational Risks to Plan For
+
+Adding a gateway concentrates important traffic and policy decisions, so
deployment and configuration choices can create their own failure modes:
+
+- **Gateway failure domain.** Run enough data-plane capacity across the
failure domains required by the service, define health checks, and test
behavior when the control plane or configuration store is unavailable.
Deploying a gateway does not by itself provide high availability.
+- **One policy for unlike services.** Upstreams differ in latency, capacity,
data sensitivity, and client behavior. Use route- or consumer-specific controls
where needed, and keep default policies explicit and auditable.
+- **Gateway-only security.** Protect administrative APIs and configuration
stores, restrict network access, and secure service-to-service communication.
Services must not trust client-controlled identity headers unless a trusted
component removes or replaces them.
+- **Unbounded plugin work.** Plugins run in a critical request path. Review
custom code, limit its network and secret access, test failure behavior, and
keep expensive or blocking work out of the request path.
+
+## Practical Evaluation Checklist
+
+Before making Apache APISIX a production dependency, verify:
+
+1. how routes and upstreams are configured, reviewed, and promoted between
environments;
+2. which authentication and authorization model protects each API and internal
call path;
+3. how APISIX discovers or receives updates about service endpoints;
+4. which telemetry is exported, where sensitive data is filtered, and which
internal paths need separate instrumentation;
+5. how the data plane behaves during upstream, network, control-plane, and
configuration-store failures; and
+6. how upgrades, backups, rollbacks, and incident response are tested.
-**Observability.** Built-in plugins export metrics to Prometheus, traces to
Jaeger, Zipkin, and OpenTelemetry, and logs to HTTP endpoints, syslog, or
Kafka. This enables a complete observability pipeline with the gateway as the
instrumentation point for all external API traffic.
+Start with the [APISIX getting-started guide](/docs/apisix/getting-started/)
and enable only the [plugins required by the
workload](/docs/apisix/terminology/plugin/). A smaller, well-tested policy set
is easier to operate than features without clear owners or failure expectations.
## FAQ
@@ -97,7 +146,7 @@ Not always. If the mesh ingress already provides the
external routing and policy
### How does an API gateway handle partial failures across microservices?
-An API gateway can be configured with circuit breakers, timeouts, and retry
policies for each upstream service. When using the API composition pattern, the
gateway can return partial results with degraded status rather than failing the
entire request when one backend is unavailable. APISIX supports configurable
timeouts and retry counts per route, and health checks automatically remove
unhealthy nodes from the upstream pool.
+An API gateway can apply timeouts, bounded retries, circuit-breaking policies,
and configured health checks before or while routing to an upstream. Those
controls can contain some failures, but they do not define how a composed
business response should degrade. If a client operation combines several
services, place partial-result and fallback policy in the composition layer and
specify which missing results are acceptable. In APISIX, health checks exclude
nodes only after the configured [...]
### Should each microservice team manage their own gateway routes?
@@ -105,7 +154,7 @@ A decentralized model where service teams own their route
configurations works w
### What is the performance impact of adding an API gateway to a microservices
architecture?
-Apache APISIX, built on NGINX and LuaJIT, adds 1-2ms of latency per request
with a typical plugin configuration (authentication, rate limiting, logging).
For most microservices architectures where end-to-end request latency is
50-500ms, this overhead is under 2% of total latency. The operational benefits
of centralized security, observability, and traffic management significantly
outweigh the minor latency cost.
+An API gateway adds a network hop and the processing cost of each enabled
policy. The impact depends on deployment topology, TLS, payload size,
connection reuse, logging, and the selected plugins. Benchmark APISIX with the
same routes, policies, and traffic profile planned for production, and include
the gateway in latency and capacity budgets.
## Related
diff --git a/website/learning-center/api-gateway-rate-limiting.md
b/website/learning-center/api-gateway-rate-limiting.md
index 2899ca962d4..dc2c3568b98 100644
--- a/website/learning-center/api-gateway-rate-limiting.md
+++ b/website/learning-center/api-gateway-rate-limiting.md
@@ -88,7 +88,7 @@ Fixed window is the simplest algorithm but has a well-known
boundary problem: a
Assign rate limits based on authenticated consumer identity. This is useful
for APIs that provide different quotas or burst allowances to different
consumer groups.
-In APISIX, an authentication plugin can establish the Consumer before a
rate-limiting plugin keys a policy on `consumer_name`. Rate-limiting plugins
can also be attached to [Consumers](/docs/apisix/terminology/consumer/) or
[Consumer Groups](/docs/apisix/terminology/consumer-group/) when that ownership
model fits the policy.
+In APISIX, an authentication plugin can establish the Consumer before a
rate-limiting plugin keys a policy on `consumer_name`. Rate-limiting plugins
can also be attached to [Consumers](/docs/apisix/terminology/consumer/) or
[Consumer Groups](/docs/apisix/terminology/consumer-group/) when that ownership
model fits the policy. See the [step-by-step APISIX example for per-consumer
and shared consumer-group
limits](/blog/2024/07/25/different-rate-limits-apisix/) for a concrete
configuration.
### Per-IP
