docs: add config.yaml reference doc; explain a few parameters and gateway port being ignored (#2552)

kayx23 · web-flow · commit a47c8c6e2c26 · 2025-09-18T14:30:02.000+08:00
diff --git a/config/samples/config.yaml b/config/samples/config.yaml
@@ -1,11 +1,11 @@
 log_level: "info"                               # The log level of the APISIX Ingress Controller.
-                                                # the default value is "info".
+                                                # 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".
+                                                              # 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
@@ -27,18 +27,18 @@ enable_http2: false                     # Whether to enable HTTP/2 for the serve
 probe_addr: ":8081"                     # The address the probe endpoint binds to.
                                         # The default value is ":8081".
 
-secure_metrics: false                      # The secure metrics configuration.
+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: "apisix"
+  type: "apisix"                        # Provider type.
+                                        # Value can be "apisix" or "apisix-standalone".
 
-  sync_period: 1h
-                                        # The period between two consecutive syncs.
+  sync_period: 1h                       # The period between two consecutive syncs.
                                         # The default value is 1 hour, 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.
+  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/config.json b/docs/en/latest/config.json
@@ -38,7 +38,8 @@
             "label": "Reference",
             "items": [
                 "reference/api-reference",
-                "reference/example"
+                "reference/example",
+                "reference/configuration-file"
             ]
         },
         {
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,75 @@
+---
+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: "apisix"                        # Provider type.
+                                        # Value can be "apisix" or "apisix-standalone".
+
+  sync_period: 1h                       # The period between two consecutive syncs.
+                                        # The default value is 1 hour, 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';
 
@@ -56,7 +75,7 @@ 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
@@ -68,14 +87,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">

Original file line number	Diff line number	Diff line change
`@@ -38,7 +38,8 @@`
`38`	`38`	`"label": "Reference",`
`39`	`39`	`"items": [`
`40`	`40`	`"reference/api-reference",`
`41`		`- "reference/example"`
	`41`	`+ "reference/example",`
	`42`	`+ "reference/configuration-file"`
`42`	`43`	`]`
`43`	`44`	`},`
`44`	`45`	`{`