跳到主要内容

常见问题与解决方案

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

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

GatewayProxy 缺失或配置错误​

GatewayProxy 定义 Ingress Controller 与控制面通信时使用的控制面端点和 Admin API key。如果资源没有同步到网关，常见原因是 GatewayProxy 资源缺失或配置错误。

确认 GatewayProxy 资源存在，并创建在正确的命名空间中：

kubectl get gatewayproxy --all-namespaces

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

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

IngressClassName 缺失或未指定​

对于以下资源，只有当 ingressClassName 与控制器配置的 IngressClass 匹配时，Ingress Controller 才会处理：

  • Ingress
  • ApisixRoute
  • ApisixUpstream
  • ApisixTLS
  • ApisixPluginConfig
  • ApisixGlobalRule
  • ApisixConsumer

如果 ingressClassName 缺失或指定错误，资源不会同步到网关。

Ingress 注解

对于 Ingress 资源，控制器会先检查 spec.ingressClassName。如果未设置，则回退到 kubernetes.io/ingress.class 注解；该注解用于向后兼容。

查看当前存在的 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 故障​

如果在 Kubernetes 上以使用 etcd 作为配置后端的部署模式运行 APISIX，可能会遇到 etcd Pod 反复重启（CrashLoopBackOff）或无法进入健康状态的问题。将 etcd 作为 Kubernetes StatefulSet 托管会带来运维挑战：Pod 在重启、扩缩容或失去持久化存储访问时可能崩溃，集群成员关系也可能变得不稳定。

因此，通常建议以 独立模式运行 APISIX，该模式不需要 etcd。它可以简化部署，并避免在 Kubernetes 内管理 etcd 集群的复杂性。

如果部署确实需要 etcd，通常更可靠的做法是在 Kubernetes 外的独立虚拟机或专用基础设施上托管 etcd 集群。

跨资源路由优先级​

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

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

  • Ingress：不支持显式路由优先级。由 Ingress 资源生成的路由会被分配默认优先级 0，通常最低。
  • HTTPRoute：使用动态计算的 38-bit priority。由于该值由多个属性推导而来，最终优先级不是固定值，也无法可靠预测。
  • APISIXRoute：允许显式配置路由优先级。若要保证 APISIXRoute 先于 HTTPRoute 匹配，其优先级必须高于 274,877,906,943（2^38 - 1）。

HTTPRoute Filter 与 PluginConfig​

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

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

当 filter 和 PluginConfig CRD 同时应用时：

  • 如果先应用 filter，PluginConfig 会覆盖重叠的插件设置。
  • 如果先应用 PluginConfig，filter 会与 PluginConfig 设置合并，并且 filter 中的重叠字段优先级更高。

升级后 Gateway API 路由返回 404​

升级到 APISIX Ingress Controller 2.1.0 后，Gateway API HTTPRoute 或 GRPCRoute 资源可能返回 404。当 Gateway 监听器端口与 APISIX 或 API7 网关实际监听端口不匹配时，可能出现该问题。

在默认的 listener_port_match_mode: auto 模式下，Ingress Controller 可能会根据匹配的 Gateway 监听器端口注入 server_port 路由变量。数据面会用自身实际监听端口（例如 9080 或 9443）评估 server_port 变量。如果 Gateway 监听器使用 80 或 443，但网关 Service 将这些端口映射到 9080 或 9443，路由可能无法匹配。

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

  • 在控制器配置中将 listener_port_match_mode 设置为 "off"，禁用 server_port route-var 注入。
  • 将 APISIX 或 API7 网关配置为监听 Gateway 监听器中声明的相同端口。