This is an automated email from the ASF dual-hosted git repository.
baoyuan 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 0ce3559f84f feat(seo): add sitemap optimization and 5 Learning Center
articles (P1) (#2025)
0ce3559f84f is described below
commit 0ce3559f84f7ec8cb2dfecc359e35163d26b3d7b
Author: Ming Wen <[email protected]>
AuthorDate: Thu Apr 16 09:54:04 2026 +0800
feat(seo): add sitemap optimization and 5 Learning Center articles (P1)
(#2025)
---
scripts/update-sitemap-loc.js | 55 +++++++-
.../learning-center/api-gateway-authentication.md | 117 ++++++++++++++++
.../api-gateway-for-microservices.md | 122 +++++++++++++++++
.../learning-center/api-gateway-rate-limiting.md | 149 +++++++++++++++++++++
.../api-gateway-vs-load-balancer.md | 132 ++++++++++++++++++
website/learning-center/kubernetes-api-gateway.md | 146 ++++++++++++++++++++
6 files changed, 716 insertions(+), 5 deletions(-)
diff --git a/scripts/update-sitemap-loc.js b/scripts/update-sitemap-loc.js
index 87135ec878c..92034f86b43 100644
--- a/scripts/update-sitemap-loc.js
+++ b/scripts/update-sitemap-loc.js
@@ -48,17 +48,62 @@ function shouldExclude(url) {
}
/**
- * Filter out excluded URLs from a sitemap object and return removal count.
+ * Determine the priority for a URL based on its path.
+ * Higher priority for key landing pages, lower for deep docs and archives.
+ */
+function getPriority(url) {
+ // Homepage
+ if (/^https:\/\/apisix\.apache\.org\/(zh\/)?$/.test(url)) return '1.0';
+ // Key landing pages
+ if (/\/(ai-gateway|plugins|downloads|docs|learning-center)\/$/.test(url))
return '0.8';
+ // Learning center articles and blog posts
+ if (/\/learning-center\//.test(url)) return '0.8';
+ if (/\/blog\/\d{4}\//.test(url)) return '0.6';
+ // Doc pages (latest version)
+ if (/\/docs\//.test(url)) return '0.7';
+ // Everything else
+ return '0.5';
+}
+
+/**
+ * Determine the changefreq for a URL based on its path.
+ */
+function getChangefreq(url) {
+ if (/^https:\/\/apisix\.apache\.org\/(zh\/)?$/.test(url)) return 'weekly';
+ if (/\/blog\/\d{4}\//.test(url)) return 'monthly';
+ if (/\/docs\//.test(url)) return 'monthly';
+ if (/\/learning-center\//.test(url)) return 'monthly';
+ return 'weekly';
+}
+
+/**
+ * Filter out excluded URLs from a sitemap object, set differentiated
+ * priority/changefreq, and add lastmod. Returns removal count.
*/
function filterSitemapUrls(sitemap) {
const urls = Array.isArray(sitemap.urlset.url)
? sitemap.urlset.url
: [sitemap.urlset.url];
const before = urls.length;
- sitemap.urlset.url = urls.filter((entry) => {
- const loc = entry.loc && entry.loc._text;
- return !loc || !shouldExclude(loc);
- });
+ const today = new Date().toISOString().split('T')[0];
+
+ sitemap.urlset.url = urls
+ .filter((entry) => {
+ const loc = entry.loc && entry.loc._text;
+ return !loc || !shouldExclude(loc);
+ })
+ .map((entry) => {
+ const loc = entry.loc && entry.loc._text;
+ if (loc) {
+ entry.priority = { _text: getPriority(loc) };
+ entry.changefreq = { _text: getChangefreq(loc) };
+ if (!entry.lastmod) {
+ entry.lastmod = { _text: today };
+ }
+ }
+ return entry;
+ });
+
return before - sitemap.urlset.url.length;
}
diff --git a/website/learning-center/api-gateway-authentication.md
b/website/learning-center/api-gateway-authentication.md
new file mode 100644
index 00000000000..237f3a98999
--- /dev/null
+++ b/website/learning-center/api-gateway-authentication.md
@@ -0,0 +1,117 @@
+---
+title: "API Gateway Authentication: Methods, Best Practices & Implementation"
+description: "Learn how to implement authentication at the API gateway layer.
Covers Key Auth, JWT, OAuth 2.0, OpenID Connect, mTLS, and HMAC with practical
examples."
+slug: api-gateway-authentication
+date: 2026-04-14
+tags: [authentication, security, api-gateway]
+hide_table_of_contents: false
+---
+
+API gateway authentication is the practice of verifying client identity at a
centralized entry point before requests reach backend services. By enforcing
authentication at the gateway layer, organizations eliminate redundant auth
logic across services, reduce attack surface, and gain a single enforcement
point for access policies.
+
+## What is API Gateway Authentication
+
+In a distributed architecture, every service that exposes an endpoint must
answer a fundamental question: who is making this request? Without a gateway,
each service independently implements its own authentication stack. This leads
to inconsistent enforcement, duplicated code, and a broader attack surface.
+
+An API gateway centralizes this concern. It intercepts every inbound request,
validates credentials against a configured identity provider or local store,
and either forwards the authenticated request downstream or rejects it
immediately. Broken authentication consistently ranks among the top API
vulnerability categories, making centralized enforcement critical.
+
+Centralizing authentication at the gateway layer provides three key
advantages. First, it significantly reduces per-service authentication code by
consolidating auth logic into a single component. Second, it creates a single
audit log for every authentication event. Third, it enables credential rotation
and policy changes without redeploying individual services.
+
+## Authentication Methods
+
+### Key Auth
+
+Key authentication is the simplest method. The client includes a static API
key in a header or query parameter. The gateway validates the key against a
stored registry and maps it to a consumer identity.
+
+Key Auth works well for server-to-server communication where transport
security (TLS) is guaranteed and the client population is small. API keys
remain common for machine-to-machine authentication, though their share is
declining as organizations move toward token-based methods.
+
+Apache APISIX supports Key Auth natively through its [key-auth
plugin](/docs/apisix/plugins/key-auth/). Configuration requires only defining a
consumer and attaching the plugin to a route.
+
+### JWT (JSON Web Tokens)
+
+JWT authentication uses digitally signed tokens that carry claims about the
client. The gateway validates the token signature, checks expiration, and
optionally verifies audience and issuer claims. Because JWTs are
self-contained, the gateway does not need to call an external service on every
request.
+
+JWTs dominate modern API authentication. The compact format and stateless
verification make JWTs particularly well-suited for high-throughput gateways
where microsecond-level latency matters.
+
+APISIX implements JWT validation through its [jwt-auth
plugin](/docs/apisix/plugins/jwt-auth/), supporting both HS256 and RS256
algorithms with configurable claim validation.
+
+### OAuth 2.0
+
+OAuth 2.0 is an authorization framework that enables third-party applications
to obtain limited access to an API on behalf of a resource owner. The gateway
validates bearer tokens issued by an authorization server, typically by
introspecting the token or verifying a JWT access token locally.
+
+OAuth 2.0 is widely adopted across enterprises for API integrations. The
framework's delegation model makes it essential for any API exposed to external
developers or partner ecosystems.
+
+### OpenID Connect (OIDC)
+
+OpenID Connect extends OAuth 2.0 with a standardized identity layer. It adds
an ID token (a JWT) that carries user identity claims alongside the OAuth 2.0
access token. The gateway can validate the ID token to confirm user identity
and use the access token for authorization decisions.
+
+OIDC is the de facto standard for single sign-on in API ecosystems. Major
identity providers including Okta, Auth0, Azure AD, and Google Identity all
implement OIDC. APISIX provides native OIDC support through its [openid-connect
plugin](/docs/apisix/plugins/openid-connect/), which handles the full
authorization code flow, token introspection, and token refresh.
+
+### mTLS (Mutual TLS)
+
+Mutual TLS requires both the client and server to present certificates during
the TLS handshake. The gateway validates the client certificate against a
trusted certificate authority, establishing strong machine identity without
application-layer tokens.
+
+mTLS adoption has surged alongside zero-trust architecture initiatives. In
Kubernetes environments, mTLS between services has become increasingly common.
At the gateway level, mTLS is particularly valuable for B2B integrations and
internal service-to-service communication where certificate management
infrastructure already exists.
+
+### HMAC Authentication
+
+HMAC authentication requires the client to compute a hash-based message
authentication code over the request content using a shared secret. The gateway
independently computes the same HMAC and compares the results. This method
provides request integrity verification in addition to authentication.
+
+HMAC is common in financial APIs and webhook verification scenarios where
request tampering must be detected. AWS Signature Version 4, used across all
AWS API calls, is an HMAC-based scheme processing billions of requests daily.
+
+## Comparison Table
+
+| Method | Complexity | Statefulness | Best For | Token Expiry |
+|--------|-----------|-------------|----------|-------------|
+| Key Auth | Low | Stateless (lookup) | Internal services, simple integrations
| Manual rotation |
+| JWT | Medium | Stateless | High-throughput APIs, mobile clients | Built-in
(exp claim) |
+| OAuth 2.0 | High | Stateful (auth server) | Third-party access, delegated
auth | Access token TTL |
+| OIDC | High | Stateful (identity provider) | SSO, user-facing APIs | ID +
access token TTL |
+| mTLS | High | Stateless (cert validation) | Zero-trust, B2B, service mesh |
Certificate validity period |
+| HMAC | Medium | Stateless | Financial APIs, webhook verification | Per-key
rotation policy |
+
+## Best Practices
+
+**Layer your authentication.** Use mTLS at the transport layer for service
identity and JWT or OAuth 2.0 at the application layer for user identity.
Defense in depth reduces the impact of any single credential compromise.
+
+**Enforce short-lived tokens.** Set JWT and OAuth 2.0 access token lifetimes
to 15 minutes or less for user-facing flows. Use refresh tokens to obtain new
access tokens without re-authentication. Short token lifetimes limit the window
of exploitation if a token is leaked.
+
+**Centralize consumer management.** Define consumers at the gateway level with
consistent identity attributes. Map every API key, JWT subject, and OAuth 2.0
client ID to a named consumer entity. This enables unified rate limiting,
logging, and access control across authentication methods.
+
+**Validate all claims.** Do not trust a JWT solely because its signature is
valid. Verify the issuer (iss), audience (aud), expiration (exp), and
not-before (nbf) claims. Reject tokens with unexpected or missing claims.
+
+**Log authentication events comprehensively.** Record every authentication
success and failure with client identity, timestamp, source IP, and the route
accessed. These logs are essential for incident response and compliance audits.
NIST SP 800-92 recommends retaining authentication logs for a minimum of 90
days.
+
+## How Apache APISIX Handles Authentication
+
+Apache APISIX provides a plugin-based authentication architecture that
supports all six methods described above. Each authentication plugin runs in
the gateway's request processing pipeline before the request reaches any
upstream service.
+
+APISIX's consumer abstraction ties authentication credentials to named
entities. A single consumer can have multiple authentication methods attached,
enabling gradual migration between methods. For example, an organization
migrating from Key Auth to JWT can configure both plugins on the same consumer
during the transition period.
+
+Key plugins include:
+
+- [key-auth](/docs/apisix/plugins/key-auth/): Static API key validation with
header or query parameter extraction.
+- [jwt-auth](/docs/apisix/plugins/jwt-auth/): JWT signature verification with
configurable algorithms and claim validation.
+- [openid-connect](/docs/apisix/plugins/openid-connect/): Full OIDC flow
support including authorization code, token introspection, and PKCE.
+
+APISIX also supports chaining authentication plugins with authorization
plugins such as consumer-restriction and OPA (Open Policy Agent), enabling
fine-grained access control decisions after identity is established.
+
+Performance benchmarks show APISIX processing authenticated requests with
sub-millisecond overhead for Key Auth and JWT validation, and under 5ms for
OIDC token introspection with a local identity provider. These numbers hold at
sustained loads exceeding 10,000 requests per second on modest hardware.
+
+## FAQ
+
+### Should I use JWT or OAuth 2.0 for my API?
+
+JWT and OAuth 2.0 are not mutually exclusive. OAuth 2.0 is an authorization
framework that often uses JWTs as its access token format. If your API serves
first-party clients only, standalone JWT authentication may suffice. If
third-party developers need delegated access, implement the full OAuth 2.0
framework with JWT access tokens.
+
+### Is API key authentication secure enough for production?
+
+API key authentication is secure for server-to-server communication over TLS
when keys are rotated regularly and scoped to specific consumers. It is not
recommended for client-side applications (browsers, mobile apps) because keys
cannot be kept secret on end-user devices. For any client-facing API, prefer
OAuth 2.0 or OIDC.
+
+### How does mTLS differ from standard TLS at the gateway?
+
+Standard TLS authenticates only the server to the client. The client verifies
the server's certificate, but the server accepts any client connection. mTLS
adds a second handshake step where the client also presents a certificate that
the server validates against a trusted CA. This provides strong machine
identity for both parties and is a foundational component of zero-trust network
architectures.
+
+### Can I combine multiple authentication methods on a single route?
+
+Yes. Apache APISIX supports configuring multiple authentication plugins on a
single route. The gateway attempts each configured method in order and accepts
the request if any method succeeds. This is useful during migration periods or
when a route serves clients with different authentication capabilities.
diff --git a/website/learning-center/api-gateway-for-microservices.md
b/website/learning-center/api-gateway-for-microservices.md
new file mode 100644
index 00000000000..cf9727f7efb
--- /dev/null
+++ b/website/learning-center/api-gateway-for-microservices.md
@@ -0,0 +1,122 @@
+---
+title: "API Gateway for Microservices: Architecture, Patterns & Best Practices"
+description: "Learn why microservices architectures need an API gateway.
Covers service discovery, load balancing, circuit breaking, and API composition
patterns."
+slug: api-gateway-for-microservices
+date: 2026-04-14
+tags: [microservices, architecture, api-gateway]
+hide_table_of_contents: false
+---
+
+Microservices architectures need an API gateway to provide a single entry
point that abstracts the complexity of a distributed service fleet from API
consumers. The gateway handles cross-cutting concerns like authentication,
routing, rate limiting, and observability centrally, preventing each
microservice from reimplementing these capabilities independently and ensuring
consistent behavior across the entire API surface.
+
+## 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.
+
+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 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.
+
+## Core Gateway Patterns
+
+### Request Routing
+
+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.
+
+### 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.
+
+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.
+
+### 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.
+
+### 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.
+
+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.
+
+## 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.
+
+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.
+
+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.
+
+### 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.
+
+### 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.
+
+### 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.
+
+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 |
+
+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.
+
+**Dynamic configuration without restarts.** APISIX stores configuration in
etcd and applies changes in real time. Routes, upstream definitions, plugins,
and consumers can be added, modified, or removed through the Admin API without
restarting any gateway node. This is essential in microservices environments
where service endpoints change frequently.
+
+**Plugin pipeline architecture.** APISIX's plugin system runs a configurable
pipeline of plugins on each request. For microservices, this means
authentication, rate limiting, request transformation, and logging execute as
independent pipeline stages. Plugins can be enabled per-route, per-service, or
globally, providing fine-grained control over cross-cutting behavior.
+
+**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.
+
+**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.
+
+## FAQ
+
+### 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.
+
+### 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.
+
+### Should each microservice team manage their own gateway routes?
+
+A decentralized model where service teams own their route configurations works
well at scale, provided the platform team controls the global policies
(authentication requirements, rate limiting defaults, logging standards).
APISIX supports this through its Admin API, which can be integrated into CI/CD
pipelines. Service teams declare their routes in version-controlled
configuration files, and the deployment pipeline applies changes through the
Admin API after policy validation.
+
+### 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.
diff --git a/website/learning-center/api-gateway-rate-limiting.md
b/website/learning-center/api-gateway-rate-limiting.md
new file mode 100644
index 00000000000..750659a0049
--- /dev/null
+++ b/website/learning-center/api-gateway-rate-limiting.md
@@ -0,0 +1,149 @@
+---
+title: "API Gateway Rate Limiting: Algorithms, Strategies & Configuration"
+description: "Understand API rate limiting at the gateway layer. Covers token
bucket, sliding window, and leaky bucket algorithms with practical
configuration examples."
+slug: api-gateway-rate-limiting
+date: 2026-04-14
+tags: [rate-limiting, traffic-control, api-gateway]
+hide_table_of_contents: false
+---
+
+API gateway rate limiting is the practice of controlling how many requests a
client can make to your API within a defined time window. Implemented at the
gateway layer, rate limiting protects backend services from overload, prevents
abuse, ensures fair resource allocation across consumers, and maintains
predictable service quality under variable traffic conditions.
+
+## What is Rate Limiting
+
+Rate limiting enforces a maximum request throughput for API consumers. When a
client exceeds its allowed quota, the gateway returns an HTTP 429 (Too Many
Requests) response instead of forwarding the request to the upstream service.
The response typically includes a `Retry-After` header indicating when the
client can resume making requests.
+
+The need for rate limiting has grown alongside API traffic volumes. API
traffic now represents the majority of HTTP requests processed globally, and a
significant portion consists of automated requests, many of which are abusive
or unintentional high-frequency polling.
+
+Without rate limiting, a single misbehaving client can consume
disproportionate backend resources, degrading performance for all consumers.
Rate limiting is also a contractual tool: it enforces the usage tiers defined
in API monetization plans and SLAs.
+
+## Why Rate Limit at the Gateway
+
+Implementing rate limiting at the API gateway rather than in individual
services provides several structural advantages.
+
+**Single enforcement point.** When rate limits are defined at the gateway,
every request passes through the same throttling logic regardless of which
upstream service handles it. This eliminates the risk of inconsistent
enforcement across a microservices fleet and reduces availability incidents
caused by traffic spikes.
+
+**Reduced backend load.** Rejected requests never reach the upstream service.
This means the gateway absorbs the cost of excess traffic, keeping backend
services operating within their designed capacity.
+
+**Consistent client experience.** Centralized rate limiting ensures all
consumers receive the same HTTP 429 responses with standardized headers
(`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`), making it
straightforward for client developers to implement backoff logic.
+
+**Operational visibility.** Gateway-level rate limiting produces unified
metrics on throttled requests, enabling operations teams to identify abusive
clients, undersized quotas, and traffic anomalies from a single dashboard.
+
+## Rate Limiting Algorithms
+
+### Token Bucket
+
+The token bucket algorithm maintains a bucket of tokens for each rate-limited
entity. Tokens are added at a fixed rate up to a maximum capacity. Each request
consumes one token. If the bucket is empty, the request is rejected.
+
+Token bucket allows short bursts up to the bucket capacity while enforcing an
average rate over time. This makes it well-suited for APIs where occasional
traffic spikes are acceptable but sustained overuse is not.
+
+**Pros:** Permits controlled bursting, simple to implement, low memory
footprint.
+
+**Cons:** Burst size must be tuned carefully; overly generous bursts can still
overwhelm backends.
+
+### Leaky Bucket
+
+The leaky bucket algorithm processes requests at a fixed rate, queuing excess
requests until the queue is full. It smooths traffic into a uniform output rate
regardless of input burstiness.
+
+Leaky bucket is ideal for backends that require strictly uniform request
rates, such as third-party APIs with their own rate limits or services with
fixed connection pools.
+
+**Pros:** Produces perfectly smooth output, prevents backend overload from
bursts.
+
+**Cons:** Higher latency for bursty traffic due to queuing, queue size
requires tuning.
+
+### Sliding Window
+
+The sliding window algorithm divides time into overlapping windows and counts
requests across the current and previous windows using weighted proportions.
This eliminates the boundary problem inherent in fixed windows.
+
+For example, if the window is 60 seconds and the current position is 40
seconds into the window, the algorithm weights 33% of the previous window's
count and 100% of the current window's count to determine if the limit is
exceeded.
+
+**Pros:** Accurate rate enforcement without boundary spikes, reasonable memory
usage.
+
+**Cons:** Slightly more complex to implement than fixed window.
+
+### Fixed Window
+
+The fixed window algorithm divides time into non-overlapping intervals and
counts requests within each interval. When the count exceeds the limit,
subsequent requests are rejected until the next window begins.
+
+Fixed window is the simplest algorithm but has a well-known boundary problem:
a client can make double the intended rate by clustering requests at the end of
one window and the beginning of the next. Despite this limitation, fixed window
remains widely deployed due to its simplicity and low overhead.
+
+**Pros:** Minimal memory and computation, easy to understand and debug.
+
+**Cons:** Boundary burst problem allows temporary rate doubling.
+
+### Algorithm Comparison
+
+| Algorithm | Burst Handling | Output Smoothness | Memory | Complexity |
Boundary Accuracy |
+|-----------|---------------|-------------------|--------|------------|-------------------|
+| Token Bucket | Allows controlled bursts | Moderate | Low | Low | N/A |
+| Leaky Bucket | Queues bursts | Very smooth | Medium | Low | N/A |
+| Sliding Window | Proportional smoothing | Smooth | Medium | Medium | High |
+| Fixed Window | Boundary bursts possible | Low | Very low | Very low | Low |
+
+## Rate Limiting Strategies
+
+### Per-Consumer
+
+Assign rate limits based on authenticated consumer identity. This is the most
common strategy for APIs with tiered pricing plans. A free tier consumer might
receive 100 requests per minute while a paid enterprise consumer receives
10,000.
+
+Per-consumer rate limiting requires the rate limiting plugin to execute after
authentication so the consumer identity is available. APISIX's consumer
abstraction makes this straightforward: attach rate limit configurations
directly to consumer definitions.
+
+### Per-IP
+
+Throttle requests based on the client's source IP address. This strategy is
effective for public APIs that do not require authentication, such as health
check endpoints or public data feeds. IP-based rate limiting is a practical
first line of defense against volumetric API abuse, especially when combined
with reputation scoring.
+
+Per-IP limiting has limitations in environments where many clients share a
single IP (corporate NATs, mobile carriers). Use it as a coarse first defense
layer, not as the sole rate limiting strategy.
+
+### Per-Route
+
+Apply different rate limits to different API endpoints based on their resource
cost. A search endpoint that triggers expensive database queries might have a
stricter limit than a simple metadata lookup. This strategy protects the most
resource-intensive parts of your backend.
+
+### Global
+
+Enforce an aggregate rate limit across all consumers and routes. Global limits
protect the overall system capacity and are typically set well above individual
consumer limits. They serve as a safety net when the sum of individual limits
exceeds actual infrastructure capacity.
+
+## How Apache APISIX Implements Rate Limiting
+
+Apache APISIX provides three complementary rate limiting plugins, each
targeting a different dimension of traffic control.
+
+### limit-req (Request Rate Limiting)
+
+The [limit-req plugin](/docs/apisix/plugins/limit-req/) implements a leaky
bucket algorithm that controls the request rate per second. It accepts
configuration for the sustained request rate (`rate`), the burst allowance
(`burst`), and the rejection status code.
+
+This plugin is ideal when you need to smooth traffic to a uniform rate. It
supports keying on remote address, consumer name, service, or any variable
available in the APISIX context.
+
+### limit-count (Request Count Limiting)
+
+The [limit-count plugin](/docs/apisix/plugins/limit-count/) enforces a maximum
number of requests within a configurable time window. It supports both fixed
window and sliding window algorithms, with the window size configurable from
one second to one day.
+
+limit-count is the best choice for implementing API quota plans (e.g., 10,000
requests per day). It returns standard rate limit headers so clients can track
their remaining quota. For distributed deployments, limit-count supports shared
counters via Redis, ensuring accurate enforcement across multiple gateway
nodes. In benchmarks, Redis-backed distributed counting adds less than 1ms of
latency per request at the 99th percentile.
+
+### limit-conn (Concurrent Connection Limiting)
+
+The [limit-conn plugin](/docs/apisix/plugins/limit-conn/) restricts the number
of concurrent requests being processed simultaneously. Unlike rate-based
limits, connection limits protect against slow-client attacks and long-running
requests that tie up backend connections.
+
+This plugin is essential for APIs that serve large file downloads, streaming
responses, or long-polling connections. It works by counting active connections
per key and rejecting new connections when the limit is exceeded.
+
+### Combining Plugins
+
+APISIX allows stacking all three plugins on a single route. A typical
production configuration might combine limit-count for daily quotas, limit-req
for per-second smoothing, and limit-conn for concurrent connection caps. The
plugins execute in order, and a request rejected by any plugin does not consume
quota in subsequent plugins.
+
+This layered approach mirrors industry best practice. Production APIs benefit
from enforcing at least two independent rate limiting dimensions to provide
comprehensive protection.
+
+## FAQ
+
+### What HTTP status code should I return for rate-limited requests?
+
+Return HTTP 429 (Too Many Requests) as defined in RFC 6585. Include a
`Retry-After` header with the number of seconds the client should wait before
retrying. Additionally, include `X-RateLimit-Limit`, `X-RateLimit-Remaining`,
and `X-RateLimit-Reset` headers so clients can proactively manage their request
rate. APISIX's limit-count plugin returns these headers automatically.
+
+### How do I handle rate limiting in a distributed gateway deployment?
+
+Use a shared counter store such as Redis. APISIX's limit-count plugin natively
supports Redis and Redis Cluster backends for distributed counter
synchronization. This ensures that rate limits are enforced accurately
regardless of which gateway node processes the request. The trade-off is a
small latency increase (typically under 1ms) for the Redis round-trip on each
request.
+
+### Should I rate limit internal service-to-service traffic?
+
+Yes, but with different thresholds. Internal rate limiting prevents cascading
failures when one service sends an unexpectedly high volume of requests to
another. Set internal limits based on measured capacity rather than commercial
quotas. Circuit breakers complement internal rate limiting by stopping requests
entirely when a downstream service is unhealthy.
+
+### How do I communicate rate limits to API consumers?
+
+Document rate limits in your API reference and include them in onboarding
materials. Use standard rate limit response headers on every response (not just
429 responses) so clients can monitor their consumption in real time. Provide a
dedicated endpoint or dashboard where consumers can check their current usage
against their quota. For paid tiers, send proactive notifications when
consumers approach their limits.
diff --git a/website/learning-center/api-gateway-vs-load-balancer.md
b/website/learning-center/api-gateway-vs-load-balancer.md
new file mode 100644
index 00000000000..f4871c692b5
--- /dev/null
+++ b/website/learning-center/api-gateway-vs-load-balancer.md
@@ -0,0 +1,132 @@
+---
+title: "API Gateway vs Load Balancer: Key Differences Explained"
+description: "Understand the differences between an API gateway and a load
balancer. Learn when to use each, how they complement each other, and where
they overlap."
+slug: api-gateway-vs-load-balancer
+date: 2026-04-14
+tags: [api-gateway, load-balancer, architecture]
+hide_table_of_contents: false
+---
+
+An API gateway and a load balancer serve different primary purposes. A load
balancer distributes network traffic across multiple backend servers to
maximize throughput and availability. An API gateway operates at the
application layer to manage, secure, and transform API traffic with features
like authentication, rate limiting, and request routing. In modern
architectures, they complement each other and are frequently deployed together.
+
+## What is a Load Balancer
+
+A load balancer sits between clients and a pool of backend servers,
distributing incoming requests to ensure no single server becomes overwhelmed.
Load balancers operate at either Layer 4 (TCP/UDP) or Layer 7 (HTTP/HTTPS) of
the OSI model.
+
+Layer 4 load balancers route traffic based on IP address and port number
without inspecting the request content. They are fast, protocol-agnostic, and
add minimal latency. Layer 7 load balancers inspect HTTP headers, URLs, and
sometimes request bodies to make more intelligent routing decisions.
+
+Load balancers are foundational infrastructure. The vast majority of
organizations use some form of load balancing in their production environments.
The technology has been a networking staple for over two decades, with the core
algorithms (round-robin, least connections, weighted distribution) remaining
largely unchanged.
+
+The primary value of a load balancer is availability. By distributing traffic
and performing health checks, load balancers ensure that the failure of a
single backend instance does not cause a service outage. They also enable
horizontal scaling: adding more backend instances to handle increased traffic
without changing the client-facing endpoint.
+
+## What is an API Gateway
+
+An API gateway is an application-layer proxy that acts as the single entry
point for API consumers. Beyond routing requests to the correct backend
service, an API gateway provides a rich set of cross-cutting concerns:
authentication, authorization, rate limiting, request and response
transformation, caching, logging, and monitoring.
+
+API gateways emerged from the needs of microservices architectures and
API-first product strategies. When an organization exposes dozens or hundreds
of microservices, a gateway centralizes the operational concerns that would
otherwise be duplicated across every service.
+
+An API gateway typically operates exclusively at Layer 7 and understands
application-level protocols like HTTP, gRPC, WebSocket, and GraphQL. It makes
routing decisions based on URL paths, headers, query parameters, and even
request body content.
+
+## Feature Comparison
+
+| Capability | Load Balancer | API Gateway |
+|-----------|--------------|-------------|
+| Traffic distribution | Yes (core function) | Yes (built-in) |
+| Health checks | Yes | Yes |
+| SSL/TLS termination | Yes | Yes |
+| Layer 4 routing | Yes | Typically no |
+| Layer 7 routing | L7 LB only | Yes (core function) |
+| Authentication | No | Yes |
+| Authorization | No | Yes |
+| Rate limiting | Basic (some L7 LBs) | Yes (granular) |
+| Request transformation | No | Yes |
+| Response transformation | No | Yes |
+| API versioning | No | Yes |
+| Protocol translation | Limited | Yes (HTTP to gRPC, REST to GraphQL) |
+| Caching | Limited | Yes |
+| Developer portal | No | Yes (with management layer) |
+| Analytics and monitoring | Basic metrics | Detailed API analytics |
+| Circuit breaking | Some implementations | Yes |
+| Canary/blue-green deploys | Some implementations | Yes |
+
+The table makes the distinction clear: load balancers focus on network-level
traffic distribution, while API gateways focus on application-level API
management. The overlap exists primarily in Layer 7 load balancers, which have
gradually added some application-aware features.
+
+## Key Differences Explained
+
+### Scope of Concern
+
+A load balancer answers the question: which backend server should handle this
connection? An API gateway answers a broader set of questions: is this client
authenticated? Are they authorized for this endpoint? Have they exceeded their
rate limit? Does the request need transformation before forwarding? Should the
response be cached?
+
+In practice, most organizations using API gateways configure multiple
cross-cutting policies (authentication, rate limiting, logging, and CORS), none
of which fall within a traditional load balancer's responsibility.
+
+### Protocol Awareness
+
+Load balancers, especially at Layer 4, are largely protocol-agnostic. They
route TCP connections without understanding the application protocol. API
gateways are deeply protocol-aware. They parse HTTP methods, match URL
patterns, inspect headers, and in many cases understand domain-specific
protocols like gRPC and GraphQL.
+
+This protocol awareness enables capabilities that load balancers cannot
provide. For example, an API gateway can route GraphQL queries to different
backend services based on the query's requested fields, or translate between
REST and gRPC protocols transparently.
+
+### Configuration Granularity
+
+Load balancer configuration centers on server pools, health check parameters,
and distribution algorithms. API gateway configuration is far more granular:
per-route authentication requirements, per-consumer rate limits, request header
injection, response body transformation, and conditional plugin execution.
+
+A typical enterprise API gateway configuration manages 50-200 routes with
distinct policy combinations, compared to a load balancer managing 10-30 server
pools. The operational complexity reflects the difference in scope.
+
+### Performance Profile
+
+Layer 4 load balancers add microsecond-level latency because they operate
below the HTTP layer. API gateways add millisecond-level latency because they
must parse, inspect, and potentially transform HTTP requests. High-performance
gateways like Apache APISIX, built on NGINX and LuaJIT, keep this overhead
under 1ms for typical configurations. According to APISIX benchmark data, the
gateway processes over 20,000 requests per second per core with authentication
and rate limiting enabled.
+
+## When to Use Which
+
+### Use a Load Balancer When
+
+- You need to distribute TCP or UDP traffic across backend instances.
+- Your primary concern is availability and horizontal scaling.
+- You are load balancing non-HTTP protocols (databases, message queues, custom
TCP services).
+- You want minimal latency overhead with no application-layer processing.
+
+### Use an API Gateway When
+
+- You expose APIs to external consumers who need authentication and rate
limiting.
+- You run a microservices architecture and need centralized cross-cutting
concerns.
+- You need request or response transformation between clients and services.
+- You require detailed API analytics, logging, and monitoring.
+- You manage multiple API versions or need protocol translation.
+
+### Use Both Together
+
+In most production architectures, load balancers and API gateways coexist at
different layers. A common deployment pattern places a Layer 4 or cloud-native
load balancer (AWS NLB, Google Cloud Load Balancing) in front of a cluster of
API gateway instances. The load balancer distributes traffic across gateway
nodes for high availability, while the gateway handles application-level API
management.
+
+This separation of concerns allows each component to do what it does best.
+
+## How Apache APISIX Combines Both
+
+Apache APISIX is an API gateway that includes built-in load balancing
capabilities, effectively combining both roles into a single component for many
use cases.
+
+APISIX supports multiple load balancing algorithms natively, documented in its
[load balancing guide](/docs/apisix/getting-started/load-balancing/):
+
+- **Round-robin (weighted):** Distributes requests across upstream nodes based
on configured weights.
+- **Consistent hashing:** Routes requests to the same backend based on a
configurable key (IP, header, URI), useful for cache-friendly distributions.
+- **Least connections:** Sends requests to the upstream node with the fewest
active connections.
+- **EWMA (Exponential Weighted Moving Average):** Selects the upstream node
with the lowest response latency, adapting to real-time backend performance.
+
+By combining API gateway features with production-grade load balancing, APISIX
reduces architectural complexity for many deployments. Organizations that would
otherwise deploy a separate load balancer and a separate API gateway can
consolidate into a single APISIX layer, reducing operational overhead and
network hops.
+
+For large-scale deployments, a dedicated Layer 4 load balancer in front of
APISIX nodes still makes sense for TCP-level high availability and DDoS
protection. But within the application layer, APISIX handles both traffic
distribution and API management without requiring an additional component.
+
+## FAQ
+
+### Can an API gateway replace a load balancer entirely?
+
+For HTTP and gRPC traffic, a modern API gateway like Apache APISIX can replace
a Layer 7 load balancer because it includes equivalent load balancing
algorithms. However, for non-HTTP protocols (raw TCP, UDP, database
connections) or for Layer 4 DDoS protection, a dedicated load balancer remains
necessary. The most common production pattern uses both: a Layer 4 load
balancer for network-level distribution and an API gateway for
application-level management.
+
+### Does adding an API gateway increase latency compared to a load balancer
alone?
+
+Yes, but the increase is typically small. A Layer 4 load balancer adds
microseconds of latency. An API gateway adds 0.5-2ms depending on the number of
active plugins. For most APIs where upstream service response times are
10-500ms, the gateway overhead is negligible. The operational benefits of
centralized authentication, rate limiting, and observability far outweigh the
minor latency cost.
+
+### Should I use a cloud provider's managed API gateway or deploy my own?
+
+Managed gateways (AWS API Gateway, Google Apigee) reduce operational burden
but limit customization and can become expensive at high traffic volumes. AWS
API Gateway charges per million requests, which can reach thousands of dollars
monthly for high-traffic APIs. Self-managed gateways like Apache APISIX offer
full control, unlimited throughput on your infrastructure, and no per-request
fees, but require your team to operate the gateway cluster. Evaluate based on
your traffic volume, cust [...]
+
+### How does an API gateway differ from a reverse proxy?
+
+A reverse proxy forwards client requests to backend servers and is the
foundation of both load balancers and API gateways. An API gateway is a
specialized reverse proxy that adds API-specific features: authentication, rate
limiting, request transformation, API versioning, and developer-facing
analytics. NGINX, for example, can function as a reverse proxy, load balancer,
or (with extensions) an API gateway. Apache APISIX is purpose-built as an API
gateway with load balancing built in.
diff --git a/website/learning-center/kubernetes-api-gateway.md
b/website/learning-center/kubernetes-api-gateway.md
new file mode 100644
index 00000000000..15c7cf20798
--- /dev/null
+++ b/website/learning-center/kubernetes-api-gateway.md
@@ -0,0 +1,146 @@
+---
+title: "Kubernetes API Gateway: Gateway API, Ingress Controllers & Best
Practices"
+description: "Compare Kubernetes Gateway API vs Ingress, understand ingress
controllers, and learn how to deploy an API gateway on Kubernetes with Apache
APISIX."
+slug: kubernetes-api-gateway
+date: 2026-04-14
+tags: [kubernetes, ingress-controller, gateway-api]
+hide_table_of_contents: false
+---
+
+A Kubernetes API gateway is the component that manages external traffic
entering a Kubernetes cluster and routes it to the appropriate services. It
translates Kubernetes-native resource definitions (Ingress resources or Gateway
API resources) into routing rules, handling TLS termination, path-based
routing, authentication, and traffic policies at the cluster edge.
+
+## What is a Kubernetes API Gateway
+
+Kubernetes does not include a built-in data plane for external traffic
management. The platform defines APIs (Ingress, Gateway API) that describe how
traffic should be routed, but the actual implementation is delegated to
third-party controllers. These controllers run as pods within the cluster,
watch for resource changes, and configure their underlying proxy accordingly.
+
+This design reflects Kubernetes' philosophy of extensibility. With Kubernetes
now the dominant container orchestration platform, the choice of API gateway is
one of the most consequential infrastructure decisions a platform team faces.
+
+The Kubernetes gateway landscape has evolved significantly. The original
Ingress resource, introduced in Kubernetes 1.1 (2015), provided minimal routing
capabilities. The newer Gateway API, which reached GA for core features in
2023, offers a far richer model with support for traffic splitting,
header-based routing, and role-oriented configuration. Adoption of Gateway API
resources in new Kubernetes deployments has grown rapidly since its GA release.
+
+## Kubernetes Ingress vs Gateway API
+
+### Ingress Resource
+
+The Ingress resource is Kubernetes' original API for defining external HTTP
routing rules. An Ingress object specifies host-based and path-based routing
rules that map incoming requests to backend Services.
+
+Ingress is simple but limited. It supports only HTTP and HTTPS traffic, has no
native concept of traffic splitting, and lacks a standard way to express
advanced routing (header matching, query parameter routing, request mirroring).
To work around these limitations, every ingress controller defines its own
annotations, creating vendor lock-in and configuration inconsistency.
+
+Despite its limitations, Ingress remains widely deployed. Most Kubernetes
clusters still have at least one Ingress resource defined, though many
organizations are migrating to Gateway API for new workloads.
+
+### Gateway API
+
+The Gateway API is a collection of Kubernetes custom resources that provide a
more expressive and role-oriented model for traffic management. Its core
resources are:
+
+- **GatewayClass:** Defines a class of gateway implementations (analogous to
StorageClass for volumes).
+- **Gateway:** Declares a gateway instance with listeners for specific
protocols and ports.
+- **HTTPRoute:** Defines HTTP routing rules with support for path matching,
header matching, query parameter matching, request mirroring, traffic
splitting, and request/response header modification.
+- **GRPCRoute, TCPRoute, TLSRoute, UDPRoute:** Protocol-specific route types
for non-HTTP traffic.
+
+Gateway API's role-oriented design separates infrastructure concerns (managed
by platform teams via GatewayClass and Gateway) from application routing
(managed by service teams via HTTPRoute). This separation mirrors real
organizational structures where platform engineers control the gateway
infrastructure and application teams define their own routes.
+
+Gateway API implementations generally process configuration changes faster
than equivalent annotation-based Ingress configurations because the structured
resource model eliminates the need for annotation parsing and interpretation.
+
+### Comparison Table
+
+| Capability | Ingress | Gateway API |
+|-----------|---------|-------------|
+| HTTP host/path routing | Yes | Yes |
+| Header-based routing | Via annotations (non-standard) | Native |
+| Traffic splitting | Via annotations (non-standard) | Native (HTTPRoute
weights) |
+| Request mirroring | Via annotations (non-standard) | Native |
+| gRPC routing | Via annotations (non-standard) | Native (GRPCRoute) |
+| TCP/UDP routing | Not supported | Native (TCPRoute, UDPRoute) |
+| TLS passthrough | Via annotations (non-standard) | Native (TLSRoute) |
+| Role-based ownership | No separation | GatewayClass/Gateway vs Route |
+| Cross-namespace routing | Not supported | Native (ReferenceGrant) |
+| Request header modification | Via annotations (non-standard) | Native |
+| Status reporting | Basic | Detailed per-route conditions |
+| API maturity | Stable (v1, limited scope) | Core features GA, extended
features beta |
+
+## What is an Ingress Controller
+
+An ingress controller is a Kubernetes controller that watches Ingress (and
optionally Gateway API) resources and configures a reverse proxy to implement
the defined routing rules. The controller runs as a Deployment or DaemonSet
within the cluster and typically exposes itself via a LoadBalancer or NodePort
Service.
+
+Every ingress controller uses a different underlying proxy technology. APISIX
Ingress Controller uses Apache APISIX. NGINX Ingress Controller uses NGINX.
Traefik and Kong act as both the controller and the proxy. The choice of
controller determines the available features, performance characteristics, and
operational model.
+
+The ingress controller market has consolidated around several primary options:
NGINX Ingress Controller (legacy standard), Apache APISIX Ingress Controller
(feature-rich, high performance), Traefik (developer-friendly, auto-discovery),
and Kong Ingress Controller (API management focus).
+
+## Choosing an Ingress Controller
+
+### Apache APISIX Ingress Controller
+
+APISIX Ingress Controller pairs a Kubernetes-native control plane with the
high-performance Apache APISIX data plane. It supports both Ingress resources
and Gateway API, allowing gradual migration. Key differentiators include a rich
plugin ecosystem (80+ plugins), dynamic configuration without restarts, and
sub-millisecond routing latency.
+
+APISIX is built on NGINX and LuaJIT, delivering throughput exceeding 20,000
requests per second per core in benchmarks. Its plugin architecture means that
authentication, rate limiting, request transformation, and observability can be
configured through Kubernetes custom resources without modifying application
code.
+
+### NGINX Ingress Controller
+
+The NGINX Ingress Controller is the most widely deployed option. It is stable
and well-documented but relies heavily on annotations for advanced
configuration, which creates verbose and hard-to-maintain manifests as
complexity grows.
+
+### Traefik
+
+Traefik provides automatic service discovery and integrates with multiple
orchestrators beyond Kubernetes. Its middleware system offers a plugin-like
model for cross-cutting concerns. Traefik is popular for smaller deployments
and developer environments. Its Go-based architecture makes it lightweight but
limits per-core throughput compared to NGINX-based controllers.
+
+### Kong Ingress Controller
+
+Kong pairs its API gateway with a Kubernetes controller and offers a path to
Kong's commercial API management platform. It provides a plugin ecosystem
comparable to APISIX's but uses a PostgreSQL or Cassandra database for
configuration storage, adding operational complexity compared to APISIX's
etcd-backed approach.
+
+## How Apache APISIX Works as a Kubernetes API Gateway
+
+The [APISIX Ingress Controller](/docs/ingress-controller/overview/) deploys
Apache APISIX as the data plane and a Kubernetes controller as the control
plane within the cluster.
+
+### Architecture
+
+The control plane watches Kubernetes resources (Ingress, Gateway API, and
APISIX custom resources) and translates them into APISIX routing configurations
via the Admin API. The data plane (APISIX instances) handles actual traffic
processing. This separation allows the data plane to scale independently based
on traffic volume.
+
+A typical production deployment runs 2-3 APISIX data plane replicas behind a
cloud load balancer, with a single controller replica (plus a standby) managing
configuration. The data plane stores active configuration in shared memory,
enabling sub-millisecond routing decisions without external lookups per request.
+
+### Gateway API Support
+
+APISIX Ingress Controller implements the Gateway API specification, supporting
GatewayClass, Gateway, and HTTPRoute resources. Platform teams define
GatewayClass and Gateway resources that configure the APISIX data plane.
Application teams create HTTPRoute resources that define routing rules for
their services.
+
+This role-based model aligns with enterprise organizational structures and
helps reduce misconfigurations compared to annotation-based Ingress resources.
+
+### Custom Resources
+
+Beyond standard Kubernetes APIs, APISIX Ingress Controller provides custom
resources (ApisixRoute, ApisixUpstream, ApisixPluginConfig) that expose the
full power of APISIX's plugin ecosystem. These CRDs allow Kubernetes-native
configuration of features like JWT authentication, rate limiting, request
transformation, and traffic mirroring without resorting to annotations.
+
+### Plugin Configuration
+
+APISIX's 80+ plugins can be configured through Kubernetes custom resources.
For example, enabling JWT authentication on a route requires adding a plugin
reference to the ApisixRoute resource. The controller translates this into
APISIX plugin configuration automatically. Plugin configurations can be shared
across routes using ApisixPluginConfig resources, reducing duplication.
+
+## Deployment Patterns
+
+### Single Cluster Gateway
+
+The simplest pattern deploys APISIX as the sole ingress point for a single
Kubernetes cluster. All external traffic enters through APISIX, which handles
TLS termination, routing, authentication, and rate limiting before forwarding
requests to cluster services. This pattern suits organizations with a single
production cluster handling moderate traffic volumes.
+
+### Multi-Cluster with Shared Gateway
+
+For organizations running multiple Kubernetes clusters (multi-region,
staging/production, or domain-separated), a shared APISIX deployment can route
traffic across clusters. APISIX's upstream configuration supports endpoints
outside the local cluster, enabling cross-cluster routing. Many organizations
now operate multiple production Kubernetes clusters, making cross-cluster
traffic management a common requirement.
+
+### Gateway Per Namespace
+
+Large organizations with multiple teams sharing a cluster may deploy separate
APISIX instances per namespace or per team. Each team manages its own gateway
configuration through Gateway API resources scoped to their namespace.
ReferenceGrant resources control cross-namespace access. This pattern provides
strong isolation between teams while sharing cluster infrastructure.
+
+### Sidecar Gateway
+
+For latency-sensitive workloads, APISIX can be deployed as a sidecar alongside
the application pod. This eliminates the network hop to a centralized gateway
but increases resource consumption and operational complexity. This pattern is
uncommon and typically reserved for specialized use cases where every
millisecond of latency matters.
+
+## FAQ
+
+### Should I use Ingress or Gateway API for new Kubernetes deployments?
+
+Use Gateway API for new deployments. Gateway API provides a richer feature
set, role-based ownership, and native support for traffic splitting, header
matching, and multi-protocol routing. Ingress will continue to work but
receives no new features. The Kubernetes SIG-Network has stated that Gateway
API is the future of Kubernetes traffic management. APISIX Ingress Controller
supports both, so you can migrate incrementally.
+
+### How does APISIX Ingress Controller compare to the NGINX Ingress Controller?
+
+APISIX offers dynamic configuration without reloads, a richer plugin ecosystem
(80+ plugins vs annotation-based configuration), native support for Gateway
API, and higher throughput per core. NGINX Ingress Controller has broader
community adoption and more third-party documentation. If your requirements
include advanced authentication, rate limiting, or request transformation,
APISIX provides these as native plugins rather than custom annotations.
+
+### Can I run multiple ingress controllers in the same Kubernetes cluster?
+
+Yes. Kubernetes supports multiple ingress controllers differentiated by
IngressClass (for Ingress resources) or GatewayClass (for Gateway API
resources). A common pattern runs APISIX for external-facing APIs requiring
authentication and rate limiting, and a lightweight controller like Traefik for
internal developer tools. Each Ingress or HTTPRoute resource specifies which
controller should handle it.
+
+### What is the resource overhead of running APISIX in Kubernetes?
+
+A production APISIX data plane replica typically requests 500m CPU and 256Mi
memory, handling 10,000-20,000 requests per second depending on plugin
configuration. The controller replica requests 200m CPU and 128Mi memory. For
most clusters, two data plane replicas and one controller replica provide
sufficient capacity and redundancy. These resource requirements are comparable
to other Kubernetes ingress controllers and negligible relative to the
application workloads they protect.
