4. 安装与部署 Kyverno：使用 Helm 安装、使用 YAML 安装、验证安装状态、常见安装问题排查

Kyverno 作为 Kubernetes 原生的策略引擎，其部署方式与集群环境紧密相关。本章将系统讲解两种主流安装方式——Helm Chart 与 原始 YAML 清单，并提供安装后的状态验证方法及高频问题排查指南。无论你处于测试环境还是生产集群，均可按本节步骤完成部署。

4.1 安装方式对比

在开始安装前，理解两种方式的适用场景有助于快速决策。下表从运维复杂度、可定制性、升级便利性三个维度进行对比：

对比维度	Helm Chart 安装	YAML 清单安装
运维复杂度	低，一条命令完成部署与配置	中，需手动管理多个 YAML 文件
可定制性	高，通过 values.yaml 灵活调整	中，需直接编辑原始清单
升级便利性	高，支持 helm upgrade 回滚	低，需手动 diff 并 apply
推荐场景	生产环境、需要频繁调整配置	CI/CD 流水线、离线环境

4.2 使用 Helm 安装 Kyverno

Helm 是 Kubernetes 生态中最常用的包管理工具。Kyverno 官方维护的 Helm Chart 仓库提供了完整的部署参数。

4.2.1 添加 Helm 仓库

helm repo add kyverno https://kyverno.github.io/kyverno/
helm repo update

4.2.2 安装 Kyverno（基础版）

kubectl create namespace kyverno
helm install kyverno kyverno/kyverno -n kyverno

4.2.3 安装 Kyverno（生产推荐配置）

生产环境建议开启高可用副本与资源限制，通过自定义 values 文件实现：

cat <<EOF > kyverno-values.yaml
replicaCount: 3
resources:
  limits:
    memory: 512Mi
    cpu: 500m
  requests:
    memory: 256Mi
    cpu: 250m
webhooks:
  failurePolicy: Fail
EOF

helm install kyverno kyverno/kyverno -n kyverno -f kyverno-values.yaml

4.3 使用 YAML 清单安装 Kyverno

对于无法访问 Helm 仓库或需要严格审计清单内容的场景，可直接使用官方发布的 YAML 文件。

4.3.1 下载并应用最新稳定版

kubectl create namespace kyverno
kubectl apply -f https://raw.githubusercontent.com/kyverno/kyverno/main/config/release/install.yaml

4.3.2 离线安装步骤

1. 在可联网机器上下载 install.yaml 文件。
2. 将文件传输至离线集群的控制节点或可通过 kubectl 访问的机器。
3. 执行 kubectl apply -f install.yaml。

4.4 验证安装状态

安装完成后，需从 Pod 状态、Webhook 注册、API 资源三个层面确认 Kyverno 正常运行。

4.4.1 检查 Pod 运行状态

kubectl get pods -n kyverno -o wide

预期输出应显示 kyverno-xxx Pod 处于 Running 状态，且 READY 列为 1/1。

4.4.2 验证 Webhook 配置

kubectl get validatingwebhookconfigurations -l webhook.kyverno.io/managed-by=kyverno
kubectl get mutatingwebhookconfigurations -l webhook.kyverno.io/managed-by=kyverno

应至少返回一条 ValidatingWebhookConfiguration 和一条 MutatingWebhookConfiguration。

4.4.3 检查 CRD 资源

kubectl get crd | grep kyverno

常见的 CRD 包括 clusterpolicies.kyverno.io、policies.kyverno.io、policyreports.wgpolicyk8s.io 等。

4.5 安装架构与组件关系

下图展示了 Kyverno 安装后的核心组件及其在 Kubernetes 集群中的交互关系：

4.6 常见安装问题排查

即使按照标准步骤操作，仍可能遇到环境差异导致的问题。以下整理了三个高频故障场景及解决方案。

4.6.1 Pod 启动失败：CrashLoopBackOff

可能原因	排查命令	解决方案
镜像拉取失败	kubectl describe pod <pod-name> -n kyverno	检查镜像仓库地址，确保私有仓库认证配置正确
资源不足	kubectl top nodes	调整 resources.requests 或增加节点资源
Webhook 端口冲突	kubectl logs <pod-name> -n kyverno	修改 values.yaml 中的 service.port 或 webhook.port

4.6.2 Webhook 未注册

若 kubectl get validatingwebhookconfigurations 返回空，通常是因为 Kyverno 启动时无法连接 API Server。执行以下命令查看日志：

kubectl logs -n kyverno -l app.kubernetes.io/name=kyverno --tail=50 | grep -i "webhook"

常见错误信息为 failed to register webhook: timeout。解决方案：检查集群 DNS 是否正常，确保 kyverno-svc 的 ClusterIP 可达。

4.6.3 策略无法生效

安装成功后创建策略但未生效，可能原因如下：

• Webhook 未触发： 检查策略是否匹配目标资源标签。
• 策略语法错误： 使用 kubectl describe clusterpolicy <policy-name> 查看状态字段。
• RBAC 权限不足： Kyverno 需要读取集群资源，确认 ClusterRole 已正确绑定。

4.7 安装后快速验证流程

为帮助你在 5 分钟内完成安装验证，以下步骤可直接复制执行：

1. 检查 Pod 状态： kubectl get pods -n kyverno
2. 检查 Webhook： kubectl get validatingwebhookconfigurations | grep kyverno
3. 创建测试策略：

cat <<EOF | kubectl apply -f -
apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: require-ns-owner
spec:
  validationFailureAction: Audit
  rules:
  - name: check-owner-label
    match:
      resources:
        kinds:
        - Namespace
    validate:
      message: "Namespace must have label 'owner'"
      pattern:
        metadata:
          labels:
            owner: "?*"
EOF

4. 触发验证： kubectl create ns test-ns（应产生 Audit 告警）
5. 查看报告： kubectl get policyreport -A

若上述步骤均通过，则 Kyverno 安装成功且策略引擎正常运行。