企业官网建设流程全解析

K3s Kubernetes 补丁版本发布全流程指南：从上游变基打标到 Channel 更新的完整工程实践

【免费下载链接】k3sLightweight Kubernetes项目地址: https://gitcode.com/GitHub_Trending/k3/k3s

K3s（Lightweight Kubernetes）在跟随上游 Kubernetes 发布补丁（patch）版本时，需要一套完整的工程流程：先把 k3s 在上游 Kubernetes 仓库中的定制改动 rebase 到新版本 tag 上，为每个 staging 模块生成-k3s1后缀的标签并推送，再更新 K3s 主仓库的go.mod依赖、验证构建、创建 PR，随后依次完成 RC 发布、镜像检查、Rancher KDM 同步以及 Channel Server 的 stable 版本切换。本文以 docs/release/kubernetes-upgrade.md 为主体，结合 K3s 仓库内的 go.mod、channel.yaml、scripts/version.sh 与 Makefile 等源码佐证，完整还原这一流程。读完本文，你将掌握 K3s 发布负责人（Release Captain）执行一次 Kubernetes 补丁版本升级所需的全部命令、版本变量推导逻辑与发布检查项。

发布流程全景概览

一次标准的 K3s Kubernetes patch 升级大致分为以下阶段，本文将按此顺序逐步展开：

1. 准备环境：Git、Go（GOPATH）、GPG 签名与 Docker 配置；
2. 变基与打标：在kubernetes/kubernetes仓库中，把 k3s 的定制提交 rebase 到新版本 tag，通过tag.sh为每个 Kubernetes staging 模块生成v<版本>-k3s1标签并推送至 k3s-io 远端；
3. 更新主仓库：修改 K3s 仓库的go.mod指向新标签，执行go mod tidy，必要时升级 Go 版本；
4. 验证与合入：本地构建验证（SKIP_VALIDATE=1 make）、提交 PR、等待 CI 与评审合入；
5. 发布与同步：依次创建 RC、检查 system-agent-installer-k3s 与 k3s-upgrade 镜像、更新 Rancher KDM、创建 GA 发布、最后更新 Channel Server。

其中版本号规则贯穿始终：上游 Kubernetes 补丁版本形如v1.36.3，K3s 标签形如v1.36.3-k3s1，发布版本形如v1.36.3+k3s1（+分隔 k3s 自身的迭代号，K3s 单独更新时从k3s1递增到k3s2）。

开始之前：环境与版本前提

发布流程主要依赖Git与Go两个工具链：

• Git：可通过系统自带的包管理器安装；
• Go：需要正确安装并配置gopath，通常通过环境变量GOPATH指定，例如：

export GOPATH="${HOME}/go"

此外还有两项提交/构建环境的配置：

1. GPG 签名：在本地 Git 配置中关闭 commit 的 GPG 签名（tag 的 GPG 签名按需另行配置）：

git config --local commit.gpgSign false

2. Docker 中的用户身份兼容：发布流程会在 Docker 容器内执行git操作，为预防用户身份（UID）不匹配引发的问题，设置如下全局配置：

git config --global core.safelyUseIncompatibleGitCredentialHelper true

克隆上游并配置远端

发布工作需要同时操作上游 Kubernetes 仓库与k3s-io 的 Kubernetes fork。首先以upstream为 origin 克隆官方仓库，再加入 k3s-io 远端：

# initial clone git clone --origin upstream \ https://github.com/kubernetes/kubernetes.git \ ${GOPATH}/src/github.com/kubernetes/kubernetes cd ${GOPATH}/src/github.com/kubernetes/kubernetes # add the k3s-io remote git remote add k3s-io https://github.com/k3s-io/kubernetes.git # fetch all remote branches and tags. If you receive a message saying that # previous tags will be "clobbered", add --force to the command below. git fetch --all --tags

• 若git fetch --all --tags提示先前已有 tags 会被 "clobbered"，需在命令后追加--force；
• 可执行第二遍git fetch --all --tags以确认没有遗漏的 tag，便于尽早发现拉取错误（参见 docs/release/expanded/cut_release.md 中的完整命令清单）。

变基与生成标签

设置版本变量

