企业官网建设流程全解析

Kubespray 发布流程完整指南：从版本规划、Release Notes 生成到容器镜像发布

【免费下载链接】kubesprayDeploy a Production Ready Kubernetes Cluster项目地址: https://gitcode.com/GitHub_Trending/ku/kubespray

导读

本文档围绕 RELEASE.md 展开，系统梳理 Kubespray 项目从「提出发布 Issue」到「发布公告」的完整发布流程，覆盖大版本（major）/小版本（minor）的版本策略、支持矩阵（n-2Kubernetes 支持下限）、Release Notes 的自动化生成、quay.io/kubespray/kubespray与quay.io/kubespray/vagrant容器镜像的构建与推送等关键环节。读完本文，你将掌握 Kubespray 维护者发布一个新版本所需的全部操作步骤、脚本与命令，并理解版本号、校验和（checksums）与分支策略背后的技术约束。

发布流程总览

Kubespray 采用「按需发布」（released on an as-needed basis）的策略，即不按固定日历周期发版，而是根据变更积累与实际需求决定何时发布。完整流程共 14 个步骤，贯穿「提议 → 审批 → 发版 → 后续公告」四个阶段：

1. 提出发布 Issue：在 Issue 中列出自上次发布以来的变更日志（changelog）；
2. 审批：至少一位 approvers（仓库维护者批准人）批准该发布；
3. （仅大版本）维护默认 Kubernetes 版本及前两个次版本的二进制校验和与按次版本（per-minor）组件映射，支持下限为n-2；kubelet_checksums中最旧的条目决定kube_version_min_required；
4. （仅大版本）从*_checksums变量中移除已 EOL（End of Life）Kubernetes 版本的哈希；
5. 使用 Kubernetes Release Notes Generator 生成 Release Notes（详见下文）；
6. approver 在 GitHub 上以vX.Y.Z格式创建 tag 与 Release，并附带 Release Notes；
7. （仅大版本）approver 创建release-X.Y形式的发布分支；
8. （大版本）在master分支上把 galaxy.yml 中的版本号提升到下一个预期大版本（X.y.0，其中y = Y + 1），并提交 Pull Request；
9. （小版本）在release-X.Y分支上把 galaxy.yml 中的版本号提升到下一个预期小版本（X.Y.z，其中z = Z + 1），并提交 Pull Request；
10. 构建并打标签对应的容器镜像quay.io/kubespray/kubespray:vX.Y.Z与quay.io/kubespray/vagrant:vX.Y.Z（详见下文）；
11. 关闭发布 Issue；
12. 向dev@kubernetes.io发送主题为[ANNOUNCE] Kubespray $VERSION is released的公告邮件；
13. 更新#kubespray频道话题为vX.Y.Z is released! | ...；
14. 创建/更新升级 Kubernetes 与 k8s-conformance 的 Issue。

从源码层面看，这套流程中的「发布」与「版本标识」并非孤立动作：仓库根目录的 galaxy.yml 中version: 2.32.0即为 Ansible Galaxy Collection 的发布版本号，步骤 8/9 的版本提升操作正是围绕该字段展开；而 Dockerfile 中固定安装的kubectl版本（当前为v1.36.4）也与步骤 3/4 中校验和维护的 Kubernetes 版本保持一致。

大版本与小版本：分支策略与里程碑

分支与 tag 的差异

• 大版本（vX.Y）：Kubespray 维护一个release-X.Y分支；
• 小版本（vX.Y.Z）：仅以 tag 形式存在，不单独维护分支；
• 安全补丁与 bug 修复：可以回移植（backported）到大版本/小版本。

里程碑与支持生命周期

• 大版本与小版本的修复通过维护版本（vX.Y.Z）交付，并归入对应的 GitHub milestone；
• 该里程碑在大/小版本的支持生命周期内保持打开，一旦里程碑被关闭，生命周期即告结束，此后只能发布下一个大版本或小版本。

版本语义与支持矩阵

• 不使用 semver：Kubespray 没有不稳定的发布（unstable releases），也没有对外 API，因此不遵循 semver 规范。每一个版本都只描述一个稳定发布；
• 破坏性变更：由默认值变更或非 contrib 的 ansible roles 的 playbook 引入的破坏性变更，必须在 Release Notes 中说明；而 contrib 插件、所绑定的 Kubernetes 与其他组件版本造成的破坏性变更，则视为组件自身职责，超出 Kubespray 范围；
• 版本绑定规则：小版本（minor release）可以变更组件的版本，但不能变更kube_version的大版本。更大的kube_version需要新的大版本或小版本发布。原文档给出示例：若 Kubespray v2.0.0 绑定kube_version: 1.4.x、calico_version: 0.22.0、etcd_version: 3.0.6，则 v2.1.0 只允许kube_version的次版本变更（如 v1.5.1），而对 etcd v4 或 calico 1.2.3 等组件版本变更不受限制；Kubespray v3.x.x 则应绑定kube_version: 2.x.x；
• 支持下限n-2：Kubespray 大/小版本支持默认kube_version的大/小版本，以及前两个 Kubernetes 次版本，前提是这些版本的二进制校验和与按次版本所需的组件映射已存在。其他组件版本只有在对应版本映射被选中时才受支持——仅有校验和条目并不代表受支持。

校验和与kube_version_min_required的源码印证

发布流程中「大版本需维护n-2支持下限」的要求，在仓库源码中有直接体现。kubelet_checksums定义于 roles/kubespray_defaults/vars/main/checksums.yml，其amd64/arm64/ppc64le三个架构下按 Kubernetes 版本维护了 sha256 校验和。相关推导逻辑位于 roles/kubespray_defaults/defaults/main/main.yml：

