Skip to main content
Version: Next

Gateway API

Gateway API is dedicated to achieving expressive and scalable Kubernetes service networking through various custom resources.

By supporting Gateway API, the APISIX Ingress controller can realize richer functions, including Gateway management, multi-cluster support, and other features. It is also possible to manage running instances of the APISIX gateway through Gateway API resource management.

Concepts#

  • 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#

ResourceCore Support LevelExtended Support LevelImplementation-Specific Support LevelAPI Version
GatewayClassSupportedN/ANot supportedv1
GatewayPartially supportedPartially supportedNot supportedv1
HTTPRouteSupportedPartially supportedNot supportedv1
GRPCRouteNot supportedNot supportedNot supportedv1
ReferenceGrantSupportedNot supportedNot supportedv1beta1
TLSRouteNot supportedNot supportedNot supportedv1alpha2
TCPRouteNot supportedNot supportedNot supportedv1alpha2
UDPRouteNot supportedNot supportedNot supportedv1alpha2
BackendTLSPolicyNot supportedNot supportedNot supportedv1alpha3

Examples#

For configuration examples, see the Gateway API tabs in Configuration Examples.

For a complete list of configuration options, refer to the Gateway API Reference. Be aware that some fields are not supported, or partially supported.

Unsupported / Partially Supported Fields#

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#

FieldsStatusNotes
spec.timeoutsNot supportedThe 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.
spec.retriesNot supportedThe field is unsupported because APISIX does not support the features in retries. To configure route retries, you can use BackendTrafficPolicy.
spec.sessionPersistenceNot supportedAPISIX does not support the configuration of cookie lifetimes. As an alternative, you can use chash load balancer.
spec.rules[].backendRefs[].filters[]Not supportedBackendRef-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#

FieldsStatusNotes
spec.listeners[].portNot 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.kindsPartially supportedOnly HTTPRoute (group gateway.networking.k8s.io) is accepted; other kinds are rejected.
spec.listeners[].tls.certificateRefs[].groupPartially supportedOnly "" is supported; other group values cause validation failure.
spec.listeners[].tls.certificateRefs[].kindPartially supportedOnly Secret is supported.
spec.listeners[].tls.modePartially supportedTerminate is implemented; Passthrough is effectively unsupported for Gateway listeners.
spec.addressesNot supportedController does not read or act on spec.addresses.