建立本地变基分支前，需要先导出全部版本相关变量。这些变量贯穿后续所有步骤，务必与实际要升级的版本一一对应：

export GLOBAL_GIT_CONFIG_PATH=$(git config --list --show-origin --show-scope --global | awk 'NR==1{ split($2,path,":"); print path[2] }') export SSH_MOUNT_PATH=$(echo ${SSH_AUTH_SOCK} || echo "${HOME}/.ssh/id_rsa") # Set up your new/old versions of Kubernetes export OLD_K8S=<old-k8s-version> export NEW_K8S=<new-k8s-version> export OLD_K8S_CLIENT=<old-k8s-client-version> export NEW_K8S_CLIENT=<new-k8s-client-version> export OLD_K3S_VER="${OLD_K8S}-k3s1" export NEW_K3S_VER="${NEW_K8S}-k3s1" export RELEASE_BRANCH=<k8s-release-branch> export GOPATH=$(go env GOPATH)

各变量的含义与示例值如下表：

注意：K8S_CLIENT通常形如v0.<minor>.<patch>，与K8S的v1.<minor>.<patch>主版本号不同，这是 Kubernetes 仓库中client-go版本号体系的惯例，sed替换时按此区分。

清理旧构建产物

rm -rf _output

执行变基

将上一次发布的 k3s 定制提交（剔除 merge commit，即~1）rebase 到新的上游 tag 之上。完成后会停留在 detached HEAD 上，该提交将在下一步被打上标签：

git rebase --onto ${NEW_K8S} ${OLD_K8S} ${OLD_K3S_VER}~1

该命令的语义是：以${OLD_K8S}为边界、把${OLD_K3S_VER}~1这一分支上的 k3s 定制改动，整体重放到${NEW_K8S}tag 之上。Kubernetes 每个版本对 Go 版本有严格要求，因此需要读取仓库内的 Go 版本定义并用指定版本的 Go 构建。

构造构建容器

Kubernetes 对每个 release 使用的 Go 版本有严格要求，发布流程采用 Alpine + Docker 的方式指定构建所用 Go 版本：

export GOVERSION=$(grep -Po '^\s*\K\S+' .go-version) export GOIMAGE="golang:${GOVERSION}-alpine" export BUILD_CONTAINER="FROM ${GOIMAGE}\n \ RUN apk add --no-cache \ bash \ git \ make \ tar \ gzip \ curl \ git \ coreutils \ rsync \ alpine-sdk" echo -e ${BUILD_CONTAINER} | docker build -t ${GOIMAGE}-dev -

即在golang:<版本>-alpine基础镜像上追加bash、git、make、tar、gzip、curl、coreutils、rsync、alpine-sdk等构建依赖，构建出-dev后缀的开发镜像。

运行 tag.sh 生成标签

rebase 操作会把tag.sh脚本带入工作树。接下来在容器内以当前用户身份执行tag.sh，为所有 Kubernetes 模块生成-k3s1标签：

docker run --rm -u $(id -u):$(id -g) \ -v ${GOPATH}/src:/go/src:rw \ -v ${GOPATH}/pkg:/go/pkg:rw \ -v ${GOPATH}/.cache:/go/.cache:rw \ -v ${GLOBAL_GIT_CONFIG_PATH}:/go/.gitconfig:rw \ -e GIT_TRACE=1 \ -e HOME=/go \ -e GOCACHE=/go/.cache \ -w /go/src/github.com/kubernetes/kubernetes \ ${GOIMAGE}-dev chown -R $(id -u) .git | ./tag.sh ${NEW_K3S_VER} 2>&1 | tee ~/tags-${NEW_K3S_VER}.log

关键点说明：

• -u $(id -u):$(id -g)：以当前用户身份运行，避免容器内 root 产生文件属主问题（docs/release/expanded/cut_release.md 的示例中也特意注释了“note user id is 502, I am not root user”）；
• 通过卷挂载把GOPATH的src、pkg、.cache以及全局.gitconfig传入容器，保证容器内的 Go 与 Git 行为与宿主机一致；
• 输出同时通过tee落盘为~/tags-${NEW_K3S_VER}.log，便于回溯。

