2. 环境准备：Kubernetes集群搭建与Kyverno安装
本章是实战调试的基础。你将依次完成：本地Kubernetes集群的搭建、使用Helm Chart安装Kyverno、以及验证所有组件运行正常。一个干净、可复现的环境是后续策略调试与流水线集成的保障。
2.1 本地Kubernetes集群搭建（Minikube vs K3s）
对于本地开发和调试，推荐使用轻量级Kubernetes发行版。下表对比了两种主流方案，帮助你根据资源情况做出选择。
| 特性 | Minikube | K3s |
|---|---|---|
| 架构 | 单节点/多节点（需驱动） | 单节点（Server+Agent合一） |
| 资源占用 | 中等（~2GB RAM） | 低（~512MB RAM） |
| 启动速度 | 较慢（需下载ISO） | 极快（原生二进制） |
| CNI默认 | Calico / Flannel | Flannel（内置） |
| 适用场景 | 完整K8s API兼容性测试 | 边缘/CI环境/资源受限 |
推荐选择：本课程后续调试操作均基于K3s。如果你使用Minikube，请确保分配至少2核CPU和4GB内存，并启用Ingress插件。
2.1.1 使用K3s快速搭建集群
执行以下命令，即可在本地启动一个单节点K3s集群：
# 安装K3s（默认使用containerd）
curl -sfL https://get.k3s.io | sh -
# 检查节点状态
sudo k3s kubectl get node
# 导出kubeconfig（后续Kyverno和流水线工具需要）
mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown $(id -u):$(id -g) ~/.kube/config
export KUBECONFIG=~/.kube/config验证集群就绪：
kubectl cluster-info
kubectl get pods -A预期输出中，coredns、local-path-provisioner、metrics-server 等核心组件应处于 Running 状态。
2.2 安装Kyverno Helm Chart
Kyverno官方推荐使用Helm进行部署，便于版本管理和参数定制。本课程使用Kyverno v1.12+。
2.2.1 添加Helm仓库并安装
# 添加Kyverno Helm仓库
helm repo add kyverno https://kyverno.github.io/kyverno/
helm repo update
# 创建命名空间
kubectl create namespace kyverno
# 安装Kyverno（包含Admission Controller、Cleanup Controller、Reports Controller）
helm install kyverno kyverno/kyverno \
--namespace kyverno \
--create-namespace \
--set admissionController.replicas=1 \
--set backgroundController.replicas=1 \
--set cleanupController.replicas=1 \
--set reportsController.replicas=1
关键参数说明：
admissionController.replicas=1：生产环境建议至少2副本，本地调试1副本即可。backgroundController：负责后台扫描（如检查已有资源是否违反策略）。cleanupController：负责清理过期资源（如TTL策略）。reportsController：负责生成策略报告（PolicyReport）。
2.2.2 验证Helm安装状态
# 查看Helm Release状态
helm list -n kyverno
# 查看Pod是否全部Running
kubectl get pods -n kyverno -o wide预期输出应包含以下Pod：
| Pod名称前缀 | 组件 | 状态 |
|---|---|---|
| kyverno-admission-controller-* | 准入控制器 | Running |
| kyverno-background-controller-* | 后台扫描控制器 | Running |
| kyverno-cleanup-controller-* | 清理控制器 | Running |
| kyverno-reports-controller-* | 报告控制器 | Running |
2.3 验证Kyverno安装状态
安装完成后，需要通过多种方式确认Kyverno正常工作，包括API可用性、Webhook注册、以及策略执行能力。
2.3.1 检查Webhook配置
Kyverno通过MutatingWebhookConfiguration和ValidatingWebhookConfiguration拦截资源请求。检查它们是否已注册：
kubectl get mutatingwebhookconfigurations -l app.kubernetes.io/instance=kyverno
kubectl get validatingwebhookconfigurations -l app.kubernetes.io/instance=kyverno预期应看到类似 kyverno-resource-mutating-webhook-cfg 和 kyverno-resource-validating-webhook-cfg 的条目。
2.3.2 测试策略执行
部署一个简单的“禁止latest镜像标签”策略，验证Kyverno能否正确拦截：
cat <尝试创建一个使用 latest 标签的Pod，应被拒绝：
kubectl run nginx-latest --image=nginx:latest
# 预期输出：Error from server: admission webhook "validate.kyverno.svc" denied the request: ...
常见问题：如果Webhook拒绝请求但策略未生效，请检查
kyverno-admission-controller 的日志：kubectl logs -n kyverno -l app.kubernetes.io/name=kyverno。常见原因包括证书未就绪或Webhook配置未正确更新。
2.4 环境架构总览
下图展示了本章搭建的完整环境组件及其关系：
2.5 环境就绪检查清单
完成上述步骤后，使用以下清单逐项确认环境可用：
| 检查项 | 验证命令 | 预期结果 |
|---|---|---|
| 集群节点就绪 | kubectl get node |
节点状态为 Ready |
| Kyverno Pod运行 | kubectl get pods -n kyverno |
4个Controller均为 Running |
| Webhook注册 | kubectl get mutatingwebhookconfigurations |
至少1条Kyverno相关条目 |
| 策略CRD可用 | kubectl get crd | grep kyverno |
显示 clusterpolicies.kyverno.io 等 |
| 策略执行测试 | 部署 disallow-latest-tag 并测试 |
使用 latest 标签的Pod被拒绝 |
调试提示：如果Webhook未生效，检查
kyverno-admission-controller 日志中的证书错误。常见原因是Helm安装时 --set admissionController.replicas=0 导致Webhook配置未创建。重新运行Helm upgrade并设置副本数为1即可修复。