跳到主要内容

了解 Admission Webhook

当你应用由 Ingress Controller 管理的资源时，admission webhook 会在 Kubernetes 接受请求之前验证配置。这有助于及早发现配置错误，避免其在运行时导致问题或服务中断。

使用 Helm 安装 APISIX 或 API7 Ingress Controller 时，admission webhook 默认启用，即 webhook.enabled=true。它会在 Kubernetes 接受资源创建和更新请求之前拦截这些请求，根据规则进行校验，并批准请求或返回详细错误信息。这可以确保：

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

在常规操作中，webhook 会在后台静默运行。只有当存在需要关注的潜在配置问题时，你才会看到 webhook 消息。

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

SSL 证书冲突​

当看到证书冲突错误时，表示你正在同一个 GatewayProxy 范围内的多个资源中，为同一主机名使用不同 TLS 证书。Admission 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 资源时，admission 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 引用缺失​

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

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

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

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

Secret 引用缺失​

创建或更新引用 Kubernetes Secret 的资源时，admission 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 名称和命名空间。

Gateway 引用缺失​

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

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

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

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