tag.sh运行结束后，输出末尾会列出若干条git push命令，将这些命令保存为可执行脚本push.sh：

chmod +x push.sh

tag.sh 输出示例（以 1.28 patch release 为例）

git push ${REMOTE} staging/src/k8s.io/api/v1.28.2-k3s1 git push ${REMOTE} staging/src/k8s.io/apiextensions-apiserver/v1.28.2-k3s1 git push ${REMOTE} staging/src/k8s.io/apimachinery/v1.28.2-k3s1 git push ${REMOTE} staging/src/k8s.io/apiserver/v1.28.2-k3s1 git push ${REMOTE} staging/src/k8s.io/client-go/v1.28.2-k3s1 git push ${REMOTE} staging/src/k8s.io/cli-runtime/v1.28.2-k3s1 git push ${REMOTE} staging/src/k8s.io/cloud-provider/v1.28.2-k3s1 git push ${REMOTE} staging/src/k8s.io/cluster-bootstrap/v1.28.2-k3s1 git push ${REMOTE} staging/src/k8s.io/code-generator/v1.28.2-k3s1 git push ${REMOTE} staging/src/k8s.io/component-base/v1.28.2-k3s1 git push ${REMOTE} staging/src/k8s.io/component-helpers/v1.28.2-k3s1 git push ${REMOTE} staging/src/k8s.io/controller-manager/v1.28.2-k3s1 git push ${REMOTE} staging/src/k8s.io/cri-api/v1.28.2-k3s1 git push ${REMOTE} staging/src/k8s.io/csi-translation-lib/v1.28.2-k3s1 git push ${REMOTE} staging/src/k8s.io/dynamic-resource-allocation/v1.28.2-k3s1 git push ${REMOTE} staging/src/k8s.io/endpointslice/v1.28.2-k3s1 git push ${REMOTE} staging/src/k8s.io/kms/v1.28.2-k3s1 git push ${REMOTE} staging/src/k8s.io/kube-aggregator/v1.28.2-k3s1 git push ${REMOTE} staging/src/k8s.io/kube-controller-manager/v1.28.2-k3s1 git push ${REMOTE} staging/src/k8s.io/kubectl/v1.28.2-k3s1 git push ${REMOTE} staging/src/k8s.io/kubelet/v1.28.2-k3s1 git push ${REMOTE} staging/src/k8s.io/kube-proxy/v1.28.2-k3s1 git push ${REMOTE} staging/src/k8s.io/kube-scheduler/v1.28.2-k3s1 git push ${REMOTE} staging/src/k8s.io/legacy-cloud-providers/v1.28.2-k3s1 git push ${REMOTE} staging/src/k8s.io/metrics/v1.28.2-k3s1 git push ${REMOTE} staging/src/k8s.io/mount-utils/v1.28.2-k3s1 git push ${REMOTE} staging/src/k8s.io/pod-security-admission/v1.28.2-k3s1 git push ${REMOTE} staging/src/k8s.io/sample-apiserver/v1.28.2-k3s1 git push ${REMOTE} staging/src/k8s.io/sample-cli-plugin/v1.28.2-k3s1 git push ${REMOTE} staging/src/k8s.io/sample-controller/v1.28.2-k3s1 git push ${REMOTE} v1.28.2-k3s1

这些标签覆盖了 Kubernetes 的绝大多数 staging 模块（api、apimachinery、client-go、kubelet、kube-proxy、kubectl、metrics等），最终还会为整个仓库打一个v1.28.2-k3s1总标签。

推送标签到 k3s-io 远端

设置REMOTE变量并执行push.sh，将上一步生成的所有标签推送到 k3s-io 的 fork 仓库：

export REMOTE=k3s-io ./push.sh

更新 K3s 依赖到新标签

此时工作树中已有一批打了新标签的 Kubernetes 模块。接下来在K3s 主仓库中更新go.mod，使其指向这些新标签，然后即可提交 PR 供评审。

