本文档采用自动化机器翻译技术翻译。尽管我们力求提供准确的译文，但不对翻译内容的完整性、准确性或可靠性作出任何保证。若出现任何内容不一致情况，请以原始英文版本为准，且原始英文版本为权威文本。

SUSE Rancher Prime Webhook

Rancher-Webhook 是 Rancher 的一个重要组成部分，它与 Kubernetes 协同工作，以增强安全性并启用 Rancher 管理的集群的关键功能。

它与 Kubernetes 的可扩展准入控制器集成，如 Kubernetes 文档中所述，这使得 Rancher-Webhook 能够检查发送到 Kubernetes API 服务器的特定请求，并为特定于 Rancher 的请求添加自定义验证和变更。Rancher-Webhook 使用 rancher.cattle.io ValidatingWebhookConfiguration 和 rancher.cattle.io MutatingWebhookConfiguration 对象管理要验证的资源，并将覆盖任何手动编辑。

Rancher 将 Rancher-Webhook 部署为本地和下游集群中的单独部署和服务。Rancher 使用 Helm 管理 Rancher-Webhook。需要注意的是，Rancher 可能会覆盖用户对 Helm 发布所做的修改。要安全地修改这些值，请参见自定义 Rancher-Webhook 配置。

每个 Rancher 版本都设计为与单个版本的 webhook 兼容。兼容的版本如下所示，方便查阅。

Rancher 管理 webhook 的部署和升级。在大多数情况下，无需用户干预即可确保 webhook 版本与您正在运行的 Rancher 版本兼容。

Rancher 版本	Webhook 版本	在 Prime 中的可用性	在 Community 中的可用性
v2.14.1	v0.10.4	✓	✓
v2.13.3	v0.9.3	✓	✓
v2.13.2	v0.9.2	✓	✓
v2.13.1	v0.9.1	✓	✓
v2.13.0	v0.9.0	✗	✓

Rancher 版本

Webhook 版本

在 Prime 中的可用性

在 Community 中的可用性

v2.14.1

v0.10.4

✓

v2.13.3

v0.9.3

✓

v2.13.2

v0.9.2

✓

v2.13.1

v0.9.1

✓

v2.13.0

v0.9.0

✗

✓

我们为什么需要它？

Rancher-Webhook 对于 Rancher 保护集群免受恶意攻击和启用各种功能至关重要。 Rancher 依赖 Rancher-Webhook 作为其功能的一个组成部分。没有 webhook，Rancher 将不是一个完整的产品。它为 Rancher 管理的集群提供了基本的保护，防止安全漏洞，并确保集群的一致性和稳定性。

Webhook 验证哪些资源？

您可以在 webhook 的代码库中找到 Webhook 验证的资源的进行中的列表。这些文档按组/版本和资源组织（顶级标题是组/版本，下一层标题是资源）。特定于某个版本的检查可以通过查看与特定标签相关的`docs.md`文件找到（请注意，`v0.3.6`之前的Webhook版本将没有此文件）。

绕过Webhook

有时，您必须绕过Rancher的Webhook验证以执行紧急恢复操作或修复其他关键问题。绕过操作是全面的，这意味着使用它时不适用任何Webhook验证或变更。不可能绕过某些验证或变更而让其他仍然适用 - 它们要么全部被绕过，要么全部处于活动状态。

Rancher的Webhook提供了关键的安全保护。绕过Webhook应仅由管理员在特定情况下进行，且在所有其他选项都已用尽后。此外，绕过Webhook的权限应受到严格控制，绝不应授予非管理员用户。

要绕过Webhook，必须同时模拟`rancher-webhook-sudo`服务账户和`system:masters`组（两者都是必需的）：

kubectl create -f example.yaml --as=system:serviceaccount:cattle-system:rancher-webhook-sudo --as-group=system:masters

自定义Rancher-Webhook配置

通过Helm安装Rancher-Webhook时，您可以添加自定义Helm值。在Rancher-Webhook图表的Helm安装过程中，Rancher会检查自定义Helm值。这些自定义值必须在名为`rancher-config`的ConfigMap中定义，在`cattle-system`命名空间下，数据键为`rancher-webhook`。此键的值必须是有效的YAML。

apiVersion: v1
kind: ConfigMap
metadata:
  name: rancher-config
  namespace: cattle-system
  labels:
    app.kubernetes.io/part-of: "rancher"
data:
  rancher-webhook: '{"port": 9553, "priorityClassName": "system-node-critical"}'

当检测到ConfigMap值的更改时，Rancher会重新部署Rancher-Webhook图表。

在Rancher安装期间自定义Rancher-Webhook

