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-ingress-controller.git
The following commit(s) were added to refs/heads/master by this push:
new d510f665 docs: clarify Ingress route configuration and deployment
architecture (#2848)
d510f665 is described below
commit d510f6656c5d2289dbb9b4c02c3c3473ff8abb2f
Author: Yilia Lin <[email protected]>
AuthorDate: Tue Aug 18 10:17:05 2026 +0800
docs: clarify Ingress route configuration and deployment architecture
(#2848)
---
docs/en/latest/concepts/deployment-architecture.md | 13 +++++++++----
docs/en/latest/concepts/resources.md | 6 +++++-
docs/en/latest/getting-started/configure-routes.md | 21 ++++++++++++++-------
docs/en/latest/overview.md | 4 ++--
4 files changed, 30 insertions(+), 14 deletions(-)
diff --git a/docs/en/latest/concepts/deployment-architecture.md
b/docs/en/latest/concepts/deployment-architecture.md
index e8b5c9b0..8444f7b8 100644
--- a/docs/en/latest/concepts/deployment-architecture.md
+++ b/docs/en/latest/concepts/deployment-architecture.md
@@ -5,6 +5,7 @@ keywords:
- Apache APISIX
- Kubernetes Ingress
- Gateway API
+description: Understand how APISIX Ingress Controller translates Kubernetes
resources and configures Apache APISIX in Admin API or Standalone mode.
---
<!--
#
@@ -25,18 +26,22 @@ keywords:
#
-->
-The APISIX Ingress Controller is used to manage the APISIX Gateway as either a
standalone application or a Kubernetes-based application. It dynamically
configures and manages the APISIX Gateway using Gateway API resources.
+APISIX Ingress Controller watches Kubernetes Ingress, Gateway API, and APISIX
custom resources, translates their desired state into Apache APISIX
configuration, and keeps the gateway configuration synchronized. APISIX remains
the data plane that receives and proxies traffic.
+
+The controller can deliver configuration to APISIX through Admin API mode or
Standalone API-driven mode. See [APISIX Ingress Controller
Resources](./resources.md) for the Kubernetes resources the controller watches
and [Configure Routes](../getting-started/configure-routes.md) for a working
routing example.
## Admin API Mode
-In the traditional deployment approach, APISIX uses etcd as its configuration
center, allowing administrators to dynamically manage routes, upstreams, and
other resources through RESTful APIs. It supports distributed cluster
deployments with real-time configuration synchronization.
+In Admin API mode, APISIX uses etcd as its configuration center. APISIX
Ingress Controller sends translated routes, upstreams, and other resources to
the APISIX Admin API, and APISIX stores the configuration in etcd. This mode
supports distributed APISIX clusters with dynamic configuration synchronization.
## Standalone Mode (Experimental)
-APISIX runs independently without relying on etcd, supporting two sub-modes -
file-driven (managing configuration through conf/apisix.yaml files) and
API-driven (storing configuration in memory with full configuration management
through the dedicated /apisix/admin/configs endpoint).
+APISIX Standalone mode does not require etcd. It supports file-driven
configuration through `conf/apisix.yaml` and API-driven configuration stored in
memory through the `/apisix/admin/configs` endpoint.
-This mode is particularly suitable for Kubernetes environments and single-node
deployments, where the API-driven memory management approach combines the
convenience of traditional Admin API with the simplicity of Standalone mode.
+APISIX Ingress Controller uses the API-driven variant to publish the complete
configuration to APISIX. This mode reduces external dependencies in Kubernetes
and single-node deployments, but it is currently experimental.
+
+Configure the control plane mode, endpoint or Service, TLS verification, and
authentication with `GatewayProxy`. See [Configure CP Endpoint and Admin
Key](../reference/example.md#configure-cp-endpoint-and-admin-key) for an
example and the [ControlPlaneProvider API
reference](../reference/api-reference.md#controlplaneprovider) for all
available fields.
diff --git a/docs/en/latest/concepts/resources.md
b/docs/en/latest/concepts/resources.md
index ca9de166..574c29fb 100644
--- a/docs/en/latest/concepts/resources.md
+++ b/docs/en/latest/concepts/resources.md
@@ -74,7 +74,11 @@ Enable additional features not included in the standard
Kubernetes Gateway API,
APISIX Ingress Controller CRDs extend Kubernetes functionality to provide
declarative configuration management for the Apache APISIX gateway, supporting
advanced routing, traffic management, and security policies.
-* ApisixRoute: Defines routing rules for HTTP/TCP/UDP, supporting path
matching, hostnames, method filtering, and backend service configurations. Can
reference ApisixUpstream and ApisixPluginConfig resources.
+#### ApisixRoute
+
+`ApisixRoute` defines HTTP, TCP, and UDP routing rules with request matching
and backend Service configuration. Use it when a route needs APISIX-specific
capabilities that are not represented by the standard Kubernetes Ingress API.
An `ApisixRoute` can also reference `ApisixUpstream` and `ApisixPluginConfig`
resources to separate upstream and plugin configuration from the route.
+
+Follow [Configure Routes](../getting-started/configure-routes.md) for a
working `ApisixRoute` example. See the [ApisixRoute API
reference](../reference/api-reference.md#apisixroute) for its complete schema.
* ApisixUpstream: Extends Kubernetes Services with advanced configurations
such as load balancing, health checks, retries, timeouts, and service subset
selection.
diff --git a/docs/en/latest/getting-started/configure-routes.md
b/docs/en/latest/getting-started/configure-routes.md
index 1c1042a4..58b43ab5 100644
--- a/docs/en/latest/getting-started/configure-routes.md
+++ b/docs/en/latest/getting-started/configure-routes.md
@@ -1,10 +1,11 @@
---
title: Configure Routes
keywords:
- - APISIX ingress
- - Apache APISIX
- - Kubernetes ingress
-description: Learn how to create routes in APISIX using APISIX Ingress
controller to forward client to upstream services.
+ - APISIX Ingress Controller
+ - ApisixRoute
+ - Kubernetes Gateway API
+ - Kubernetes Ingress
+description: Configure routes to Kubernetes Services with Gateway API,
Kubernetes Ingress, or the ApisixRoute CRD using APISIX Ingress Controller.
---
<!--
@@ -29,9 +30,9 @@ description: Learn how to create routes in APISIX using
APISIX Ingress controlle
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
-Apache APISIX provides flexible gateway management capabilities based on
routes, in which routing paths and target upstreams are defined.
+APISIX Ingress Controller translates Kubernetes routing resources into Apache
APISIX configuration. You can use Gateway API, Kubernetes Ingress, or the
APISIX-native `ApisixRoute` custom resource to define request matching and
target services.
-This tutorial guides you through creating a Route using the APISIX Ingress
Controller and verifying its behavior. You’ll configure a Route to a sample
Upstream pointing to an httpbin service, then send a request to observe how
APISIX proxies the traffic.
+This tutorial creates the same HTTP route with each API and verifies how
APISIX proxies traffic to an httpbin Service. See [APISIX Ingress Controller
Resources](../concepts/resources.md) for a comparison of the supported resource
types and the [ApisixRoute API
reference](../reference/api-reference.md#apisixroute) for field-level details.
## Prerequisites
@@ -49,7 +50,11 @@ kubectl apply -f
https://raw.githubusercontent.com/apache/apisix-ingress-control
In this section, you will create a Route that forwards client requests to the
httpbin example application, an HTTP request and response service.
-You can use either Gateway API, Ingress, or APISIX CRD resources to configure
the route.
+Choose the resource that matches how your Kubernetes platform manages traffic:
+
+- Gateway API `HTTPRoute` provides a portable Kubernetes routing API.
+- Kubernetes `Ingress` supports the standard Ingress API.
+- `ApisixRoute` exposes APISIX-specific routing capabilities through a custom
resource.
:::important
@@ -177,6 +182,8 @@ spec:
<TabItem value="apisix-crd">
+Use `ApisixRoute` when you need APISIX-native route configuration. For all
available fields, see the [ApisixRoute API
reference](../reference/api-reference.md#apisixroute).
+
```yaml title="httpbin-route.yaml"
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
diff --git a/docs/en/latest/overview.md b/docs/en/latest/overview.md
index 81a9723c..187b8e61 100644
--- a/docs/en/latest/overview.md
+++ b/docs/en/latest/overview.md
@@ -30,7 +30,7 @@ APISIX Ingress Controller is a [Kubernetes ingress
controller](https://kubernete
APISIX Ingress Controller can be configured using the native Kubernetes
Ingress or Gateway API, as well as with APISIX’s own declarative and
easy-to-use custom resources. The controller translates these resources into
APISIX configuration.
-See the [Getting Started
tutorials](./getting-started/get-apisix-ingress-controller.md) to set up and
start using the APISIX Ingress Controller.
+See the [Getting Started
tutorials](./getting-started/get-apisix-ingress-controller.md) to install
APISIX Ingress Controller. Then review the [supported
resources](./concepts/resources.md), [configure a
route](./getting-started/configure-routes.md), or learn how the controller
[delivers configuration to APISIX](./concepts/deployment-architecture.md).
## Features
@@ -40,7 +40,7 @@ To summarize, APISIX ingress controller has the following
features:
- Supports native Kubernetes Ingress v1 and Gateway API.
- Supports service discovery through Kubernetes Service.
- Supports load balancing based on pods (Upstream nodes).
-- Rich
[Plugins](https://apisix.apache.org/docs/apisix/next/plugins/batch-requests/)
with [custom
Plugin](https://apisix.apache.org/docs/apisix/next/plugin-develop/) support.
+- Rich
[Plugins](https://apisix.apache.org/docs/apisix/plugins/batch-requests/) with
[custom Plugin](https://apisix.apache.org/docs/apisix/plugin-develop/) support.
## Get involved
