From 1bbea862560b93381fd958b45553612f414ee3c0 Mon Sep 17 00:00:00 2001 From: traky Date: Thu, 18 Sep 2025 14:52:18 +0800 Subject: [PATCH 1/2] port doc changes 2 --- docs/en/latest/FAQ.md | 56 ++++++++++++++ docs/en/latest/config.json | 7 +- .../getting-started/configure-routes.md | 27 ++++++- .../getting-started/key-authentication.md | 27 ++++++- .../latest/getting-started/load-balancing.md | 27 ++++++- .../latest/getting-started/rate-limiting.md | 27 ++++++- .../en/latest/reference/configuration-file.md | 75 +++++++++++++++++++ docs/en/latest/reference/example.md | 41 ++++++++-- 8 files changed, 277 insertions(+), 10 deletions(-) create mode 100644 docs/en/latest/FAQ.md create mode 100644 docs/en/latest/reference/configuration-file.md diff --git a/docs/en/latest/FAQ.md b/docs/en/latest/FAQ.md new file mode 100644 index 000000000..4ad421cdb --- /dev/null +++ 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. +--- + + + +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 index 99f0924e8..92045e808 100644 --- 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 index c90be316c..0bafd8223 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. + + + +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: + +
+ +Show configuration + +```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 +``` +
-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 54f8c54ed..d4702befc 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. + + + +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: + +
+ +Show configuration + +```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 +``` +
-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 5a4304110..3827528fc 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. + + + +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: + +
+ +Show configuration + +```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 +``` +
-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 ca852b233..6dc92149c 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. + + + +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: + +
+ +Show configuration + +```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 +``` +
-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 000000000..b01b0294b --- /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. +--- + + + +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 cf614ccbf..1cb7dd648 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. --- + + 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. + @@ -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 From b9e75cd1b38c92392f104d69340bcaf986583d96 Mon Sep 17 00:00:00 2001 From: traky Date: Thu, 18 Sep 2025 14:55:36 +0800 Subject: [PATCH 2/2] Fix config file --- docs/en/latest/reference/configuration-file.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/en/latest/reference/configuration-file.md b/docs/en/latest/reference/configuration-file.md index b01b0294b..dc3d82c7f 100644 --- a/docs/en/latest/reference/configuration-file.md +++ b/docs/en/latest/reference/configuration-file.md @@ -36,8 +36,8 @@ log_level: "info" # The log level of the APISIX In 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_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 @@ -64,11 +64,10 @@ 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". + type: "api7ee" # Provider type. - sync_period: 1h # The period between two consecutive syncs. - # The default value is 1 hour, which means the controller will not sync. + 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.