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 3d4d833b docs: update gateway api docs (#2558)
3d4d833b is described below
commit 3d4d833b7e893c39dd973f030ccb33fe0528b7c3
Author: Traky Deng <[email protected]>
AuthorDate: Mon Sep 15 16:45:00 2025 +0800
docs: update gateway api docs (#2558)
---
docs/en/latest/concepts/gateway-api.md | 88 +++++++++++++---------------------
1 file changed, 33 insertions(+), 55 deletions(-)
diff --git a/docs/en/latest/concepts/gateway-api.md
b/docs/en/latest/concepts/gateway-api.md
index 7954537a..ce431a71 100644
--- a/docs/en/latest/concepts/gateway-api.md
+++ b/docs/en/latest/concepts/gateway-api.md
@@ -9,11 +9,11 @@ keywords:
<!--
#
# Licensed to the Apache Software Foundation (ASF) under one or more
-# contributor license agreements. See the NOTICE file distributed with
+# 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
+# the License. You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
@@ -31,11 +31,15 @@ By supporting Gateway API, the APISIX Ingress controller
can realize richer func
## Concepts
-- **GatewayClass**: Defines a set of Gateways that share a common
configuration and behavior. Each GatewayClass is handled by a single
controller, although controllers may handle more than one GatewayClass.
-- **Gateway**: A resource in Kubernetes that describes how traffic can be
translated to services within the cluster.
-- **HTTPRoute**: Can be attached to a Gateway to configure HTTP
-
-For more information about Gateway API, please refer to [Gateway
API](https://gateway-api.sigs.k8s.io/).
+- **GatewayClass**: Defines a class of Gateways with a shared configuration
and behavior. Each GatewayClass is managed by a single controller, although a
controller may support multiple GatewayClasses.
+- **Gateway**: Represents a request for network traffic handling within the
cluster. A Gateway specifies how traffic enters the cluster and is directed to
backend Services, typically by binding to one or more listeners.
+- **HTTPRoute**: Configures routing for HTTP traffic.
+- **GRPCRoute**: Configures routing for gRPC traffic.
+- **ReferenceGrant**: Grants permission to reference resources across
namespaces.
+- **TLSRoute**: Defines routing rules for terminating or passing through TLS
traffic.
+- **TCPRoute**: Configures routing for TCP traffic.
+- **UDPRoute**: Configures routing for UDP traffic.
+- **BackendTLSPolicy**: Specifies how a Gateway should validate TLS
connections to its backends, including trusted certificate authorities and
verification modes.
## Gateway API Support Level
@@ -45,64 +49,38 @@ For more information about Gateway API, please refer to
[Gateway API](https://ga
| Gateway | Partially supported | Partially supported | Not
supported | v1 |
| HTTPRoute | Supported | Partially supported | Not
supported | v1 |
| GRPCRoute | Not supported | Not supported | Not
supported | v1 |
-| ReferenceGrant | Not supported | Not supported | Not
supported | v1beta1 |
+| ReferenceGrant | Supported | Not supported | Not
supported | v1beta1 |
| TLSRoute | Not supported | Not supported | Not
supported | v1alpha2 |
| TCPRoute | Not supported | Not supported | Not
supported | v1alpha2 |
| UDPRoute | Not supported | Not supported | Not
supported | v1alpha2 |
| BackendTLSPolicy | Not supported | Not supported | Not
supported | v1alpha3 |
-## HTTPRoute
+## Examples
-The HTTPRoute resource allows users to configure HTTP routing by matching HTTP
traffic and forwarding it to Kubernetes backends. Currently, the only backend
supported by APISIX Gateway is the Service resource.
+For configuration examples, see the Gateway API tabs in [Configuration
Examples](../reference/example.md).
-### Example
+For a complete list of configuration options, refer to the [Gateway API
Reference](https://gateway-api.sigs.k8s.io/reference/spec/). Be aware that some
fields are not supported, or partially supported.
-The following example demonstrates how to configure an HTTPRoute resource to
route traffic to the `httpbin` service:
+## Unsupported / Partially Supported Fields
-```yaml
-apiVersion: gateway.networking.k8s.io/v1
-kind: GatewayClass
-metadata:
- namespace: ingress-apisix
- name: apisix
-spec:
- controllerName: "apisix.apache.org/apisix-ingress-controller"
+The fields below are specified in the Gateway API specification but are either
partially implemented or not yet supported in the APISIX Ingress Controller.
----
+### HTTPRoute
-apiVersion: gateway.networking.k8s.io/v1
-kind: Gateway
-metadata:
- namespace: ingress-apisix
- name: apisix
-spec:
- gatewayClassName: apisix
- listeners:
- - name: http
- protocol: HTTP
- port: 80
+| Fields | Status | Notes
|
+|--------------------------------|------------------------|-----------------------------------------------------------------------------------------|
+| `spec.timeouts` | Not supported | The field is
unsupported because ADC provides finer-grained timeout configuration (connect,
read, write), whereas `spec.timeouts` only allows a general total timeout and
upstream timeout, so it cannot be directly mapped. To configure route timeouts,
you can use
[BackendTrafficPolicy](../reference/api-reference.md#backendtrafficpolicyspec).
|
+| `spec.retries` | Not supported | The field is
unsupported because APISIX does not support the features in retries. To
configure route retries, you can use
[BackendTrafficPolicy](../reference/api-reference.md#backendtrafficpolicyspec).
|
+| `spec.sessionPersistence` | Not supported | APISIX does not
support the configuration of cookie lifetimes. As an alternative, you can use
[`chash` load balancer](../reference/api-reference.md#loadbalancer). |
+| `spec.rules[].backendRefs[].filters[]` | Not supported | BackendRef-level
filters are not implemented as data plane does not support filtering at this
level; only rule-level filters (`spec.rules[].filters[]`) are supported. |
----
+### Gateway
-apiVersion: gateway.networking.k8s.io/v1
-kind: HTTPRoute
-metadata:
- namespace: ingress-apisix
- name: httpbin
-spec:
- parentRefs:
- - name: apisix
- hostnames:
- - backends.example
- rules:
- - matches:
- - path:
- type: Exact
- value: /get
- - path:
- type: Exact
- value: /headers
- backendRefs:
- - name: httpbin
- port: 80
-```
+| Fields | Status
| Notes
|
+|------------------------------------------------------|----------------------|------------------------------------------------------------------------------------------------|
+| `spec.listeners[].port` | Not supported* | The configuration
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. |
+| `spec.listeners[].allowedRoutes.kinds` | Partially supported
| Only `HTTPRoute` (group `gateway.networking.k8s.io`) is accepted; other kinds
are rejected. |
+| `spec.listeners[].tls.certificateRefs[].group` | Partially supported | Only
`""` is supported; other group values cause validation failure. |
+| `spec.listeners[].tls.certificateRefs[].kind` | Partially supported
| Only `Secret` is supported.
|
+| `spec.listeners[].tls.mode` | Partially supported
| `Terminate` is implemented; `Passthrough` is effectively unsupported for
Gateway listeners. |
+| `spec.addresses` | Not supported
| Controller does not read or act on `spec.addresses`.
|
