了解准入 Webhook

准入 Webhook 会在 Kubernetes 接受创建或更新请求前校验 Ingress Controller 资源，从而在配置错误造成运行时故障或服务中断之前将其发现。

独立的 APISIX 与 API7 Ingress Controller Chart 默认通过 webhook.enabled=true 启用 webhook。APISIX umbrella Chart 默认不启用；需设置 ingress-controller.webhook.enabled=true，设置教程已显式启用该值。

启用后，webhook 会校验：

• Schema 校验：资源规格符合要求。
• 配置安全性：立即发现不存在的 Secret 或 Service 等无效资源引用。
• 冲突预防：在部署前识别重复或冲突配置。
• TLS/SSL 验证：校验证书配置的正确性。

只有请求中存在潜在配置问题时，webhook 才会返回消息。

如果由 Argo CD 渲染 Controller Chart，请参阅使用 Argo CD 管理，了解当前 Webhook 证书限制和内容确定的配置方式。

本文介绍常见 webhook 消息，并帮助你理解如何解决这些问题。

SSL 证书冲突

当看到证书冲突错误时，表示你正在同一个 GatewayProxy 范围内的多个资源中，为同一主机名使用不同 TLS 证书。准入 Webhook 会阻止这种情况，以避免路由歧义和安全问题。

SSL configuration conflicts detected:
- Host '<hostname>' is already configured with a different certificate in <resource-type>/<namespace>/<resource-name>

SSL 证书冲突通常发生在为同一主机名创建重复 TLS 资源时，或证书轮换操作失误导致创建了新的 TLS 资源而不是更新现有资源时。无论哪种情况，webhook 都会拒绝新资源来阻止冲突，并指出已有哪个资源正在为该主机名使用不同证书。

GatewayProxy 冲突

创建或更新 GatewayProxy 资源时，准入 Webhook 会验证它是否与现有 GatewayProxy 资源冲突。这些错误会阻止资源创建，避免多个控制器干扰同一个控制面实例。

gateway proxy configuration conflict: GatewayProxy <namespace>/<new-gatewayproxy-name> and <namespace>/<existing-gatewayproxy-name> both target Service <namespace>/<service-name> port <port> while sharing <admin-key>

gateway proxy configuration conflict: GatewayProxy <namespace>/<new-gatewayproxy-name> and <namespace>/<existing-gatewayproxy-name> both target control plane endpoints [<endpoint-url>] while sharing <admin-key>

GatewayProxy 冲突通常发生在两个 GatewayProxy 资源使用相同 admin key（相同内联值或相同 Secret 引用）管理同一个控制面实例时。

如需解决冲突，请找出所有 GatewayProxy 资源，并确定应保留哪一个。如果确实需要多个 GatewayProxy 资源，请确保它们指向不同的控制面实例。

Service 引用缺失

创建或更新将流量路由到后端服务的资源时，准入 Webhook 会验证被引用的 Kubernetes Service 是否存在。如果资源引用的 Service 不存在，你会看到类似如下警告：

Warning: Referenced Service '<namespace>/<service-name>' not found

与错误不同，警告会允许资源创建，但在后端 Service 存在之前，流量路由会失败。

Service 引用缺失通常由 Service 名称或命名空间拼写错误，或被引用 Service 尚未创建导致。如需解决该问题，请确认 Service 存在于正确命名空间，检查 Service 引用是否有拼写错误，并在应用依赖它的资源之前先创建该 Service。

Secret 引用缺失

创建或更新引用 Kubernetes Secret 的资源时，准入 Webhook 会验证这些 Secret 是否存在，以及是否包含所需 key。Secret 可能用于 TLS 证书、认证凭证或插件配置。

如果资源引用的 Secret 不存在，你会看到类似如下警告：

Warning: Referenced Secret '<namespace>/<secret-name>' not found

如果资源引用的 Secret 不包含所需 key（例如 basic authentication 缺少 password key），你会看到类似如下警告：

Warning: Secret key '<key-name>' not found in Secret '<namespace>/<secret-name>'

与错误不同，警告会允许资源创建，但在被引用 Secret 正确配置前，受影响功能无法正常工作。

如需解决该问题，请确保在应用引用 Secret 的资源之前先创建所需 Secret，确认 Secret 包含所有必要 key，并再次检查 Secret 名称和命名空间。

跨命名空间 Consumer Secret

Consumer 引用另一命名空间中的凭证 Secret 时，Secret 命名空间中必须有允许该引用的 ReferenceGrant，否则请求会被拒绝，错误中包含：

not permitted by any ReferenceGrant

响应不会泄露 Secret 是否存在。请先创建授权再应用 Consumer。参阅配置跨命名空间引用。

无效 CSRF 注解

当 k8s.apisix.apache.org/enable-csrf 为 true 时，Ingress 还必须设置非空的 k8s.apisix.apache.org/csrf-key，否则 webhook 会拒绝创建与更新请求：

annotation "k8s.apisix.apache.org/enable-csrf" is enabled but "k8s.apisix.apache.org/csrf-key" is missing or empty

为 Ingress 注解添加强 key 后重新应用资源。参阅 CSRF 注解参考。

Gateway 引用缺失

创建或更新引用 GatewayProxy 的 Gateway 或 IngressClass 时，准入 Webhook 会验证 GatewayProxy 是否存在。如果资源引用的 GatewayProxy 不存在，你会看到类似如下警告：

Warning: Referenced GatewayProxy '<namespace>/<gatewayproxy-name>' not found

与错误不同，警告会允许资源创建，但在被引用 GatewayProxy 正确配置之前，受影响功能无法正常工作。

如需解决该问题，请确保 GatewayProxy 存在于正确命名空间，并检查 GatewayProxy 引用是否存在拼写错误。

Webhook 连接

Webhook Service 监听端口 443，并将请求转发到容器端口 9443。若有 NetworkPolicy 选择了 Controller Pod，它必须允许访问 Pod 的 TCP 9443，而不只是 Service 端口 443。

升级后校验 TCPRoute 或 UDPRoute 返回 404 时，请检查手工维护的 ValidatingWebhookConfiguration。当前 API 版本与路径如下：

资源	rules[].apiVersions	clientConfig.service.path
TCPRoute	v1	/validate-gateway-networking-k8s-io-v1-tcproute
UDPRoute	v1	/validate-gateway-networking-k8s-io-v1-udproute

Chart 管理的 webhook 资源会随 Chart 更新；自定义资源需手工更新。可用以下命令检查 endpoint：

kubectl get validatingwebhookconfiguration \
  -o jsonpath='{range .items[*].webhooks[*]}{.clientConfig.service.path}{"\t"}{range .rules[*].apiVersions[*]}{.}{" "}{end}{"\n"}{end}' \
  | grep -E 'v1-(tcp|udp)route'

每个 TCPRoute 与 UDPRoute 行都应显示其 v1 webhook 路径和 v1 API 版本。若版本仍为 v1alpha2，请同时更新规则与路径。