跳到主要内容

常见问题与解决方案

使用 Ingress Controller 时如果出现问题，通常应先查看网关和控制器日志，因为日志往往可以快速暴露根因。

本文介绍常见问题，并提供实用的排查和解决建议。

GatewayProxy 缺失或配置错误​

当 Gateway 或 IngressClass 引用 GatewayProxy 时，GatewayProxy 定义其使用的提供商连接。如果资源没有同步到网关，常见原因是被引用的 GatewayProxy 缺失或配置错误。

确认 GatewayProxy 资源存在：

kubectl get gatewayproxy --all-namespaces

如果 GatewayProxy 存在，检查其配置：

kubectl describe gatewayproxy <gatewayproxy-name> -n <namespace>

对于 Gateway，被引用的 GatewayProxy 必须位于同一命名空间。IngressClass 可以在 spec.parameters 中指定 GatewayProxy 的命名空间。确认提供商 Service 或端点以及任何被引用的认证 Secret。这些检查不能证明提供商连接正常；如果引用正确，请继续进行配置同步故障排查。

IngressClassName 缺失或未指定​

当以下资源的 ingressClassName 选择了匹配的 IngressClass，或者在省略该字段时存在匹配的默认 IngressClass，Ingress Controller 会处理这些资源：

  • Ingress
  • ApisixRoute
  • ApisixUpstream
  • ApisixTls
  • ApisixPluginConfig
  • ApisixGlobalRule
  • ApisixConsumer

如果显式指定的 ingressClassName 不正确，或者省略该字段且不存在匹配的默认 IngressClass，资源不会同步到网关。

Ingress 注解

对于 Ingress 资源，控制器会先检查 spec.ingressClassName，然后回退到 kubernetes.io/ingress.class 注解。如果两者均未设置，控制器可以使用匹配的默认 IngressClass。

查看当前存在的 IngressClass 资源（集群级资源）：

kubectl get ingressclass

检查 IngressClass 配置，确认它引用了预期的 Ingress Controller：

kubectl describe ingressclass <ingressclass-name>

确认你的资源指定了正确的 ingressClassName，例如：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
spec:
  ingressClassName: apisix
  rules:
  - http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: example-service
            port:
              number: 80

etcd 故障​

本节仅适用于使用 etcd 作为配置后端的 APISIX 部署。如果 etcd Pod 反复重启（CrashLoopBackOff）或持续处于不健康状态，APISIX 配置操作可能失败。

检查 etcd Pod 的状态、事件和日志，然后恢复存储访问和健康的集群成员关系，再继续排查 Ingress Controller。这是 APISIX 网关后端问题，而非 Ingress Controller 故障；APISIX 独立模式不受影响。

跨资源路由优先级​

优先级值越高，路由优先级越高。当同时使用多种资源类型（Ingress、HTTPRoute 和 ApisixRoute）时，路由行为可能受到不同资源优先级分配和评估方式的影响。

各资源类型的优先级处理方式如下：

  • Ingress：原生资源不提供显式路由优先级。只有 HTTPRoutePolicy 提供优先级时，控制器才会设置优先级。
  • HTTPRoute：除非 HTTPRoutePolicy 设置了优先级，否则控制器会根据路由匹配条件计算确定性的优先级。
  • ApisixRoute：允许显式配置路由优先级。

不要依赖固定的 ApisixRoute 值来覆盖所有 HTTPRoute 或 Ingress。请比较通过 HTTPRoutePolicy 设置的所有优先级，并参阅配置路由优先级和匹配条件。

HTTPRoute 过滤器与 PluginConfig​

当 HTTPRoute 过滤器和 PluginConfig CRD 同时应用到同一路由时，可能出现非预期的插件行为。理解二者的交互方式有助于避免配置冲突。

Ingress Controller 会将内置 Gateway API HTTPRoute 过滤器映射到特定插件：

不要在同一条规则中通过标准过滤器和 PluginConfig 配置同一个底层插件。重叠的条目无法可靠合并，并可能导致路由无法转换。有关支持的映射，请参阅 HTTP 路由过滤器。

启用监听器端口匹配时 Gateway API 路由返回 404​

启用监听器端口匹配时，Gateway API HTTPRoute 或 GRPCRoute 可能返回 404；TCPRoute 与 UDPRoute 连接也可能无法匹配 stream route。这些问题源于 Gateway 监听器端口与网关实际监听端口不一致。

按照查看渲染后的控制器配置检查 config.yaml 中实际生效的 listener_port_match_mode。Helm Chart 会显式渲染该字段，因此安装值可能与控制器省略字段时的默认值不同。

当监听器端口匹配注入 server_port 路由变量时，数据面会用实际监听端口（例如 9080、9443 或配置的 stream 端口）评估该值。若 Gateway 监听器使用不同的 Service 对外端口，路由将无法按预期匹配。有关模式触发条件和产品差异，请参阅配置参考。

可使用以下任一方式解决：

  • 将 listener_port_match_mode 设置为 "off"，禁用 server_port 路由变量注入。
  • 将网关配置为监听 Gateway 监听器中声明的相同端口。对于 TCPRoute 与 UDPRoute，监听器端口必须等于对应的 stream_proxy 端口。