Ingress 和 Gateway API 支持
Ingress Controller 会协调 Kubernetes Gateway API 和 Ingress 资源。下表列出生产清单中可用的 API 和字段。
请参阅配置示例，了解何时以及如何使用各类资源。
Gateway API
Gateway API 将基础设施、Gateway 和 Route 配置分离，使其可以分别由不同团队管理。请参阅使用 Kubernetes RBAC 委派 Gateway API 访问权限配置用户权限，并参阅配置跨命名空间引用授权 Route 挂载和跨命名空间资源引用。
Gateway API 版本
- Gateway API 1.6.0 release
- Gateway API 1.6.0 API definitions
gateway.networking.k8s.io/v1
Helm Chart 参考中列出的兼容 Controller Chart 提供 Gateway API 1.6.0 standard bundle。其中的 CRD 包含支持矩阵使用的 v1 L4 Route API。由 Chart 管理的安装无需单独执行 CRD 安装命令。
独立的 APISIX Ingress Controller Chart 1.4.0 默认将 Gateway API bundle 渲染为 Helm 模板。对象不存在或已由同一个 release 拥有时，该 Chart 会渲染它。如果集群平台拥有 Gateway API，请设置 crds.gatewayAPI.enabled=false；仅使用 --skip-crds 不会禁用这些模板。
API7 Ingress Controller Chart 0.1.28 与 APISIX umbrella Chart 的 Controller 1.3.0 依赖项都通过静态 CRD 生命周期打包 Gateway API。当集群平台拥有 Gateway API 时，请配置这些 release 跳过捆绑的静态 CRD。
手动管理 bundle 时，请使用服务端 apply，因为这些 CRD 会超过客户端注解大小限制：
kubectl apply --server-side --force-conflicts \
-f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.6.0/standard-install.yaml
如果 CRD 已由 Chart、GitOps release 或其他平台组件管理，请勿运行此手动命令。
资源支持级别
下表概述当前实现对 Gateway API 资源的支持级别。它描述已实现的行为，并非上游一致性声明。
| 资源 | 核心 | 扩展 | 特定实现 | API 版本 |
|---|---|---|---|---|
| GatewayClass | 支持 | 不适用 | 不支持 | v1 |
| Gateway | 部分支持 | 部分支持 | 部分支持 | v1 |
| HTTPRoute | 支持 | 部分支持 | 部分支持 | v1 |
| GRPCRoute | 支持 | 部分支持 | 部分支持 | v1 |
| ReferenceGrant | 支持 | 不支持 | 不支持 | v1 |
| TLSRoute | 支持 | 支持 | 不支持 | v1 |
| TCPRoute | 支持 | 支持 | 不支持 | v1 |
| UDPRoute | 支持 | 支持 | 不支持 | v1 |
| BackendTLSPolicy | 不支持 | 不支持 | 不支持 | v1 |
有关完整配置选项，请参阅 Gateway API 1.6.0 API definitions。部分字段不受支持或仅部分支持，具体如下。
不支持/部分支持的字段
以下字段在 Gateway API 规范中有定义，但在 Ingress Controller 中要么部分实现，要么尚未支持。
HTTPRoute
| 字段 | 状态 | 说明 |
|---|---|---|
spec.timeouts | 不支持 | 此字段不受支持，因为 ADC 提供了更精细的超时配置（连接、读取、写入），而 spec.timeouts 只允许设置通用的总超时和上游超时，因此无法直接映射。要配置路由超时，可以使用 BackendTrafficPolicy。 |
spec.retries | 不支持 | 此字段不受支持，因为 APISIX 不支持 retries 中的功能。要配置路由重试，可以使用 BackendTrafficPolicy。 |
spec.sessionPersistence | 不支持 | APISIX 不支持 Cookie 生命周期的配置。作为替代，你可以使用 chash 负载均衡器。 |
spec.rules[].backendRefs[].filters[] | 不支持 | 后端引用级别的过滤器未实现，因为数据平面不支持此级别的过滤；仅支持规则级别的过滤器（spec.rules[].filters[]）。 |
GRPCRoute
| 字段 | 状态 | 说明 |
|---|---|---|
spec.rules[].sessionPersistence | 不支持 | 控制器不会将此字段转换为网关配置。 |
Gateway
| 字段 | 状态 | 说明 |
|---|---|---|
spec.listeners[].port | 部分支持 | 两个控制器都会在路由通过端口指向监听器时，将此字段与路由的 parentRefs[].port 比较。当 listener_port_match_mode 注入 server_port 条件时，该条件必须等于网关实际的监听端口。控制器不会打开数据面端口。 |
spec.listeners[].tls.certificateRefs[].group | 部分支持 | 仅支持 ""；其他 group 值会导致验证失败。 |
spec.listeners[].tls.certificateRefs[].kind | 部分支持 | 仅支持 Secret。 |
spec.listeners[].tls.mode | 部分支持 | 实现了 Terminate；Passthrough 对于 Gateway 监听器实际上不受支持。 |
spec.tls.frontend.default.validation.caCertificateRefs | 部分支持 | 核心行为支持 ConfigMap，实现特定扩展还支持 Secret。CA 引用使用 ca.crt 键。不支持 AllowInsecureFallback。 |
spec.tls.frontend.perPort | 支持 | 每端口配置会覆盖该端口监听器的默认客户端证书校验。 |
spec.addresses | 不支持 | 控制器不读取或作用于 spec.addresses。 |
当所有匹配的监听器都定义了 spec.listeners[].hostname 时，APISIX Ingress Controller 不会添加 server_port 条件。因此，将路由关联到此类监听器不会把生成的路由限制到该监听器端口。API7 Ingress Controller 可以在端口匹配中包含配置了主机名的监听器。如需 APISIX 执行端口匹配，请省略监听器主机名，并改为在 HTTPRoute 或 GRPCRoute 上配置主机名。模式触发条件请参阅配置参考，实际端口不匹配的恢复方法请参阅常见问题。
有关可运行的客户端证书校验示例，请参阅配置客户端与网关之间的 mTLS。
HTTP 路由过滤器
Ingress Controller 将 HTTPRoute 资源中的标准 Gateway API 过滤器映射到相应的插件：
| Gateway API 过滤器 | APISIX 插件 |
|---|---|
RequestHeaderModifier | proxy-rewrite |
RequestRedirect | redirect |
RequestMirror | proxy-mirror |
URLRewrite | proxy-rewrite |
ResponseHeaderModifier | response-rewrite |
CORS | cors |
ExtensionRef | 同一命名空间中 PluginConfig 的插件 |
当 HTTPRoute 规则使用标准过滤器和 ExtensionRef 时，两者应配置不同的插件。不要在同一条规则中通过两种机制配置同一个底层插件；重叠的条目无法可靠合并，并可能导致路由无法转换。
Ingress
包
- networking.k8s.io/v1
支持的资源
控制器支持标准的 Kubernetes Ingress API，包括：
支持基本的基于主机和路径的路由。有关支持的 Ingress 注解和使用示例，请参阅注解参考。
使用 APISIX 或 API7 网关时，*.example.com 这样的 Ingress 规则主机名按后缀匹配。它既匹配 foo.example.com，也匹配 bar.foo.example.com，但不匹配裸域名 example.com。这比 Kubernetes Ingress 文档所述的单标签通配符行为更宽泛。
如果路由只能接受特定子域名，请显式列出每个主机名。如 Gateway API 主机名文档所述，HTTPRoute 通配符同样可以匹配多个前导标签。