You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by yi...@apache.org on 2026/08/18 02:17:11 UTC
(apisix-ingress-controller) branch master updated: docs: clarify Ingress route configuration and deployment architecture (#2848)

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 <Yi...@apache.org>
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.
 
 ![Admin API Architecture](../../../assets/images/ingress-admin-api-architecture.png)
 
 ## 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.
 
 ![Standalone Architecture](../../../assets/images/ingress-standalone-architecture.png)
+
+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