3. 缓存数据结构：缓存键设计原理、缓存值存储格式、TTL与失效策略

Kyverno 配置缓存的底层实现基于 Go 标准库 sync.Map 与自定义的 LRU（Least Recently Used）淘汰逻辑。理解缓存的数据结构是巡检命中率与排查故障的前提。本章从键设计、值存储、TTL 与失效三个维度展开。

3.1 缓存键设计原理

缓存键（Key）采用 复合字符串 拼接方式，确保在集群范围内唯一标识一条策略规则与资源的匹配结果。键的生成遵循以下模板：

cacheKey = policyNamespace + "/" + policyName + "/" + ruleName + "/" + resourceGVK + "/" + resourceName

各字段说明：

3.2 缓存值存储格式

缓存值（Value）是一个结构体，包含策略引擎执行后的完整结果。其核心字段如下：

type CacheEntry struct {
    Result      bool          // 策略是否通过（true=通过，false=拒绝）
    Message     string        // 引擎返回的详细消息
    MatchedRules []string     // 匹配到的规则名称列表
    Timestamp   time.Time     // 缓存写入时间
    TTL         time.Duration // 剩余生存时间
    ResourceVersion string   // 资源对象版本号（用于后续校验）
}

存储格式特点：

• Result + Message：直接缓存策略判定结果，避免重复执行 CEL 或 JMESPath 表达式。
• ResourceVersion：记录缓存生成时的资源版本，用于后续 乐观锁校验。若资源实际版本号与缓存中的版本号不一致，则缓存失效。
• MatchedRules：记录命中哪些规则，便于调试时快速定位。

3.3 TTL 与失效策略

Kyverno 缓存采用 两级失效机制：基于时间的 TTL 失效 + 基于事件的主动失效。

3.3.1 TTL 配置

TTL 从缓存写入时开始计时，到期后条目标记为 “过期”，在下一次清理周期中被删除。过期条目被访问时，Kyverno 会重新执行策略引擎并更新缓存。

3.3.2 事件驱动失效

以下事件会触发缓存条目的 主动失效：

• 资源更新/删除：对应资源的 ResourceVersion 变化，缓存条目立即失效。
• 策略更新：策略内容（规则表达式、参数）变更，所有关联该策略的缓存条目失效。
• 命名空间变更：命名空间标签或注解变化，影响策略匹配范围，相关缓存失效。
• 手动清除：通过 kyverno cache clear 命令或 API 接口强制清空缓存。

3.4 缓存数据结构总览

下图展示了缓存键、值、TTL 与失效策略的整体关系：

3.5 缓存失效流程

下图展示了缓存条目从写入到失效的完整生命周期：