当您使用 Helm 安装 Rancher chart 时，可以向本地群集的 Rancher-Webhook 添加自定义 Helm 值。Rancher-Webhook chart 中的所有值都可以作为嵌套变量在 webhook 名称下访问。

这些值在安装期间会同步到 rancher-config ConfigMap。

helm install rancher rancher-prime/rancher \
  --namespace cattle-system \
  ...
  --set webhook.port=9553 \
  --set webhook.priorityClassName="system-node-critical"

常见问题

带有 Calico CNI 的 EKS 集群

运行带有 Calico CNI 的 EKS 集群的用户可能会遇到错误，当 Kubernetes API 服务器尝试联系 Rancher-Webhook 时。解决此问题的一种变通方法，如 Calico 文档中所述，涉及为 webhook 部署设置 hostNetwork=true。您可以通过将 Helm 值 global.hostNetwork=true 添加到 rancher-config ConfigMap 来更改此值。有关更多信息，请参见自定义 Rancher-Webhook 配置。

apiVersion: v1
kind: ConfigMap
metadata:
  name: rancher-config
  namespace: cattle-system
  labels:
    app.kubernetes.io/part-of: "rancher"
data:
  rancher-webhook: '{"global": {"hostNetwork": true}}'

此临时变通方法可能违反环境的安全策略。此变通方法还要求主机网络上未使用 9443 端口。

默认情况下，Helm 将信息存储为机密。机密是某些 webhook 版本验证的资源。在这些情况下，使用 kubectl 直接更新部署，使用 hostNetwork=true 值，然后按照上述说明更新 webhook 配置。

私有 GKE 集群

使用私有 GKE 集群时，可能会发生错误，阻止 Kubernetes API 服务器与 webhook 通信。可能会出现以下错误消息：

Internal error occurred: failed calling webhook "rancher.cattle.io.namespaces.create-non-kubesystem": failed to call webhook: Post "https://rancher-webhook.cattle-system.svc:443/v1/webhook/validation/namespaces?timeout=10s": context deadline exceeded

此问题发生是因为防火墙规则限制了 API 服务器与私有集群之间的通信。要解决此通信问题，用户必须添加防火墙规则，以允许 GKE 控制平面通过 9443 端口与 Rancher-Webhook 通信。有关更新防火墙规则的详细信息和步骤，请参阅 GKE 文档。

由于 Rancher-Webhook 阻止访问，应用程序无法部署。

Webhook 提供了对 namespaces 的额外验证。这些验证之一确保用户只有在拥有适当权限的情况下才能更新与 PSA 相关的标签（updatepsa 对 projects 在 management.cattle.io 中）。这可能导致特定的操作员，例如 Tigera 或 Trident，在尝试部署带有 PSA 标签的命名空间时失败。有多种方法可以解决此问题：

配置应用程序以创建没有 PSA 标签的命名空间。如果用户希望将 PSA 应用到这些命名空间，他们可以在配置后将其添加到具有所需 PSA 的项目中。请参阅关于 PSS 和 PSA 资源的文档，以获取如何操作的说明。
- 这是首选选项，尽管并非所有应用程序都可以以这种方式进行配置。
手动授予操作员管理命名空间的 PSA 权限。
- 此选项将引入安全风险，因为操作员现在将能够为其访问的命名空间设置 PSA。这可能允许操作员部署特权 Pod，或通过其他方式影响集群接管。
具有适当权限的用户帐户可以预先创建具有适当配置的命名空间。
- 此选项取决于应用程序处理现有资源的能力。

这些验证之一确保用户具有更新命名空间上 field.cattle.io/projectId 注释的适当权限。这是 manage-namespaces 在 projects 中的 management.cattle.io 权限。

特定版本的问题

以下是不完整的、影响特定 Rancher-Webhook 版本的高严重性问题列表。在大多数情况下，这些问题可以通过升级到更新的 Rancher 版本来解决。

回滚时不兼容的 Webhook 版本

这影响回滚到 Rancher v2.7.5 或更早版本。

如果您回滚到 Rancher v2.7.5 或更早版本，您可能会看到与运行 pre-v2.7.5 版本 Rancher 的下游集群不兼容的 webhook 版本。这可能会导致各种不兼容问题。例如，项目成员可能无法创建命名空间。此外，当您回滚到下游集群中安装 webhook 之前的版本时，webhook 可能仍然安装，这可能导致类似的不兼容问题。

为了解决这些问题，您可以在回滚后运行 adjust-downstream-webhook shell 脚本。该脚本选择并安装适合相应 Rancher 版本的正确 webhook 版本（或完全去除 webhook）。