📚 课程目录第3章 Kyverno安装

3、Kyverno安装：使用Helm在K8s集群中安装Kyverno、验证安装状态

Kyverno 作为 Kubernetes 原生的策略引擎，推荐使用 Helm Chart 进行生产级部署。本节将演示完整的安装流程、关键参数配置以及安装后的状态验证方法，确保 Kyverno 在集群中正常运行，为后续集成 Backstage 插件奠定基础。

3.1 环境准备与前置检查

在安装 Kyverno 之前，请确认以下环境条件已满足：

检查项	最低要求	验证命令
Kubernetes 集群版本	v1.24 及以上	`kubectl version --short`
Helm 版本	v3.8+	`helm version`
集群资源（最小）	2 vCPU / 4 GB 内存	`kubectl top nodes`
RBAC 权限	cluster-admin 或等效	`kubectl auth can-i '' ''`

提示：如果集群版本低于 v1.24，Kyverno 的部分 Webhook 功能可能无法正常工作。建议优先升级集群版本，或使用 Kyverno 1.8.x 等兼容旧版本的发行系列。

3.2 添加 Helm 仓库与安装

Kyverno 官方 Helm Chart 托管在 kyverno 仓库中。执行以下步骤完成安装：

添加 Helm 仓库

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

创建命名空间（推荐使用 kyverno 作为专用命名空间）

kubectl create namespace kyverno

使用 Helm 安装 Kyverno（生产推荐配置）

helm install kyverno kyverno/kyverno \
  --namespace kyverno \
  --create-namespace \
  --set admissionController.replicas=2 \
  --set backgroundController.replicas=2 \
  --set cleanupController.replicas=1 \
  --set reportsController.replicas=1 \
  --set global.image.tag=v1.12.0

  关键参数说明：
  admissionController.replicas：准入控制器副本数，生产环境建议 ≥2 保证高可用。
backgroundController.replicas：后台扫描控制器副本数，用于周期性策略审计。
cleanupController.replicas：清理控制器，负责删除过期资源。
reportsController.replicas：报告控制器，生成策略执行报告。
global.image.tag：指定 Kyverno 版本，建议锁定到经过测试的稳定版本。

3.3 安装架构与组件关系

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

架构要点：Admission Controller 负责拦截资源创建/更新请求，Background Controller 负责对已有资源进行周期性扫描，Reports Controller 聚合策略执行结果，Cleanup Controller 管理过期资源。四个控制器协同工作，构成完整的策略执行闭环。

3.4 验证安装状态

安装完成后，执行以下命令验证 Kyverno 是否正常运行：

检查 Pod 状态

kubectl get pods -n kyverno

预期输出示例：

NAME                                           READY   STATUS    RESTARTS   AGE
kyverno-admission-controller-7d8f9c6b5c-2x4k9   1/1     Running   0          2m
kyverno-admission-controller-7d8f9c6b5c-j5m7n   1/1     Running   0          2m
kyverno-background-controller-6b4f7c8d9f-3p1q   1/1     Running   0          2m
kyverno-background-controller-6b4f7c8d9f-8r2s   1/1     Running   0          2m
kyverno-cleanup-controller-5a2b3c4d5e-6t3u      1/1     Running   0          2m
kyverno-reports-controller-9e8f7g6h5i-4v5w      1/1     Running   0          2m

检查 Service 与 Webhook

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

验证 Kyverno 版本与 API 可用性

kubectl get clusterpolicy -n kyverno
kubectl api-resources | grep kyverno

常见问题排查：

如果 Pod 处于 CrashLoopBackOff 状态，检查 kubectl logs <pod-name> -n kyverno 查看错误日志，通常与 RBAC 权限或 Webhook 证书有关。
如果 Webhook 未注册，检查集群的 admissionregistration.k8s.io/v1 API 是否启用。
如果使用自签名证书，可能需要配置 --set admissionController.tls.selfSigned=true。

3.5 安装参数速查表

以下表格汇总了生产环境中常用的 Helm 安装参数及其推荐值：

参数路径	推荐值	说明
`admissionController.replicas`	2	准入控制器副本数，保障高可用
`backgroundController.replicas`	2	后台扫描控制器副本数
`cleanupController.replicas`	1	清理控制器，单副本即可
`reportsController.replicas`	1	报告控制器，单副本即可
`global.image.tag`	v1.12.0	锁定稳定版本，避免自动升级
`admissionController.resources`	requests: 100m/256Mi limits: 500m/512Mi	资源限制，防止资源争抢
`features.reporting.enabled`	true	启用策略报告功能

3.6 卸载 Kyverno（可选）

如需卸载 Kyverno，执行以下命令清理所有资源：

helm uninstall kyverno -n kyverno
kubectl delete namespace kyverno
kubectl delete validatingwebhookconfigurations -l webhook.kyverno.io/managed-by=kyverno
kubectl delete mutatingwebhookconfigurations -l webhook.kyverno.io/managed-by=kyverno
kubectl delete clusterpolicy --all
kubectl delete clusterpolicyreport --all

  注意：卸载前请确认没有正在运行的策略依赖 Kyverno，否则可能导致集群资源创建/更新被 Webhook 拒绝。建议先禁用所有策略再执行卸载。