4. 安装与部署：使用 Helm 安装 Gatekeeper、配置参数、验证部署状态
本章聚焦于在生产级 Kubernetes 集群中快速、可复用地部署 OPA Gatekeeper。Helm 是官方推荐的安装方式，能够通过 values 文件灵活控制组件参数、资源限制与 Webhook 行为。以下内容涵盖 Helm Chart 安装、关键配置项解析、自定义资源定义（CRD）管理以及部署状态验证。
4.1 前置条件与 Helm 仓库配置
在安装前，请确保集群满足以下要求：
- Kubernetes 版本：v1.20 及以上（推荐 v1.24+）
- Helm 版本：v3.8+
- 集群管理员权限：Gatekeeper 需要创建集群级别的 Webhook 与 CRD
- 网络策略：允许 kube-apiserver 访问 Gatekeeper 的 webhook 服务（默认端口 443）
添加官方 Helm 仓库并更新索引：
helm repo add gatekeeper https://open-policy-agent.github.io/gatekeeper/charts
helm repo update4.2 使用 Helm 安装 Gatekeeper
执行以下命令安装最新稳定版 Gatekeeper：
helm install gatekeeper/gatekeeper \
--name-template gatekeeper \
--namespace gatekeeper-system \
--create-namespace \
--values values.yaml若需要指定版本，使用 --version 参数：
helm install gatekeeper/gatekeeper \
--name-template gatekeeper \
--namespace gatekeeper-system \
--create-namespace \
--version 3.16.0 \
--values values.yaml
生产建议：始终将 values.yaml 文件纳入版本控制（GitOps），避免直接使用
--set 传递大量参数导致配置漂移。
4.3 核心配置参数详解
以下表格列出了生产部署中最关键的 values 参数及其推荐值：
| 参数路径 | 默认值 | 生产推荐值 | 说明 |
|---|---|---|---|
replicas |
1 | 2-3 | 控制器副本数，保障高可用 |
auditInterval |
60 | 60-300 | 审计扫描间隔（秒），频繁扫描增加 etcd 压力 |
constraintViolationsLimit |
20 | 100 | 单个约束对象最多记录的违规数 |
auditFromCache |
false | true | 审计时优先使用缓存，减少 API Server 请求 |
enableExternalData |
false | false | 启用外部数据源支持（需额外配置 Provider） |
webhook.enabled |
true | true | 启用准入 Webhook，拦截不合规资源 |
webhook.failurePolicy |
Ignore | Fail | Webhook 不可用时是否拒绝请求（生产建议 Fail） |
resources.limits.memory |
512Mi | 1Gi-2Gi | 根据集群规模调整内存限制 |
resources.limits.cpu |
1000m | 1000m-2000m | CPU 上限，避免突发流量导致 OOM |
4.4 CRD 管理策略
Gatekeeper 使用 CRD 定义约束模板（ConstraintTemplate）和约束（Constraint）。Helm Chart 默认自动安装 CRD，但在升级时需注意：
- 自动 CRD 管理：Chart 中的
crd.install参数默认为true，Helm 会在安装/升级时自动应用 CRD。 - 手动 CRD 管理：若需精细控制 CRD 版本，设置
crd.install=false，然后使用kubectl apply单独管理 CRD 文件。 - CRD 升级风险：Gatekeeper 3.x 到 4.x 的 CRD 变更可能不兼容，建议在测试环境先行验证。
注意：Helm 不会自动删除 CRD。若卸载 Gatekeeper，需手动清理 CRD 及对应的约束实例，否则残留的 CRD 可能导致集群 API 异常。
4.5 验证部署状态
安装完成后，执行以下步骤确认组件正常运行：
- 检查 Pod 状态：
kubectl get pods -n gatekeeper-system
# 预期输出：gatekeeper-controller-manager-xxx Running
# gatekeeper-audit-xxx Running- 验证 Webhook 注册：
kubectl get validatingwebhookconfigurations -l gatekeeper.sh/system=yes
# 预期输出：gatekeeper-validating-webhook-configuration- 检查 CRD 是否就绪：
kubectl get crd | grep gatekeeper
# 预期输出：assign.mutations.gatekeeper.sh
# assignmetadata.mutations.gatekeeper.sh
# constrainttemplates.templates.gatekeeper.sh
# ...- 查看审计日志（确认审计循环正常）：
kubectl logs -n gatekeeper-system -l gatekeeper.sh/operation=audit --tail=20- 测试准入拦截（可选）：
# 创建一个违反基线约束的 Pod（需先部署约束）
kubectl run nginx-privileged --image=nginx --privileged
# 预期输出：Error from server (Forbidden): ... denied by constraint ...4.6 部署架构示意
下图展示了 Gatekeeper 在集群中的核心组件及其交互关系：
4.7 常见安装问题与排错
| 现象 | 可能原因 | 解决方案 |
|---|---|---|
Pod 一直处于 Pending 状态 |
资源不足或节点污点不匹配 | 检查节点资源，添加 tolerations 或调整 nodeSelector |
| Webhook 注册失败 | 证书问题或网络策略阻止 443 端口 | 检查 cert-manager 或自签名证书；确认集群网络策略 |
| 审计日志无输出 | auditInterval 过大或审计被禁用 |
确认 auditInterval 值；检查 --disable-audit 参数 |
| 约束创建后不生效 | ConstraintTemplate 未就绪或 Rego 语法错误 | 使用 kubectl describe constrainttemplate 查看错误详情 |
最佳实践：在 CI/CD 流水线中集成
helm template 命令，将渲染后的 YAML 与基线约束一起进行静态扫描，提前发现配置错误。