docs: port docs changes (FAQ, explain port config and parameters in gateway class) (#265)

kayx23 · web-flow · commit 3334e78af017 · 2025-09-18T16:13:52.000+08:00
* port doc changes 2

* Fix config file
diff --git a/docs/en/latest/FAQ.md b/docs/en/latest/FAQ.md
@@ -0,0 +1,56 @@
+---
+title: FAQ
+keywords:
+- APISIX Ingress
+- Apache APISIX
+- Kubernetes Ingress
+- Gateway API
+- FAQ
+description: This document provides answers to frequently asked questions (FAQ) when using APISIX Ingress Controller.
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+This document provides answers to frequently asked questions (FAQ) when using APISIX Ingress Controller.
+
+### How does Ingress Controller handle route priority across multiple resources?
+
+In APISIX, a higher value indicates a higher route priority.
+
+* **Ingress:** Does not support explicit route priority. Routes created using Ingress are assigned a default priority of 0, typically the lowest.
+* **HTTPRoute:** Has a [38-bit priority](https://github.com/apache/apisix-ingress-controller/blob/master/internal/adc/translator/httproute.go#L428-L448). The priority calculation is dynamic and may change, making exact values difficult to predict.
+* **APISIXRoute:** Can be assigned an explicit priority. To have a higher priority than an HTTPRoute, the value must exceed 549,755,813,887 (2^39 − 1).
+
+### How do HTTPRoute filters interact with PluginConfig CRDs?
+
+APISIX maps built-in Gateway API HTTPRoute filters to specific plugins:
+
+* `RequestHeaderModifier` → `proxy-rewrite`
+* `RequestRedirect` → `redirect`
+* `RequestMirror` → `proxy-mirror`
+* `URLRewrite` → `proxy-rewrite`
+* `ResponseHeaderModifier` → `response-rewrite`
+* `CORS` → `cors`
+* `ExtensionRef` → user-defined plugin reference
+
+When both filters and a PluginConfig CRD are applied:
+
+* If filters are applied first, PluginConfig overrides any overlapping plugin settings.
+* If PluginConfig is applied first, filters merge with PluginConfig settings, and overlapping fields from filters take precedence.
diff --git a/docs/en/latest/config.json b/docs/en/latest/config.json
@@ -38,13 +38,18 @@
             "label": "Reference",
             "items": [
                 "reference/api-reference",
-                "reference/example"
+                "reference/example",
+                "reference/configuration-file"
             ]
         },
         {
             "type": "doc",
             "id": "upgrade-guide"
         },
+        {
+            "type": "doc",
+            "id": "FAQ"
+        },
         {
             "type": "link",
             "label": "CHANGELOG",
diff --git a/docs/en/latest/getting-started/configure-routes.md b/docs/en/latest/getting-started/configure-routes.md
@@ -86,9 +86,34 @@ 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.
+
+</details>
+
+If you are using Ingress or APISIX custom resources, you can proceed without additional configuration, as the IngressClass resource below is already applied with installation:
+
+<details>
+
+<summary>Show configuration</summary>
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: IngressClass
+metadata:
+  name: apisix
+spec:
+  controller: apisix.apache.org/apisix-ingress-controller
+  parameters:
+    apiGroup: apisix.apache.org
+    kind: GatewayProxy
+    name: apisix-config
+    namespace: ingress-apisix
+    scope: Namespace
+```
+
 </details>
 
-If you are using Ingress or APISIX custom resources, you can proceed without additional configuration.
+See [Define Controller and Gateway](../reference/example.md#define-controller-and-gateway) for more information on parameters.
 
 :::
 
diff --git a/docs/en/latest/getting-started/key-authentication.md b/docs/en/latest/getting-started/key-authentication.md
@@ -76,9 +76,34 @@ 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.
+
+</details>
+
+If you are using Ingress or APISIX custom resources, you can proceed without additional configuration, as the IngressClass resource below is already applied with installation:
+
+<details>
+
+<summary>Show configuration</summary>
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: IngressClass
+metadata:
+  name: apisix
+spec:
+  controller: apisix.apache.org/apisix-ingress-controller
+  parameters:
+    apiGroup: apisix.apache.org
+    kind: GatewayProxy
+    name: apisix-config
+    namespace: ingress-apisix
+    scope: Namespace
+```
+
 </details>
 
-If you are using Ingress or APISIX custom resources, you can proceed without additional configuration.
+See [Define Controller and Gateway](../reference/example.md#define-controller-and-gateway) for more information on parameters.
 
 :::
 
diff --git a/docs/en/latest/getting-started/load-balancing.md b/docs/en/latest/getting-started/load-balancing.md
@@ -76,9 +76,34 @@ 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.
+
+</details>
+
+If you are using Ingress or APISIX custom resources, you can proceed without additional configuration, as the IngressClass resource below is already applied with installation:
+
+<details>
+
+<summary>Show configuration</summary>
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: IngressClass
+metadata:
+  name: apisix
+spec:
+  controller: apisix.apache.org/apisix-ingress-controller
+  parameters:
+    apiGroup: apisix.apache.org
+    kind: GatewayProxy
+    name: apisix-config
+    namespace: ingress-apisix
+    scope: Namespace
+```
+
 </details>
 
-If you are using Ingress or APISIX custom resources, you can proceed without additional configuration.
+See [Define Controller and Gateway](../reference/example.md#define-controller-and-gateway) for more information on parameters.
 
 :::
 
diff --git a/docs/en/latest/getting-started/rate-limiting.md b/docs/en/latest/getting-started/rate-limiting.md
@@ -76,9 +76,34 @@ 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.
+
+</details>
+
+If you are using Ingress or APISIX custom resources, you can proceed without additional configuration, as the IngressClass resource below is already applied with installation:
+
+<details>
+
+<summary>Show configuration</summary>
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: IngressClass
+metadata:
+  name: apisix
+spec:
+  controller: apisix.apache.org/apisix-ingress-controller
+  parameters:
+    apiGroup: apisix.apache.org
+    kind: GatewayProxy
+    name: apisix-config
+    namespace: ingress-apisix
+    scope: Namespace
+```
+
 </details>
 
-If you are using Ingress or APISIX custom resources, you can proceed without additional configuration.
+See [Define Controller and Gateway](../reference/example.md#define-controller-and-gateway) for more information on parameters.
 
 :::
 
diff --git a/docs/en/latest/reference/configuration-file.md b/docs/en/latest/reference/configuration-file.md
@@ -0,0 +1,74 @@
+---
+title: Configuration File
+slug: /reference/apisix-ingress-controller/configuration-file
+description: Configure the APISIX Ingress Controller using the config.yaml file, including configurations such as log settings, leader election, metrics, and sync behavior.
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+The APISIX Ingress Controller uses a configuration file `config.yaml` to define core settings such as log level, leader election behavior, metrics endpoints, and sync intervals.
+
+Configurations are defined in a Kubernetes ConfigMap and mounted into the controller pod as a file at runtime. To apply changes, you can update the ConfigMap and restart the controller Deployment to reload the configurations.
+
+Below are all available configuration options, including their default values and usage:
+
+```yaml
+log_level: "info"                               # The log level of the APISIX Ingress Controller.
+                                                # The default value is "info".
+
+controller_name: apisix.apache.org/apisix-ingress-controller  # The controller name of the APISIX Ingress Controller,
+                                                              # which is used to identify the controller in the GatewayClass.
+                                                              # The default value is "apisix.apache.org/apisix-ingress-controller".
+leader_election_id: "apisix-ingress-controller-leader"    # The leader election ID for the APISIX Ingress Controller.
+                                                          # The default value is "apisix-ingress-controller-leader".
+leader_election:
+  lease_duration: 30s                   # lease_duration is the duration that non-leader candidates will wait
+                                        # after observing a leadership renewal until attempting to acquire leadership of a
+                                        # leader election.
+  renew_deadline: 20s                   # renew_deadline is the time in seconds that the acting controller
+                                        # will retry refreshing leadership before giving up.
+  retry_period: 2s                      # retry_period is the time in seconds that the acting controller
+                                        # will wait between tries of actions with the controller.
+  disable: false                        # Whether to disable leader election.
+
+metrics_addr: ":8080"                   # The address the metrics endpoint binds to.
+                                        # The default value is ":8080".
+
+enable_http2: false                     # Whether to enable HTTP/2 for the server.
+                                        # The default value is false.
+
+probe_addr: ":8081"                     # The address the probe endpoint binds to.
+                                        # The default value is ":8081".
+
+secure_metrics: false                   # The secure metrics configuration.
+                                        # The default value is "" (empty).
+
+exec_adc_timeout: 15s                   # The timeout for the ADC to execute.
+                                        # The default value is 15 seconds.
+
+provider:
+  type: "api7ee"                        # Provider type.
+
+  sync_period: 0s                       # The period between two consecutive syncs.
+                                        # The default value is 0 seconds, which means the controller will not sync.
+                                        # If you want to enable the sync, set it to a positive value.
+  init_sync_delay: 20m                  # The initial delay before the first sync, only used when the controller is started.
+                                        # The default value is 20 minutes.
+```
diff --git a/docs/en/latest/reference/example.md b/docs/en/latest/reference/example.md
@@ -4,6 +4,25 @@ slug: /reference/apisix-ingress-controller/examples
 description: Explore a variety of APISIX Ingress Controller configuration examples to help you customize settings to suit your environment effectively.
 ---
 
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
@@ -52,9 +71,10 @@ values={[
 apiVersion: gateway.networking.k8s.io/v1
 kind: GatewayClass
 metadata:
+  namespace: ingress-apisix
   name: apisix
 spec:
-  controllerName: "apisix.apache.org/apisix-ingress-controller"
+  controllerName: "apisix.apache.org/apisix-ingress-controller"    # 1
 ---
 apiVersion: gateway.networking.k8s.io/v1
 kind: Gateway
@@ -66,14 +86,24 @@ spec:
   listeners:
   - name: http
     protocol: HTTP
-    port: 80
+    port: 80                    # 2
   infrastructure:
     parametersRef:
-      group: apisix.apache.org
-      kind: GatewayProxy
-      name: apisix-config
+      group: apisix.apache.org  # 3
+      kind: GatewayProxy        # 4
+      name: apisix-config       # 5
 ```
 
+❶ The controllerName field in GatewayClass needs to 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 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.
+
+❸ API group of the referenced resource.
+
+❹ Kind of the referenced resource.
+
+❺ Name of the referenced resource. Should match the `metadata.name` of the GatewayProxy resource.
+
 </TabItem>
 
 <TabItem value="ingress">
@@ -102,6 +132,7 @@ spec:
 apiVersion: networking.k8s.io/v1
 kind: IngressClass
 metadata:
+  namespace: ingress-apisix
   name: apisix
 spec:
   controller: apisix.apache.org/apisix-ingress-controller
