📚 课程目录第2章环境准备

2. Kyverno 基础架构：组件解析与工作流程

Kyverno 是一个为 Kubernetes 设计的原生策略引擎，其核心架构围绕 Admission Controller、Webhook 和 Policy Controller 三大组件构建。理解这些组件如何协同工作，是掌握策略即代码流水线调试的前提。

Kyverno 以 Pod 形式运行在集群中，通常部署在 kyverno 命名空间下。其架构由以下关键组件构成：

组件名称	部署形态	核心职责	关键特性
Admission Controller	Kyverno Pod 主进程	拦截并处理 API Server 的准入请求（Mutating / Validating）	同步执行策略，返回补丁或拒绝响应
Webhook	Kubernetes 原生资源	注册到 API Server 的 MutatingWebhookConfiguration 和 ValidatingWebhookConfiguration	定义触发条件、超时、失败策略
Policy Controller	Kyverno Pod 内的控制器循环	监听 ClusterPolicy / Policy 资源变化，生成对应的 Webhook 配置	动态注册/注销 Webhook，无需重启
Report Controller	Kyverno Pod 内的后台协程	生成背景扫描报告（PolicyReport / ClusterPolicyReport）	对已有资源进行合规审计，不阻塞请求
Cache / Store	内存 + 本地存储	缓存策略规则、Webhook 状态、资源上下文	降低 API Server 压力，加速策略匹配

调试要点： 在回滚策略流水线中，Admission Controller 是策略生效的“第一道关卡”，而 Report Controller 则用于事后审计。当流水线因策略拒绝而失败时，应优先检查 Admission Controller 的日志和 Webhook 配置。

Kyverno 的工作流程分为 准入控制路径 和 后台扫描路径。下图展示了完整的组件交互关系：

当用户通过 kubectl apply 或 API 调用创建/更新资源时，Kyverno 的准入控制路径按以下步骤执行：

请求拦截： API Server 根据 MutatingWebhookConfiguration 和 ValidatingWebhookConfiguration 中的规则，将匹配的请求转发给 Kyverno 的 Admission Controller。
策略匹配： Admission Controller 从本地 Cache 中加载所有生效的 ClusterPolicy 和 Policy，根据资源类型、命名空间标签、资源标签等条件进行匹配。
策略执行：
- Mutating 阶段： 执行 mutate 规则（如注入 Sidecar、添加标签），生成 JSON Patch 返回给 API Server。
- Validating 阶段： 执行 validate 规则（如检查镜像来源、禁止特权容器），返回 allow 或 deny 响应。
结果返回： API Server 根据 Kyverno 的响应决定是否允许资源写入 etcd。

流水线调试关键点： 在回滚策略场景中，如果流水线因策略拒绝而中断，应检查 kyverno 命名空间下 Admission Controller 的日志：

kubectl logs -n kyverno -l app.kubernetes.io/name=kyverno --tail=50 | grep -i "deny\|fail\|error"

同时确认 Webhook 配置的 failurePolicy 字段：Fail 表示策略失败会阻塞流水线，Ignore 则允许通过但记录告警。

除了准入控制，Kyverno 还提供后台扫描能力，用于对集群中已有的资源进行合规审计：

扫描类型	触发方式	输出对象	用途
定时扫描	Report Controller 按间隔（默认 1h）扫描所有匹配的资源	PolicyReport / ClusterPolicyReport	持续合规监控，发现历史遗留问题
手动扫描	通过 `kyverno scan` CLI 或 API 触发	PolicyReport	流水线中作为预检步骤，验证回滚前的资源状态
变更扫描	当策略或资源发生变更时自动触发	PolicyReport	实时反馈策略变更对现有资源的影响

回滚策略流水线提示： 在回滚操作前，建议先执行一次 手动扫描，生成当前资源的合规报告。这可以帮助你判断回滚目标版本是否满足现有策略要求，避免回滚后立即被策略拒绝。

在生产环境中，Kyverno 支持多副本部署以保障高可用。其组件扩展机制如下：

多副本部署： 通过 replicas: 2 或更多，Admission Controller 和 Policy Controller 形成主备模式，Webhook 配置指向 Service，由 Kubernetes 自动负载均衡。
Webhook 超时控制： 默认超时时间为 30 秒，可通过 timeoutSeconds 调整。在流水线调试中，建议设置为 10-15 秒以快速失败。
排除命名空间： 通过 webhookConfiguration.excludeNamespaces 配置，避免 Kyverno 对系统命名空间（如 kube-system）进行策略检查，防止循环依赖。
资源限制： 建议为 Kyverno Pod 设置 resources.requests 和 resources.limits，防止策略处理占用过多集群资源。

最佳实践： 在回滚策略流水线中，建议将 Kyverno 的日志级别设置为 --logLevel=debug，以便在策略拒绝时获取详细的匹配和执行信息。同时，开启 --webhookRegistrationDelay=5s 避免启动时 Webhook 未就绪导致的误拒绝。