cd ${GOPATH}/src/github.com/k3s-io/k3s git remote add upstream https://github.com/k3s-io/k3s.git git fetch upstream git branch delete ${NEW_K3S_VER} git checkout -B ${NEW_K3S_VER} upstream/${RELEASE_BRANCH} git clean -xfd sed -Ei "\|github.com/k3s-io/kubernetes| s|${OLD_K3S_VER}|${NEW_K3S_VER}|" go.mod sed -Ei "s/k8s.io\/kubernetes v\S+/k8s.io\/kubernetes ${NEW_K8S}/" go.mod sed -Ei "s/${OLD_K8S_CLIENT}/${NEW_K8S_CLIENT}/g" go.mod # since drone perform the builds and tests for the updated tags we no longer need to run make locally. # We now update the go.sum by running go mod tidy: go mod tidy

以上sed命令逐一完成三处替换：

1. 把所有github.com/k3s-io/kubernetes相关的 replace 目标从${OLD_K3S_VER}（如v1.28.1-k3s1）替换为${NEW_K3S_VER}（如v1.28.2-k3s1）；
2. 把k8s.io/kubernetes主模块版本替换为新的${NEW_K8S}；
3. 全局替换client-go关联版本号${OLD_K8S_CLIENT}→${NEW_K8S_CLIENT}。

