📚 课程目录第2章 Kyverno安装与部署

2. Kyverno 安装与部署：使用 Helm 安装、高可用配置与组件健康验证

本章聚焦于在生产环境中使用 Helm 包管理器安装 Kyverno，配置高可用模式，并验证所有组件的健康状态。正确的安装与部署是后续策略管理的基础，尤其在高可用的云原生环境中，必须确保策略引擎本身具备弹性与可靠性。

2.1 环境准备与 Helm 仓库配置

在安装 Kyverno 之前，需要确保 Kubernetes 集群版本 ≥ 1.22，并且已安装 Helm 3.8+。首先添加 Kyverno 官方 Helm 仓库并更新索引。

# 添加 Kyverno Helm 仓库
helm repo add kyverno https://kyverno.github.io/kyverno/

# 更新仓库索引
helm repo update

# 验证仓库是否添加成功
helm search repo kyverno/kyverno --versions | head -5

版本选择建议： 生产环境建议锁定一个经过验证的稳定版本，例如 v1.12.x 或 v1.13.x。避免直接使用 latest 或未经过充分测试的 RC 版本。可以通过 --version 参数指定版本号。

2.2 使用 Helm 安装 Kyverno（基础模式）

基础安装适用于测试或小规模集群。以下命令将 Kyverno 安装到 kyverno 命名空间，并启用核心策略引擎。

# 创建命名空间
kubectl create namespace kyverno

# 使用 Helm 安装 Kyverno（基础模式）
helm install kyverno kyverno/kyverno \
  --namespace kyverno \
  --create-namespace \
  --version v1.13.0 \
  --set replicaCount=1 \
  --set serviceMonitor.enabled=false

安装完成后，可以通过以下命令快速检查 Pod 状态：

kubectl get pods -n kyverno -w

预期输出应包含一个 kyverno-xxx 的 Pod，状态为 Running，且 READY 列为 1/1。

2.3 配置高可用（HA）模式

在生产环境中，单副本的 Kyverno 存在单点故障风险。高可用模式通过多副本部署、Pod 反亲和性以及 leader election 机制来保证策略评估的连续性。下表列出了 HA 模式的关键配置参数。

参数	默认值	HA 推荐值	说明
`replicaCount`	1	3	副本数量，建议至少 3 个以保证多数派可用
`podAntiAffinity`	soft	hard	强制 Pod 分布在不同节点，避免节点故障影响所有副本
`resources.requests.cpu`	100m	500m	HA 模式下需要更多 CPU 资源处理并发请求
`resources.requests.memory`	128Mi	512Mi	内存需求随策略数量和集群规模增长
`leaderElection.enabled`	true	true	必须启用，确保同一时刻只有一个控制器执行写操作

以下是一个完整的 HA 安装命令示例：

helm upgrade --install kyverno kyverno/kyverno \
  --namespace kyverno \
  --version v1.13.0 \
  --set replicaCount=3 \
  --set podAntiAffinity.hard=true \
  --set resources.requests.cpu=500m \
  --set resources.requests.memory=512Mi \
  --set resources.limits.cpu=1000m \
  --set resources.limits.memory=1Gi \
  --set leaderElection.enabled=true \
  --set serviceMonitor.enabled=true

资源规划提醒： HA 模式下，3 个副本的总资源需求约为 1.5 CPU 和 1.5Gi 内存（requests）。如果集群节点资源紧张，建议至少保证每个副本所在节点有足够的余量，避免因资源竞争导致 Pod 驱逐或 OOMKill。

2.4 Kyverno 组件架构与健康检查

Kyverno 由多个核心组件构成，理解它们之间的关系有助于快速定位问题。下图展示了 Kyverno 在 HA 模式下的组件架构与健康检查链路。

健康检查分为三个层次：

Pod 级健康检查： Kyverno 容器内置了 /healthz（存活检查）和 /readyz（就绪检查）端点。Kubelet 定期探测，如果失败则重启 Pod 或从 Service 端点中移除。
组件级健康检查： 通过 kubectl get pods -n kyverno 查看所有 Pod 的 READY 状态。HA 模式下，所有副本的 READY 应为 1/1。
功能级健康检查： 部署一个测试策略并创建违规资源，验证 Webhook 是否正常拦截。这是最接近用户感知的验证方式。

2.5 验证安装状态与组件健康

安装完成后，建议执行以下验证步骤清单，确保集群已准备好运行策略。

验证项	命令/方法	预期结果
Pod 状态	`kubectl get pods -n kyverno`	所有 Pod 均为 `Running`，`READY` 为 `1/1`
Service 存在	`kubectl get svc -n kyverno`	存在 `kyverno-svc` 和 `kyverno-svc-metrics`
Webhook 注册	`kubectl get mutatingwebhookconfigurations` `kubectl get validatingwebhookconfigurations`	存在以 `kyverno` 开头的 Webhook 配置
Leader 选举	`kubectl logs -n kyverno -l app=kyverno --tail=20 \| grep leader`	只有一个 Pod 输出 `leading`，其余输出 `following`
策略执行测试	部署一个简单的 `disallow-latest-tag` 策略并创建违规 Pod	Pod 创建被拒绝，返回策略违规信息

快速健康检查脚本： 可以将以下命令组合成一个 shell 脚本，用于日常巡检：

#!/bin/bash
NAMESPACE="kyverno"
echo "=== Pod Status ==="
kubectl get pods -n $NAMESPACE -o wide
echo ""
echo "=== Service Endpoints ==="
kubectl get svc -n $NAMESPACE
echo ""
echo "=== Webhook Configurations ==="
kubectl get mutatingwebhookconfigurations | grep kyverno
kubectl get validatingwebhookconfigurations | grep kyverno
echo ""
echo "=== Leader Election Status ==="
kubectl logs -n $NAMESPACE -l app=kyverno --tail=10 | grep -E "leading|following"

2.6 常见安装问题与排错

下表列出了安装过程中可能遇到的典型问题及对应的解决方案。

问题现象	可能原因	解决方案
Pod 一直处于 `Pending` 状态	节点资源不足，或 PVC 无法挂载	检查节点资源使用情况：`kubectl describe node`；如果使用了持久化存储，检查 PVC 状态
Webhook 注册失败	集群的 `admissionregistration.k8s.io/v1` API 未启用或版本不兼容	确认集群版本 ≥ 1.22；检查 API Server 启动参数是否禁用了 admission webhook
Leader 选举异常，多个 Pod 同时成为 Leader	网络分区或 etcd 性能问题导致租约过期	检查 etcd 集群健康状态；增加 `leaderElection.leaseDuration` 参数（默认 15s）
策略不生效，资源创建未被拦截	Webhook 配置被修改或证书过期	重新安装 Kyverno 或手动重建证书：`kubectl delete secret -n kyverno kyverno-svc.kyverno.svc.kyverno-tls` 然后重启 Pod

日志分析技巧： 当遇到策略执行异常时，优先查看 Kyverno 控制器的日志。使用 kubectl logs -n kyverno -l app=kyverno --tail=100 可以获取最近 100 行日志。关注 level=error 或 level=warn 的条目，通常能直接定位问题根因。

通过以上步骤，你已经完成了 Kyverno 的安装、高可用配置以及健康验证。接下来可以进入策略编写与基线核验的实战环节。