K3s 发布工程实战在 Go 工作区中搭建 Kubernetes 双远程仓库环境setup_k8s_repos 完整指南【免费下载链接】k3sLightweight Kubernetes项目地址: https://gitcode.com/GitHub_Trending/k3/k3s导读K3s 的发布流程依赖一个特殊的代码仓库布局在本地 Go 工作区GOPATH中同时挂载 Kubernetes 官方仓库kubernetes/kubernetes与 K3s 团队维护的分支仓库k3s-io/kubernetes并借助 Git 多远程multi-remote机制完成标签tag与提交的合并、变基与推送。本文以 docs/release/expanded/setup_k8s_repos.md 为骨架结合仓库内的 setup_env.md、rebase.md、cut_release.md 等发布文档以及当前仓库 go.mod 中的 replace 指令证据完整讲解这套环境的前置条件、搭建步骤、底层原理与后续用法。读完本文你将掌握 K3s 发布维护者是如何组织本地 Kubernetes 源码树并为后续的变基打标签、生成 K3s 升级 PR 等操作奠定基础的。一、为什么需要这套特殊目录结构Go 模块解析与目录强绑定1.1 Go 对目录结构的洁癖来自哪里原文档强调了一个核心原因Go is very particular about the file structure (it uses the file structure to infer the urls it will pull dependencies from).在 Go Modules 时代虽然模块导入路径import path主要由go.mod中的module与replace指令决定但当你在GOPATH模式下工作、或直接以源码目录形式参与多模块multi-module协作时$GOPATH/src/host/owner/repo的目录布局仍然被大量工具、脚本和 CI 硬编码依赖。K3s 的发布工具链正是这样一套高度依赖目录结构的流程tag.sh脚本运行在容器内的固定工作目录/go/src/github.com/kubernetes/kubernetes见 tagging.md 中的 docker run 示例本地 git 命令、变基操作也都发生在$HOME/go/src/github.com/kubernetes/kubernetes这个路径下。因此目录名必须与仓库名完全一致仓库目录是kubernetes不能是k3s或其他名字否则 Go 与脚本都无法据此推断出正确的依赖来源 URL。1.2 从 go.mod 看 k3s-io/kubernetes 的实际地位在当前仓库的 go.mod 中可以看到K3s 对 Kubernetes 官方模块做了全面替换replace指向k3s-io/kubernetes维护的分支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/kubernetes github.com/k3s-io/kubernetes v1.36.3-k3s1也就是说K3s 二进制实际链接的是k3s-io/kubernetes仓库在对应vX.Y.Z-k3s1标签上发布的模块包括从staging/src/k8s.io/*导出的组件模块。发布维护者每次升级 Kubernetes 版本本质上就是要让k3s-io/kubernetes这个分支仓库追上上游 Kubernetes 的新版本并在其基础上叠加 K3s 专属的定制提交。这也是setup_k8s_repos要同时拉取两个远程仓库的根本原因。二、搭建 Kubernetes 双远程仓库setup_k8s_repos 完整步骤原文档给出了 5 个步骤下面将其展开为可直接执行的命令并逐条解释。2.1 步骤一确保目录存在install -d $HOME/go/src/github.com/kubernetesinstall -d等价于mkdir -p可一次性创建多级目录。这个路径必须完整匹配github.com/kubernetes因为本地副本将代表 GitHub 上kubernetes/kubernetes这个仓库详见环境准备文档 setup_env.md其中要求预先创建github.com/your user、github.com/k3s-io、github.com/rancher、github.com/rancherlabs、github.com/kubernetes等目录并设置GOPATH$HOME/go。2.2 步骤二清理旧副本rm -rf $HOME/go/src/github.com/kubernetes/kubernetes原文档的解释是clear out (remove) kubernetes repo if is already there (just makes things smoother with a new clone)——删除旧副本只是为了让全新的克隆更顺畅。这是因为旧副本可能包含未同步的远程引用、残留的本地分支或中断的变基状态重新克隆能避免这些历史包袱。2.3 步骤三以 upstream 为远程名克隆官方仓库git clone --origin upstream https://github.com/kubernetes/kubernetes.git $HOME/go/src/github.com/kubernetes/kubernetes关键点在于--origin upstreamGit 默认的远程名是origin但这里刻意命名为upstream。在 K3s 的仓库命名惯例中upstream 原始/上游仓库这里是 Kubernetes 官方仓库或对 k3s 仓库而言是 k3s-io/k3sorigin 发布维护者自己的 fork个人私有仓库。这一点在 cut_release.md 的命令清单中有直接体现git clone --origin upstream https://github.com/kubernetes/kubernetes.git /Users/mtrachier/go/src/github.com/kubernetes/kubernetes cd /Users/mtrachier/go/src/github.com/kubernetes/kubernetes git remote add k3s-io https://github.com/k3s-io/kubernetes.git git fetch --all --tags2.4 步骤四添加 k3s-io/kubernetes 为第二个远程cd $HOME/go/src/github.com/kubernetes/kubernetes git remote add k3s-io https://github.com/k3s-io/kubernetes.git这样本地副本就有了两个远程upstream官方与k3s-ioK3s 维护的分支。K3s 的定制提交custom/proprietary commits只存在于k3s-io远程中而官方的新提交只存在于upstream中详见 rebase.md。2.5 步骤五拉取两个远程的全部对象git fetch --all --tagsgit fetch --all会拉取所有已配置远程upstream 与 k3s-io的全部引用--tags额外拉取所有标签。原文档特别强调这一步很重要并给出一个实战技巧来自 cut_release.mdthis second fetch should return no more tags pulled, this makes it easier to see pull errors即建议连续执行两次git fetch --all --tags第二次应返回没有新标签的结果这样如果某个标签拉取失败就能第一时间被发现。三、搭建完成后的目录布局总览按照上述步骤最终本地会形成如下结构以原文档中的示例路径为准$HOME/go/src/github.com/kubernetes/kubernetes ├── (upstream 远程) → https://github.com/kubernetes/kubernetes.git ├── (k3s-io 远程) → https://github.com/k3s-io/kubernetes.git ├── .git/ │ └── refs/ │ ├── remotes/upstream/ ← 官方分支与标签 │ └── remotes/k3s-io/ ← K3s 定制提交与 k3s 标签该副本同时拥有两个远程的所有分支和所有标签这正是后续git rebase --onto变基操作的前提本地副本成为官方提交与 K3s 定制提交的汇合点详见 rebase.md。四、这套环境在发布流程中的位置与后续用法4.1 在完整发布流程中的位置从 docs/release/release.md 可以看到setup_k8s_repos位于整个发布流程的第二步紧接在 setup_env.md环境准备与 setup_rc.md环境变量设置之后生成 K3s-IO/Kubernetes 分支的新标签setup_k8s_repos→rebase→build_container→tagging更新 K3ssetup_k3s_repossetup_k3s_repos.md为 k3s 仓库本身建立同样的 upstream/origin 双远程→ 生成升级 PRpr.md发布 RC/GA、更新 KDM、检查镜像、生成发布说明。也就是说setup_k8s_repos是给 k3s-io/kubernetes 分支打新标签这一系列操作的入口环境。4.2 后续怎么用rebase、tag.sh 与 push环境就绪后下一个动作是在此副本上执行变基rebase.mdgit rebase --onto $NEW_K8S $OLD_K8S $OLD_K3S_VER~1含义把 K3s 的定制提交从旧的 Kubernetes 版本之上搬运到新的 Kubernetes 版本之上。变基后本地副本处于 detached HEAD 状态这是正常的。随后在构建容器中运行tag.sh生成大量标签tagging.mddocker run --rm -u $(id -u) \ --mount typetmpfs,destination${GOPATH}/pkg \ -v ${GOPATH}/src:/go/src \ -v ${GOPATH}/.cache:/go/.cache \ -v ${GLOBAL_GIT_CONFIG_PATH}:/go/.gitconfig \ -v ${HOME}/.gnupg:/go/.gnupg \ -e HOME/go -e GOCACHE/go/.cache \ -w /go/src/github.com/kubernetes/kubernetes \ ${GOIMAGE}-dev ./tag.sh ${NEW_K3S_VER} 21 | tee tags-${NEW_K3S_VER}.log注意工作目录正是/go/src/github.com/kubernetes/kubernetes——再次印证了目录结构必须严格匹配。tag.sh脚本只存在于 k3s-io 远程的提交中这也是必须同时拉取k3s-io远程的原因。最后将tag.sh输出的 git push 命令整理成脚本设置export REMOTEk3s-io后执行把标签推送到 k3s-io/kubernetes 仓库。4.3 为什么要 clone 而不是直接复用现成仓库原文档与 setup_k3s_repos.md 对 k3s 仓库给出了完全对称的步骤确保$HOME/go/src/github.com/k3s-io存在 → 清理旧 k3s → 以upstream克隆 k3s-io/k3s → fork 并添加为origin→ fetch 全部。之所以坚持全新克隆 双远程 fetch是为了保证本地副本包含所有远程的全量对象变基与打标签不受缺对象影响第二次 fetch 无新内容时可以立即发现拉取错误避免旧状态如未完成的 rebase、孤儿提交干扰发布操作。五、常见问题与注意事项目录名不能改仓库目录必须叫kubernetes路径$HOME/go/src/github.com/kubernetes/kubernetes因为脚本硬编码了该路径如tag.sh的运行目录、-w /go/src/github.com/kubernetes/kubernetes。两次 fetch 的验证技巧git fetch --all --tags连续执行两次第二次应无新标签输出用于暴露拉取错误出自 cut_release.md。平台差异原文档的命令示例以 macOS 为主如/Users/mtrachier/go在 Linux 上替换为$HOME/go即可后续 PR 修改 go.mod 时sed -i的参数在 macOSsed -Ei 与 Linuxsed -Ei上不同详见 pr.md。内存压力发布流程中的tag.sh会构建大量二进制并产生大量文件变动pr.md 中记录了一个实战经验在 Mac 上运行tag.sh后内存占用飙升、系统变慢作者通过重启解决。六、小结setup_k8s_repos是 K3s 发布工程中看似简单却至关重要的第一步它建立了本地 Go 工作区中同时容纳 kubernetes 官方仓库与 k3s-io 分支仓库的双远程环境让后续的git rebase --onto变基、容器内tag.sh打标签、向k3s-io远程推送标签成为可能。这套约定源于 Go 工具链对$GOPATH/src目录结构的依赖也体现在 go.mod 中大量k8s.io/* github.com/k3s-io/kubernetes/...的 replace 指令里。掌握这套环境搭建是理解 K3s 如何将上游 Kubernetes 与自身定制代码融合发布的第一步也是阅读 docs/release/release.md 其余发布步骤rebase、tagging、cut release、update KDM的前提。【免费下载链接】k3sLightweight Kubernetes项目地址: https://gitcode.com/GitHub_Trending/k3/k3s创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考