This is an automated email from the ASF dual-hosted git repository.
kayx23 pushed a commit to branch v2.1.0
in repository https://gitbox.apache.org/repos/asf/apisix-ingress-controller.git
The following commit(s) were added to refs/heads/v2.1.0 by this push:
new da632fa3 docs: update 2.1 listener port guidance (#2787)
da632fa3 is described below
commit da632fa3988d81ca01cf735d44d6de2cf539b44c
Author: Traky Deng <[email protected]>
AuthorDate: Wed Jun 10 16:16:48 2026 +0800
docs: update 2.1 listener port guidance (#2787)
---
docs/en/latest/getting-started/configure-routes.md | 4 ++--
docs/en/latest/getting-started/key-authentication.md | 2 +-
docs/en/latest/getting-started/load-balancing.md | 2 +-
docs/en/latest/getting-started/rate-limiting.md | 2 +-
docs/en/latest/reference/example.md | 2 +-
docs/en/latest/reference/troubleshoot.md | 11 +++++++++++
6 files changed, 17 insertions(+), 6 deletions(-)
diff --git a/docs/en/latest/getting-started/configure-routes.md
b/docs/en/latest/getting-started/configure-routes.md
index 0bafd822..68f290da 100644
--- a/docs/en/latest/getting-started/configure-routes.md
+++ b/docs/en/latest/getting-started/configure-routes.md
@@ -42,7 +42,7 @@ This tutorial guides you through creating a Route using the
APISIX Ingress Contr
Install the httpbin example application on the cluster to test the
configuration:
```bash
-kubectl apply -f
https://raw.githubusercontent.com/apache/apisix-ingress-controller/refs/heads/v2.0.0/examples/httpbin/deployment.yaml
+kubectl apply -f
https://raw.githubusercontent.com/apache/apisix-ingress-controller/refs/heads/v2.1.0/examples/httpbin/deployment.yaml
```
## Configure a Route
@@ -86,7 +86,7 @@ spec:
name: apisix-config
```
-Note that the `port` in the Gateway listener is required but ignored. This is
due to limitations in the data plane: it cannot dynamically open new ports.
Since the Ingress Controller does not manage the data plane deployment, it
cannot automatically update the configuration or restart the data plane to
apply port changes.
+The `port` in the Gateway listener can be used for route matching based on
[`listener_port_match_mode`](../reference/configuration-file.md) (`auto`,
`explicit`, or `off`). The controller cannot dynamically open new ports on the
data plane, so ensure APISIX is configured to listen on the port.
</details>
diff --git a/docs/en/latest/getting-started/key-authentication.md
b/docs/en/latest/getting-started/key-authentication.md
index 51e0bc71..a9ecae99 100644
--- a/docs/en/latest/getting-started/key-authentication.md
+++ b/docs/en/latest/getting-started/key-authentication.md
@@ -76,7 +76,7 @@ spec:
name: apisix-config
```
-Note that the `port` in the Gateway listener is required but ignored. This is
due to limitations in the data plane: it cannot dynamically open new ports.
Since the Ingress Controller does not manage the data plane deployment, it
cannot automatically update the configuration or restart the data plane to
apply port changes.
+The `port` in the Gateway listener can be used for route matching based on
[`listener_port_match_mode`](../reference/configuration-file.md) (`auto`,
`explicit`, or `off`). The controller cannot dynamically open new ports on the
data plane, so ensure APISIX is configured to listen on the port.
</details>
diff --git a/docs/en/latest/getting-started/load-balancing.md
b/docs/en/latest/getting-started/load-balancing.md
index 15f17f74..a4b47db5 100644
--- a/docs/en/latest/getting-started/load-balancing.md
+++ b/docs/en/latest/getting-started/load-balancing.md
@@ -76,7 +76,7 @@ spec:
name: apisix-config
```
-Note that the `port` in the Gateway listener is required but ignored. This is
due to limitations in the data plane: it cannot dynamically open new ports.
Since the Ingress Controller does not manage the data plane deployment, it
cannot automatically update the configuration or restart the data plane to
apply port changes.
+The `port` in the Gateway listener can be used for route matching based on
[`listener_port_match_mode`](../reference/configuration-file.md) (`auto`,
`explicit`, or `off`). The controller cannot dynamically open new ports on the
data plane, so ensure APISIX is configured to listen on the port.
</details>
diff --git a/docs/en/latest/getting-started/rate-limiting.md
b/docs/en/latest/getting-started/rate-limiting.md
index 6a3a804f..d76ffd05 100644
--- a/docs/en/latest/getting-started/rate-limiting.md
+++ b/docs/en/latest/getting-started/rate-limiting.md
@@ -76,7 +76,7 @@ spec:
name: apisix-config
```
-Note that the `port` in the Gateway listener is required but ignored. This is
due to limitations in the data plane: it cannot dynamically open new ports.
Since the Ingress Controller does not manage the data plane deployment, it
cannot automatically update the configuration or restart the data plane to
apply port changes.
+The `port` in the Gateway listener can be used for route matching based on
[`listener_port_match_mode`](../reference/configuration-file.md) (`auto`,
`explicit`, or `off`). The controller cannot dynamically open new ports on the
data plane, so ensure APISIX is configured to listen on the port.
</details>
diff --git a/docs/en/latest/reference/example.md
b/docs/en/latest/reference/example.md
index b828dd9a..318770bc 100644
--- a/docs/en/latest/reference/example.md
+++ b/docs/en/latest/reference/example.md
@@ -96,7 +96,7 @@ spec:
❶ The controller name should be customized if you are running multiple
distinct instances of the APISIX Ingress Controller in the same cluster (not a
single instance with multiple replicas). Each ingress controller instance must
use a unique controllerName in its [configuration file](configuration-file.md),
and the corresponding GatewayClass should reference that value.
-❷ The `port` in the Gateway listener is used for routing matching based on
`listener_port_match_mode` in the controller configuration (`auto`, `explicit`,
or `off`). The controller cannot dynamically open new ports on the data plane,
so ensure APISIX is configured to listen on the port.
+❷ The `port` in the Gateway listener is used for routing matching based on
[`listener_port_match_mode`](configuration-file.md) (`auto`, `explicit`, or
`off`). The controller cannot dynamically open new ports on the data plane, so
ensure APISIX is configured to listen on the port.
❸ API group of the referenced resource.
diff --git a/docs/en/latest/reference/troubleshoot.md
b/docs/en/latest/reference/troubleshoot.md
index 5c8fdaed..d5df1c54 100644
--- a/docs/en/latest/reference/troubleshoot.md
+++ b/docs/en/latest/reference/troubleshoot.md
@@ -54,3 +54,14 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -H
"X-API-KEY: ${ADMIN_API_KEY}
```
For reference, see [Admin
API](https://apisix.apache.org/docs/apisix/admin-api/).
+
+## Gateway API Routes Return 404 After Upgrade
+
+After upgrading to APISIX Ingress Controller 2.1.0, Gateway API HTTPRoute or
GRPCRoute resources may return `404`. This can happen when Gateway listener
ports do not match the ports that APISIX actually listens on.
+
+In the default `listener_port_match_mode: auto` mode, the Ingress Controller
may inject a `server_port` route variable from the matched Gateway listener
ports. The `server_port` variable is evaluated by APISIX against its actual
listening port, such as `9080` or `9443`. If the Gateway listener uses `80` or
`443` but the gateway Service maps those ports to `9080` or `9443`, the route
may not match.
+
+To resolve the issue, use one of the following approaches:
+
+- Set [`listener_port_match_mode`](configuration-file.md) to `"off"` in the
controller configuration to disable `server_port` route-var injection.
+- Configure APISIX to listen on the same ports declared in the Gateway
listeners.
