Cilium 与 Kubernetes 兼容性全解支持的 K8s 版本、e2e 测试矩阵与 CNP/CCNP CRD Schema 版本对照【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium本指南系统梳理 CiliumeBPF-based Networking, Security, and Observability 项目与 Kubernetes 的兼容性保证机制涵盖 e2e 测试覆盖的 Kubernetes 版本范围、Cilium 网络策略 APIcilium.io/v2CRD的 Schema 校验机制以及 Cilium 各发布版本与 CNP/CCNP CRD Schema 版本的一一对照表。读完本文你将能够根据集群的 Kubernetes 版本判断 Cilium 是否受官方 e2e 测试保障理解io.cilium.k8s.crd.schema.version注解的作用并能借助兼容性表规划升级路径。兼容性概述多 API Group 与 e2e 测试保障Cilium 与 Kubernetes 的集成横跨多个 API Group。其中一部分 API 已被弃用或处于 Beta 阶段可能仅在特定 Kubernetes 版本中可用而所有在兼容性表中列出的 Kubernetes 版本均已通过 e2e 测试验证可以确保与 Cilium 兼容。未列入表格的较旧或较新 Kubernetes 版本其兼容性取决于 Kubernetes 自身提供的前向 / 后向兼容能力Cilium 不做显式保证。当前仓库对应的测试基准为 Kubernetes 1.34、1.35、1.36、1.37涉及两种网络策略 APIk8s 版本k8s NetworkPolicy APICiliumNetworkPolicy1.34, 1.35, 1.36, 1.37networking.k8s.io/v1Kubernetes 原生 NetworkPolicy稳定版 APIcilium.io/v2Cilium 自有策略基于 CustomResourceDefinition其中Kubernetes 原生 NetworkPolicy 采用networking.k8s.io/v1这一稳定 API 版本而 CiliumNetworkPolicyCNP与 CiliumClusterwideNetworkPolicyCCNP则是 Cilium 通过 CRD 扩展的、功能更丰富的策略模型API Group 为cilium.io当前版本为v2。e2e 测试策略与云厂商测试矩阵开发分支的 e2e 测试原则作为一般规则Cilium 使用开发分支的最新构建针对 Kubernetes 官方补丁发布页面上定义的、当前受支持的 Kubernetes 版本运行 e2e 测试。这意味着开发分支的测试范围会跟随 Kubernetes 上游的支持节奏动态更新。发布分支的测试稳定性一旦某个发布分支从开发分支创建在整个维护周期内Cilium 通常不会改变该发布分支用于运行 e2e 测试的 Kubernetes 版本。这一策略保证了发布分支的测试结果在维护期内的可复现性与可比性也意味着旧发布分支的兼容性测试基准相对固定。云厂商托管 Kubernetes 的测试矩阵除了社区 Kubernetes 之外Cilium 还针对多家云厂商的托管 Kubernetes 服务运行多版本 e2e 测试。测试矩阵定义在仓库的如下文件中AKSAzure Kubernetes Service.github/actions/azure/k8s-versions.yamlEKSAmazon Elastic Kubernetes Service.github/actions/eks/k8s-versions.yamlGKEGoogle Kubernetes Engine.github/actions/gke/k8s-versions.yaml这些文件是各云厂商环境下的版本测试矩阵的唯一事实来源读者可据此了解当前仓库在托管 Kubernetes 服务上的验证覆盖范围。Cilium CRD Schema 校验机制为什么需要 Schema 校验Cilium 在 Kubernetes 中使用 CRD 承载其网络策略。CRD 的 Schema 校验可能随版本演进发生变化其作用是验证 Cilium Clusterwide Network PolicyCCNP或 Cilium Network PolicyCNP的定义是否合法、字段取值是否符合预期。当策略 CRD 的校验逻辑升级时Cilium 需要一种机制来感知并同步这些变化。核心注解io.cilium.k8s.crd.schema.versionCRD 自身携带一个名为io.cilium.k8s.crd.schema.version的注解其中保存的是 Schema 定义版本号。该注解定义于 pkg/k8s/apis/cilium.io/register.go其源码注释明确说明其用途CustomResourceDefinitionSchemaVersionKey是保存 CRD Schema 版本的标签键名。对应的 Schema 版本常量定义在同一文件中// CustomResourceDefinitionSchemaVersion is semver-conformant version of CRD schema // Used to determine if CRD needs to be updated in cluster CustomResourceDefinitionSchemaVersion 1.34.4从源码可以推断该版本号采用语义化版本SemVer格式并在 CRD Schema 每次发生变更时递增 patch 版本源码注释要求开发者“Bump patch for each change in the CRD schema”。自动更新与按需更新的判断逻辑默认情况下Cilium 会自动将 CRD 及其校验逻辑更新为较新版本。这一自动更新过程由 agent 启动时的 CRD 注册逻辑驱动实现在 pkg/k8s/apis/cilium.io/client/register.go 的createCRD函数中func createCRD(ctx context.Context, logger *slog.Logger, clientset apiextensionsclient.Interface, crdVersionedName string, crdMetaName string) (*apiextensionsv1.CustomResourceDefinition, error) { ciliumCRD : GetPregeneratedCRD(logger, crdVersionedName) return crdhelpers.CreateUpdateCRD( ctx, logger, clientset, constructV1CRD(crdMetaName, ciliumCRD), crdhelpers.NewDefaultPoller(), crdhelpers.NeedsUpdateV1Factory( k8sconst.CustomResourceDefinitionSchemaVersionKey, versioncheck.MustVersion(k8sconst.CustomResourceDefinitionSchemaVersion), ), ) }其工作流程可以概括为从预生成的 CRD 模板GetPregeneratedCRD加载最新 CRD 定义通过constructV1CRD构造 apiextensionsv1版本的 CRD 对象并将io.cilium.k8s.crd.schema.version标签值为1.34.4写入ObjectMeta.Labels借助NeedsUpdateV1Factory比较集群中现有 CRD 的 Schema 版本注解与当前编译进二进制文件的版本若不一致则触发 CRD 更新。createCRD的注释还强调该函数“在 agent 启动时调用但它是幂等的可以安全地重复调用”这保证了重复启动不会破坏集群中的 CRD 状态。CRD 的实际形态仓库中预生成的 CRD 清单位于 examples/crds/v2/ciliumnetworkpolicies.yaml其元数据片段如下apiVersion: apiextensions.k8s.io/v1 kind: CustomResourceDefinition metadata: annotations: controller-gen.kubebuilder.io/version: v0.20.1 name: ciliumnetworkpolicies.cilium.io spec: group: cilium.io names: categories: - cilium - ciliumpolicy kind: CiliumNetworkPolicy listKind: CiliumNetworkPolicyList plural: ciliumnetworkpolicies shortNames: - cnp - ciliumnp singular: ciliumnetworkpolicy可以看到cilium.io/v2Group 下的CiliumNetworkPolicy资源定义该文件长达数千行包含完整的 OpenAPI v3 SchemaCNP 的短名shortNames为cnp/ciliumnp。同目录下的 examples/crds/v2/ciliumclusterwidenetworkpolicies.yaml 则定义了集群范围的 CCNP。Cilium 版本与 CNP/CCNP Schema 版本对照表下表列出 Cilium 各发布版本含预发布与 RC 版本对应的 CNP 和 CCNP Schema 校验版本。同一 Schema 版本可同时被多个 Cilium 补丁版本使用——这符合“Schema 仅在变更时递增 patch 版本”的设计而每次 Schema 版本递增都意味着 CRD 校验逻辑发生了实质变化需要 Cilium 升级后自动同步。Cilium 版本CNP 和 CCNP Schema 版本v1.19.0-pre.01.32.1v1.19.0-pre.11.32.2v1.19.0-pre.21.32.3v1.19.0-pre.31.32.4v1.19.0-pre.41.32.5v1.19.0-rc.01.32.6v1.19.0-rc.11.32.6v1.19.01.32.6v1.19.11.32.6v1.19.21.32.6v1.19.31.32.6v1.19.41.32.6v1.19.51.32.6v1.19.61.32.7v1.19.71.32.7v1.191.32.7v1.20.0-pre.01.33.1v1.20.0-pre.11.33.2v1.20.0-pre.21.33.3v1.20.0-pre.31.33.8v1.20.0-pre.41.33.9v1.20.0-rc.01.33.9v1.20.0-rc.11.33.10v1.20.01.33.11v1.20.11.33.11v1.201.33.11v1.21.0-pre.01.34.2v1.21.0-pre.11.34.4v1.21.0-pre.21.34.4latest / main1.34.4该表格的完整数据来自 Documentation/network/kubernetes/compatibility-table.rst并作为子表被 Documentation/network/kubernetes/compatibility.rst 通过 include 机制嵌入。从表格中能读出的关键信息预发布版本同步递增v1.19 的每个 pre 版本都对应一个新的 Schema 版本1.32.1 → 1.32.5说明 1.19 开发周期内策略 Schema 经历了密集迭代RC 与正式版对齐v1.19.0-rc.0 起 Schema 稳定在 1.32.6v1.20 的 RC 阶段稳定在 1.33.9/1.33.10正式版 v1.20.0 起稳定在 1.33.11符合发布冻结节奏补丁版本不引入 Schema 变更v1.19.0 至 v1.19.5 均使用 1.32.6v1.19.6/v1.19.7 使用 1.32.7说明补丁版本通常只修 Bug 不改变 Schema分支版本跟随末位补丁v1.19、v1.20这类分支级条目与各自最新补丁版本保持相同 Schema1.32.7、1.33.11main 分支领先发布分支latest / main使用 1.34.4与当前仓库 pkg/k8s/apis/cilium.io/register.go 中定义的CustomResourceDefinitionSchemaVersion 1.34.4完全一致。兼容性表的生成与维护机制该对照表并非手工维护而是由脚本自动生成脚本位于 Documentation/check-crd-compat-table.sh。从脚本实现可以还原完整的生成流程版本枚举通过git ls-remote --refs --tags拉取仓库远端的所有v*标签按语义化版本排序后分别收集各 minor 版本的 RC 标签与正式版标签Schema 提取对每个标签执行git grep提取该版本pkg/k8s下CustomResourceDefinitionSchemaVersion ...的值作为该 Cilium 版本对应的 Schema 版本分支回退对每个稳定分支取其分支上的 Schema 版本并写入v1.X分支条目main 分支额外追加latest / main一行取 main 分支当前的 Schema 版本一致性校验脚本内置 semver 比较逻辑如果发现examples/crds目录CRD 定义所在在最近两个发布版本之间发生了变更而 Schema 版本号却没有递增则报错并提示执行--update参数自动递增 patch 版本。结合源码注释pkg/k8s/apis/cilium.io/register.go维护者每次发布都会运行./Documentation/check-crd-compat-table.sh确保对照表与各分支、各标签中的 Schema 版本常量保持同步。这意味着表格本身与源码中的版本常量存在强校验关系——任何 CRD Schema 变更都必须伴随版本号递增否则 CI 会拦截。实战应用如何使用这张兼容性表场景一升级 Cilium 前的风险预判在计划从 Cilium v1.19 升级到 v1.20 时查阅表格可以发现 Schema 版本从 1.32.7 提升至 1.33.11说明期间 CRD 校验逻辑发生了跨 minor 版本的变更。升级后 Cilium 会自动检测并更新 CRD依据io.cilium.k8s.crd.schema.version注解与NeedsUpdateV1Factory的比较逻辑策略对象将按新 Schema 重新校验因此应提前核对存量 CNP/CCNP 中可能受影响的字段。场景二核对当前集群的 Schema 版本集群中实际生效的 Schema 版本可以通过以下命令查看示例kubectl get crd ciliumnetworkpolicies.cilium.io -o jsonpath{.metadata.labels.io\.cilium\.k8s\.crd\.schema\.version}将输出值与对照表中该 Cilium 版本对应的 Schema 版本比对即可确认集群中的 CRD 是否与二进制版本一致。若不一致说明 agent 启动时的自动更新流程尚未完成或在离线环境下使用了手动管理的 CRD。场景三验证 Kubernetes 版本兼容性根据本文第一部分当前仓库 e2e 测试保障的 Kubernetes 版本为 1.34、1.35、1.36、1.37。若你的集群版本位于该区间内且网络策略使用networking.k8s.io/v1原生或cilium.io/v2CNP/CCNP则兼容性受官方测试保障超出该区间的版本则需要依赖 Kubernetes 自身的前向后向兼容性建议通过云厂商矩阵文件AKS、EKS、GKE了解托管环境下的额外验证覆盖。小结Cilium 通过三重机制保障与 Kubernetes 生态的兼容性e2e 测试基线开发分支跟踪 Kubernetes 当前支持版本发布分支在维护期内保持测试版本固定并覆盖 AKS/EKS/GKE 等托管服务CRD Schema 版本化io.cilium.k8s.crd.schema.version注解与CustomResourceDefinitionSchemaVersion常量当前 1.34.4配合驱动 agent 启动时的 CRD 自动更新自动化对照表由 Documentation/check-crd-compat-table.sh 从各 git 标签提取版本常量自动生成 compatibility-table.rst确保文档与源码强一致。升级 Cilium 或规划集群时将本文的兼容性表作为权威依据结合集群内实际 Schema 版本进行核对即可安全地完成版本决策。【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考