以当前仓库 go.mod 的实际状态为例，可以看到这一替换体系的最终形态——所有k8s.io/*模块均通过replace指向github.com/k3s-io/kubernetes下对应 staging 目录的-k3s1标签：

k8s.io/api => github.com/k3s-io/kubernetes/staging/src/k8s.io/api v1.36.3-k3s1 k8s.io/apimachinery => github.com/k3s-io/kubernetes/staging/src/k8s.io/apimachinery v1.36.3-k3s1 k8s.io/client-go => github.com/k3s-io/kubernetes/staging/src/k8s.io/client-go v1.36.3-k3s1 k8s.io/kubelet => github.com/k3s-io/kubernetes/staging/src/k8s.io/kubelet v1.36.3-k3s1 k8s.io/kubernetes => github.com/k3s-io/kubernetes v1.36.3-k3s1

由于 Drone CI 会针对更新后的标签自动执行构建与测试，本地无需再运行make，只需用go mod tidy更新go.sum。

同步 Go 版本

如果新版本 Kubernetes 要求的 Go 版本有变化，需要同步更新 K3s 仓库中的 Dockerfile 与 GitHub Actions 工作流：

export OLD_GO_VERSION=<old-go-version> sed -i'' "s/$OLD_GO_VERSION/$GOVERSION/g" Dockerfile.* .github/workflows/integration.yaml .github/workflows/unitcoverage.yaml

即把Dockerfile.*（含Dockerfile、Dockerfile.test、Dockerfile.manifest等，具体范围以仓库实际文件为准）以及.github/workflows/integration.yaml、.github/workflows/unitcoverage.yaml中的旧 Go 版本统一替换为$GOVERSION。

关于 modsync 脚本的说明

需要特别注意的是：modsync 脚本（k3s_modsync.sh）仅用于"针对特定上游 Kubernetes commit 而非 tag"的更新场景。常规 patch release 流程中不需要使用它。仅在需要把 K3s 的依赖与某个上游 commit 对齐时，才执行：

curl -s https://raw.githubusercontent.com/rancher/ecm-distro-tools/master/bin/k3s_modsync.sh | sh -

验证 K3s 构建

在提交 PR 之前，先在本地验证 K3s 可以正常构建：

SKIP_VALIDATE=1 make

其中SKIP_VALIDATE=1用于跳过仓库校验步骤（对应 Makefile 中validatetarget 传递的SKIP_VALIDATE构建参数），仅验证编译产物能否产出。若构建失败，可能需要同步更新其他持有上游组件 fork 的仓库，常见的有：

• k3s-io/klog
• k3s-io/cri-dockerd
• k3s-io/containerd

对于这些仓库，需要为其构建并推送新 tag，然后在go.mod中把对应依赖更新到新 tag。

创建 PR

将所有改动提交并推送到个人 fork 的${NEW_K3S_VER}分支：

git commit --all --signoff -m "Update to ${NEW_K8S}" git push --set-upstream origin ${NEW_K3S_VER}

随后基于该分支创建 PR，务必以对应的发布分支（${RELEASE_BRANCH}）为合入目标，等待 CI 在 PR 上运行测试。CI 通过并得到两个 approve之后，即可 squash-merge 该 PR；merge 后的主 CI 运行完成后，就可以打 RC 标签了。

创建发布候选（RC）

发布由打标签触发。在 GitHub UI 上按以下步骤创建 release：

1. 按正在处理的发布版本设置 title 与 tag，例如：
   • 常规升级（仅升级 Kubernetes）：v1.28.2-rc1+k3s1；
   • K3s 自身单独更新（K3s 版本号递增）：从k3s1递增到k3s2，如v1.28.2-rc1+k3s2；
2. 描述（description）留空；
3. 勾选pre-release复选框；
4. 发布（Publish）。

若因依赖变更（如k3s-io/k3s-upgrade仓库的改动）需要新的候选版本，重复上述打标签流程并将 rc 序号递增（rc1 → rc2 …）即可。

关于 tag 目标的补充：tag 应与 release 标题一致，target 指向对应发布分支，最新版本挂在main分支上（参见 docs/release/expanded/cut_release.md）。RC 发布后，还需在发布 Slack 频道中通知新的 RC 已可用。

检查 system-agent-installer-k3s 发布镜像

system-agent-installer-k3s仓库服务于 Rancher 的 v2prov 系统：凡是写入 Rancher KDM 的 K3s 版本（包括 RC 与正式版），都必须在system-agent-installer-k3s中同步发布。因此需要：

• 前往rancher/system-agent-installer-k3s仓库，核对是否已为与版本号对应的新 release 与 tag 创建了记录；
• 在rancher/system-agent-installer-k3s的 Docker Hub tags 页面跟踪构建进度。

若自动化未生效，则按后续"检查发布镜像"一节的说明手动触发。

检查发布镜像（k3s-upgrade）

k3s-upgrade仓库将 K3s 二进制与升级脚本打包成镜像，供用户升级到新的 K3s release。该过程通常自动进行，但自动化失败时需手动介入：

1. 前往k3s-upgrade仓库，为本次发布手动创建一个新 tag（例如v1.28.2-rc1+k3s1），触发镜像构建；
2. Draft 一个新的 release；
3. 输入 tag（如v1.28.2-rc1+k3s1）；
4. 确认k3s 镜像与k3s-upgrade 镜像均已存在。

构建需要一些时间，完成后镜像会出现在各自的 Docker Hub 镜像列表（rancher/k3s与rancher/k3s-upgrade）中。

验证组件发布版本：每次发布，K3s 都会在 release notes 中附带一张"组件及其版本"的表格。发布负责人应据此核对各组件（Kubernetes、containerd、runc、flannel、cri-dockerd 等）的版本是否与本次发布一致。release notes 的具体生成与校验方法可参见 docs/release/expanded/release_notes.md。

更新 Rancher KDM

此步骤专属于 Rancher 生态，目的是更新 Rancher 的Kontainer Driver Metadata（KDM）数据，使 Rancher 能够识别并使用新版本 K3s。

在rancher/kontainer-driver-metadata仓库最新 dev 分支上创建一个 PR，更新channels.yaml中的 Kubernetes 版本。该 PR 应包含两个 commit：

1. 修改channels.yaml以更新 Kubernetes 版本；
2. 运行go generate，提交其产生的data/data.json变更，第二个 commit 标题为"go generate"。

注意事项：

• 若是 Kubernetes 的新 minor 版本，需要在channels.yaml中新建条目，并正确设置min/max版本约束；不确定时应向团队确认（取决于 Rancher 计划支持的范围）；
• 自 v1.21.4 起，每次发布（无论 minor 还是 patch）都要求在channels.yaml中新建条目；新条目可以复用其他条目已定义的 server、agent 与 chart 参数。

例如，v1.21.4定义了如下 server args（本小节示例均取自原文档，版本对应本次发布中的实际 patch 版本）：

- version: v1.21.4+k3s2 minChannelServerVersion: v2.6.0-alpha1 maxChannelServerVersion: v2.6.99 ... serverArgs: &serverArgs-v1 tls-san: type: array

后续版本可以直接通过 YAML 锚点引用这些参数而无需改动：

- version: v1.21.5+k3s1 minChannelServerVersion: v2.6.0-alpha1 maxChannelServerVersion: v2.6.99 serverArgs: *serverArgs-v1

QA 也可能基于 RC 提出 spec 变更请求，此时需按 RC 版本更新约束，例如：

- version: v1.28.2-rc1+k3s1 minChannelServerVersion: v2.8.0-alpha1 maxChannelServerVersion: v2.8.99 serverArgs: *serverArgs-v7

如果不确定新 minor 版本的 min/max 约束，可以向项目经理和/或 QA 确认。

创建 GA 发布候选

QA 验证 RC 可用（或后续 RC 已包含修复）之后，进入正式发布（GA）阶段：

1. 在 GitHub Web 界面创建新 release；
2. 设置 title 为${NEW_K8S}，添加包含 release notes 的描述，tag 部分留空；
3. 勾选pre-release复选框；
4. 先保存为draft，直到 RC 测试完成。

QA 对某个 RC 签署通过后：

1. 设置要创建的 tag——该 tag 需与 draft title 中的版本一致；
2. 确保 prerelease 已勾选；
3. 发布（Publish）；
4. 重复前面的各项检查流程，并用 GA 发布标签更新 KDM 规范；
5. CI 完成、产物已生成后，在 Slack 发布线程中宣布 GA 并告知 K3s 已解除冻结（thawed）；
6. 创建一个 tag 匹配的system-agent-installer-k3srelease。

24 小时之后：

1. 取消 prerelease 勾选并保存；
2. 更新 channel server（见下一节）。

更新 Channel Server

发布被验证后，需要更新 channel server 配置，让stable通道指向新版本。Channel 配置文件位于 K3s 仓库根目录的 channel.yaml，只需单行修改：

# Example channels config channels: - name: stable latest: <new-k8s-version>+k3s1 # Replace this semver with the version corresponding to the release

负责该改动的 Release Captain 需要将上述 stanza 中的latest更新为本次发布对应的新 stable 版本。

以当前仓库 channel.yaml 的实际内容为例，stable通道当前指向v1.36.3+k3s1，同时latest/testing通道通过latestRegexp与excludeRegexp分别匹配最新版与 RC 版本，每个 minor 版本（v1.16至v1.36）均有对应的vX.Y通道。这印证了原文档中"单行修改 stable"的操作边界——升级一个 patch 版本时，通常只需改动stable通道这一行。

源码佐证：版本如何从 go.mod 流转到二进制

上述流程最终服务的，是让 K3s 二进制携带正确的版本号。从源码可以看出版本信息的来源链条：

• scripts/version.sh 通过go list -m从go.mod读取k8s.io/kubernetes的 replace 版本（VERSION_K8S_K3S），并剥离-k3s*后缀得到VERSION_K8S；它还读取 containerd、cri-tools、runc、flannel、cri-dockerd 等组件的版本，用于 release notes 的组件版本表；
• 当存在GIT_TAG（即 tag 构建）时，version.sh会校验 tag 是否匹配^"$VERSION_K8S"[+-]，不匹配则报错退出——这就是"go.mod 必须先行更新、再打 tag"这一顺序的底层原因；
• 最终版本号写入 pkg/version/version.go 的Version变量（未打 tag 时为"dev"），并参与二进制构建。

因此，发布流程中tag.sh → push.sh → go.mod 更新 → go mod tidy → 构建验证的顺序，本质上就是在为这条版本链路准备正确的输入。

收尾：解除冻结与发布公告

完成以上全部流程后，请在发布 Slack 线程中公布：patch release 已全部完成、代码冻结（code freeze）已结束。

至此，一次完整的 K3s Kubernetes 补丁版本发布即告收官：从上游变基打标、主仓库依赖更新、PR 合入，到 RC/GA 发布、Rancher KDM 同步与 Channel Server 切换，所有环节环环相扣。相关命令的完整串联示例可进一步参考 docs/release/expanded/cut_release.md，channel 更新细节见 docs/release/expanded/channel_server.md，整体发布流程可参阅 docs/release/release.md。

【免费下载链接】k3sLightweight Kubernetes项目地址: https://gitcode.com/GitHub_Trending/k3/k3s