2. Gatekeeper 安装与部署：使用 Helm 安装 Gatekeeper、配置 Webhook、验证部署状态与日志查看

本章聚焦于在生产环境中快速、可复现地部署 OPA Gatekeeper。我们将使用 Helm 作为包管理工具，完成从仓库添加、参数配置到 Webhook 注册的全流程，并掌握部署验证与日志排查的核心方法。

2.1 环境准备与 Helm 仓库配置

在安装之前，请确保你的 Kubernetes 集群版本 ≥ 1.19，并且已安装 Helm 3.x 客户端。以下步骤将配置官方 Helm 仓库并更新索引：

# 添加 Gatekeeper 官方 Helm 仓库
helm repo add gatekeeper https://open-policy-agent.github.io/gatekeeper/charts

# 更新本地仓库索引
helm repo update

2.2 使用 Helm 安装 Gatekeeper

执行以下命令完成基础安装。默认情况下，Gatekeeper 会创建 gatekeeper-system 命名空间，并部署三个核心组件：Controller Manager、Audit Controller 和 Webhook Server。

# 基础安装（使用默认配置）
helm install gatekeeper/gatekeeper \
  --name-template=gatekeeper \
  --namespace=gatekeeper-system \
  --create-namespace

对于生产环境，建议通过自定义 values 文件覆盖关键参数。下表列出了最常用的配置项：

使用自定义 values 文件安装示例：

# 创建 values-prod.yaml
cat <<EOF > values-prod.yaml
replicas: 2
auditInterval: 120
logLevel: INFO
webhook:
  failurePolicy: Fail
  timeoutSeconds: 5
resources:
  limits:
    memory: 1Gi
  requests:
    cpu: 500m
    memory: 512Mi
EOF

# 使用自定义配置安装
helm install gatekeeper gatekeeper/gatekeeper \
  --namespace=gatekeeper-system \
  --create-namespace \
  --values values-prod.yaml

2.3 Webhook 配置与工作原理

Gatekeeper 通过 ValidatingWebhookConfiguration 和 MutatingWebhookConfiguration 两种资源拦截 API 请求。默认安装会自动创建以下 Webhook：

• validation.gatekeeper.sh：验证准入 Webhook，拦截资源创建/更新请求，根据 Constraint 策略进行校验。
• mutating.gatekeeper.sh：变更准入 Webhook，用于自动注入标签或修改资源字段（默认启用，可关闭）。

下图展示了 Gatekeeper 在 Kubernetes 准入控制链中的位置与请求处理流程：

2.4 验证部署状态

安装完成后，通过以下命令验证各组件是否正常运行：

# 检查 Pod 状态
kubectl get pods -n gatekeeper-system

# 预期输出示例：
# NAME                                             READY   STATUS    RESTARTS   AGE
# gatekeeper-controller-manager-7d8c9f5b6c-abc12   1/1     Running   0          2m
# gatekeeper-controller-manager-7d8c9f5b6c-xyz34   1/1     Running   0          2m
# gatekeeper-audit-5f6d7e8f9g-hij56                1/1     Running   0          2m

# 检查 Service 和 Webhook 配置
kubectl get svc -n gatekeeper-system
kubectl get validatingwebhookconfiguration
kubectl get mutatingwebhookconfiguration

验证 Webhook 是否正常注册：

# 查看 ValidatingWebhookConfiguration 详情
kubectl describe validatingwebhookconfiguration gatekeeper-validating-webhook-configuration

关键检查项包括：

• service 引用：指向 gatekeeper-webhook-service 的 443 端口
• caBundle：应包含有效的 Base64 编码 CA 证书
• rules：定义了哪些资源操作（CREATE/UPDATE）会被拦截
• failurePolicy：与配置一致

2.5 日志查看与常见问题排查

Gatekeeper 的日志是排查策略问题和 Webhook 故障的首要手段。以下为不同场景的日志查看方法：

常见问题与解决措施：

2.6 部署架构总览

以下 SVG 展示了 Gatekeeper 部署后的完整组件架构与数据流关系：

2.7 卸载 Gatekeeper

如需完全移除 Gatekeeper，请按以下顺序操作，确保清理所有资源：

# 1. 删除所有 Constraint 和 ConstraintTemplate（避免残留策略）
kubectl delete constraint --all
kubectl delete constrainttemplate --all

# 2. 卸载 Helm Release
helm uninstall gatekeeper -n gatekeeper-system

# 3. 删除命名空间（可选，会清理所有关联资源）
kubectl delete namespace gatekeeper-system