Ingress and Gateway API Support
The Ingress Controller reconciles Kubernetes Gateway API and Ingress resources. The support tables identify the APIs and fields available for production manifests.
The configuration examples show when and how to use each resource type.
Gateway API
Gateway API separates infrastructure, Gateway, and Route configuration so that each can be managed by a different team. See Delegate Gateway API Access with Kubernetes RBAC to configure user permissions, and Configure Cross-Namespace References to authorize Route attachment and references between namespaces.
Gateway API Version
- Gateway API 1.6.0 release
- Gateway API 1.6.0 API definitions
gateway.networking.k8s.io/v1
The compatible controller charts listed in the Helm chart reference install Gateway API 1.6.0 standard-channel CRDs. These CRDs include the v1 L4 Route APIs used by the support matrix. A chart-managed installation does not require a separate CRD command.
If the cluster platform owns Gateway API CRDs, have that owner install the 1.6.0 standard bundle before the controller release. Configure the controller chart to skip its bundled CRDs.
For a manually managed bundle, use server-side apply because the CRDs exceed the client-side annotation size limit:
kubectl apply --server-side --force-conflicts \
-f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.6.0/standard-install.yaml
Do not run this manual command against CRDs managed by the chart, a GitOps release, or another platform component.
Resource Support Levels
The table below outlines the support levels for Gateway API resources in the current implementation. It describes implemented behavior and is not an upstream conformance claim.
| Resource | Core | Extended | Implementation-Specific | API Version |
|---|---|---|---|---|
| GatewayClass | Supported | N/A | Not supported | v1 |
| Gateway | Partially supported | Partially supported | Not supported | v1 |
| HTTPRoute | Supported | Partially supported | Not supported | v1 |
| GRPCRoute | Supported | Supported | Not supported | v1 |
| ReferenceGrant | Supported | Not supported | Not supported | v1 |
| TLSRoute | Supported | Supported | Not supported | v1 |
| TCPRoute | Supported | Supported | Not supported | v1 |
| UDPRoute | Supported | Supported | Not supported | v1 |
| BackendTLSPolicy | Not supported | Not supported | Not supported | v1 |
For a complete list of configuration options, refer to the Gateway API 1.6.0 API definitions. Some fields are unsupported or partially supported as described below.
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 Ingress Controller.
HTTPRoute
| 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. |
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. |
spec.sessionPersistence | Not supported | APISIX does not support the configuration of cookie lifetimes. As an alternative, you can use chash load balancer. |
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
| Fields | Status | Notes |
|---|---|---|
spec.listeners[].port | Partially supported | The controllers compare this field with a route's parentRefs[].port when the route targets a listener by port. When listener_port_match_mode injects a server_port predicate, it must equal the physical gateway listener port. The controllers do not open data-plane ports. |
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.tls.frontend.default.validation.caCertificateRefs | Partially supported | ConfigMap is supported as the Gateway API Core behavior. Secret is also supported as an implementation-specific extension. CA references use the ca.crt key. AllowInsecureFallback is not supported. |
spec.tls.frontend.perPort | Supported | A per-port configuration overrides the default client-certificate validation for the listener on that port. |
spec.addresses | Not supported | Controller does not read or act on spec.addresses. |
APISIX Ingress Controller does not add a server_port predicate when every matched listener defines spec.listeners[].hostname. As a result, attaching a route to such a listener does not restrict the generated route to its port. API7 Ingress Controller can include hostname listeners in port matching. To require APISIX port matching, omit the listener hostname and configure the host on the HTTPRoute or GRPCRoute instead. See the configuration reference for the mode triggers and common issues for physical-port mismatch recovery.
For a working client-certificate validation example, see Configure mTLS Between Client and Gateway.
HTTP Route Filters
Ingress Controller maps standard Gateway API filters in HTTPRoute resources to corresponding plugins:
| Gateway API Filter | Plugin |
|---|---|
RequestHeaderModifier | proxy-rewrite |
RequestRedirect | redirect |
RequestMirror | proxy-mirror |
URLRewrite | proxy-rewrite |
ResponseHeaderModifier | response-rewrite |
CORS | cors |
ExtensionRef | plugins from a same-namespace PluginConfig |
An HTTPRoute rule can use standard filters and an ExtensionRef when they configure different plugins. Do not configure the same underlying plugin through both mechanisms on one rule; overlapping entries are not merged reliably and can prevent the route from being translated.
Ingress
Package
- networking.k8s.io/v1
Supported Resources
The controller supports the standard Kubernetes Ingress API, including:
Basic host- and path-based routing is supported. For supported Ingress annotations and usage examples, see the annotations reference.
With APISIX or API7 Gateway, an Ingress rule host such as *.example.com is matched as a suffix. It matches both foo.example.com and bar.foo.example.com, but does not match the bare example.com domain. This is broader than the single-label wildcard behavior described in the Kubernetes Ingress documentation.
List each host explicitly when a route must accept only specific subdomains. HTTPRoute wildcards also match multiple leading labels, as defined by the Gateway API specification.