• 默认kube_version取kubelet_checksums['amd64']中最新的（第一个）键；
• kube_version_min_required取最旧的（最后一个）键，即最旧的 kubelet 校验和条目决定了版本支持下限。

在 roles/validate_inventory/tasks/main.yml 中，这个下限会真正生效：kube_version必须满足>= kube_version_min_required，否则 playbook 会以明确报错终止——"The current release of Kubespray only support newer version of Kubernetes than {{ kube_version_min_required }}"。

同时，kubelet_checksums与下载链路耦合：kubelet_binary_checksum通过kubelet_checksums[image_arch][kube_version]动态解析（见 roles/kubespray_defaults/defaults/main/download.yml），因此「为某版本维护校验和」与「该版本可被正常下载部署」是同一件事。这也解释了为什么大版本发布时既要把 EOL 版本的哈希从*_checksums中移除（避免继续向用户提供不受支持的目标），又要补齐n-2以内版本的哈希。

Release Note 的自动化生成

使用 Kubernetes Release Notes Generator

Release Note 通过 Kubernetes Release Notes Generator 生成，核心命令如下：

export GITHUB_TOKEN=<your-github-token> export ORG=kubernetes-sigs export REPO=kubespray release-notes generate --org "${ORG}" --repo "${REPO}" --repo-path "${PWD}" --start-sha <The start commit-id> --end-sha <The end commit-id> --dependencies=false --output=/tmp/kubespray-release-note

各参数含义：

• --start-sha：本次发布时间段的起始 commit-id（通常取上一次发布的 commit）；
• --end-sha：本次发布时间段的结束 commit-id（即待发布的最新 commit）；
• --dependencies=false：不把依赖组件的更新（dependencies）纳入 Release Note 的 PR 统计；
• --output：Release Note 输出文件的路径。

处理 "Uncategorized" 分组

生成完成后，如果输出文件（如/tmp/kubespray-release-note）中出现### Uncategorized分组，说明其中有 PR 缺少合法的 kind 标签（如kind/feature）。此时需要对每个未分类的 PR 补上合法标签，然后重新运行上述release-notes generate命令，才能得到一份完整、可对外发布的 Release Note。

容器镜像的创建与推送

kubespray:vX.Y.Z（主发布镜像）

该镜像由仓库根目录的 Dockerfile 构建，命令如下：

cd kubespray/ nerdctl build -t quay.io/kubespray/kubespray:vX.Y.Z . nerdctl push quay.io/kubespray/kubespray:vX.Y.Z

从 Dockerfile 内容看，该镜像以不可变的 Ubuntu 镜像（带完整 sha256 digest）为基础，安装python3/pip/sshpass/rsync/openssh-client等依赖，通过 requirements.txt 安装 Ansible 及所需 Collection，并预置固定版本的kubectl（当前为v1.36.4，安装时校验 sha256）。随后将 playbook、roles、inventory、library、plugins、contrib、extra_playbooks 等全部目录 COPY 进/kubespray工作目录——也就是说，发布镜像内置了完整可执行的 Kubespray 部署工具链。

vagrant:vX.Y.Z（Vagrant CI 镜像）

该镜像由 test-infra/vagrant-docker/build.sh 构建：

cd kubespray/test-infra/vagrant-docker/ ./build vX.Y.Z

build.sh会将vX.Y.Z作为KUBESPRAY_VERSION构建参数传入，以quay.io/kubespray/kubespray:${VERSION}为基础镜像（见 test-infra/vagrant-docker/Dockerfile），并在其上安装 Vagrant（当前锁定2.3.7）、vagrant-libvirt插件，同时设置VAGRANT_DEFAULT_PROVIDER=libvirt与VAGRANT_ANSIBLE_TAGS=facts，供 vagrant CI 任务使用（详见 test-infra/vagrant-docker/README.md）。

权限说明

以上操作要求具备向quay.io/kubespray/推送容器镜像的权限。如果缺少权限，需要在#kubespray-dev频道上申请。

常见问题与实战要点

• 为什么用nerdctl而不是docker构建镜像？这是流程文档给出的标准命令；nerdctl与 containerd 生态兼容，两者产出的 OCI 镜像均可推送到 quay.io，实际操作中以维护团队当前使用的容器工具为准。
• 为什么大版本才需要处理校验和与n-2支持矩阵？因为只有大版本才会改变默认kube_version及其支持范围；小版本只允许组件版本的增量变更，不触碰 Kubernetes 大版本，也就无需重新梳理支持下限。
• 如何判断某个 Kubernetes 版本是否受当前 Kubespray 支持？查看 roles/kubespray_defaults/vars/main/checksums.yml 中kubelet_checksums是否含该版本；但需注意：仅有校验和条目并不代表受支持，受支持还要求存在对应的按次版本组件映射（per-minor component mappings）。
• 版本号提升的位置：无论大版本（master分支）还是小版本（release-X.Y分支），提升的版本号都位于仓库根目录的 galaxy.yml 中version字段，这也是 Ansible Galaxy 消费 Kubespray Collection 时的版本来源。

结语

Kubespray 的发布流程是一套「流程 + 工具 + 仓库约束」结合的体系：Release Issue 与审批机制保证发布有据可查，galaxy.yml版本号与checksums.yml支持矩阵保证版本标识与可部署版本一致，Release Notes Generator 保证变更记录可自动汇总，而两个 quay.io 镜像则分别服务「生产部署」与「Vagrant CI」两类场景。对于想要参与贡献或自建分发流程的读者，理解这 14 个步骤与背后的源码机制，是安全发版的基础。

【免费下载链接】kubesprayDeploy a Production Ready Kubernetes Cluster项目地址: https://gitcode.com/GitHub_Trending/ku/kubespray