This is an automated email from the ASF dual-hosted git repository.
traky 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 a47c8c6e docs: add config.yaml reference doc; explain a few parameters
and gateway port being ignored (#2552)
a47c8c6e is described below
commit a47c8c6e2c26abe943a8b8970b181fea1d64e6d9
Author: Traky Deng <[email protected]>
AuthorDate: Thu Sep 18 14:30:02 2025 +0800
docs: add config.yaml reference doc; explain a few parameters and gateway
port being ignored (#2552)
---
config/samples/config.yaml | 20 +++---
docs/en/latest/config.json | 3 +-
docs/en/latest/getting-started/configure-routes.md | 27 +++++++-
.../latest/getting-started/key-authentication.md | 27 +++++++-
docs/en/latest/getting-started/load-balancing.md | 27 +++++++-
docs/en/latest/getting-started/rate-limiting.md | 27 +++++++-
docs/en/latest/reference/configuration-file.md | 75 ++++++++++++++++++++++
docs/en/latest/reference/example.md | 39 +++++++++--
8 files changed, 225 insertions(+), 20 deletions(-)
diff --git a/config/samples/config.yaml b/config/samples/config.yaml
index a8e663fd..f16265b9 100644
--- 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
index a746e3ba..92045e80 100644
--- 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
index c90be316..0bafd822 100644
--- 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
index 54f8c54e..d4702bef 100644
--- 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
index 5a430411..3827528f 100644
--- 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
index ca852b23..6dc92149 100644
--- 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
new file mode 100644
index 00000000..b01b0294
--- /dev/null
+++ 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
index 746a5d7d..ce4c4c1d 100644
--- 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">
