生成 kubectl 命令的参考文档

此页面显示如何生成 kubectl 命令参考文档。

准备工作

要求

• 您需要一台运行 Linux 或 macOS 的机器。

• 您需要安装以下工具

  • Python v3.7.x+
  • Git
  • Golang 版本 1.13+
  • Pip 用于安装 PyYAML
  • PyYAML v5.1.2
  • make
  • gcc 编译器/链接器
  • Docker (仅限 kubectl 命令参考)

• 您的 PATH 环境变量必须包含必需的构建工具，例如 Go 二进制文件和 python。

• 您需要了解如何向 GitHub 存储库创建拉取请求。这包括创建存储库的个人分支。有关更多信息，请参阅 从本地克隆进行工作。

设置本地仓库

创建本地工作区并设置 GOPATH

mkdir -p $HOME/<workspace>

export GOPATH=$HOME/<workspace>

克隆以下仓库的本地副本

go get -u github.com/spf13/pflag
go get -u github.com/spf13/cobra
go get -u gopkg.in/yaml.v2
go get -u github.com/kubernetes-sigs/reference-docs

如果还没有 kubernetes/website 仓库，请立即获取

git clone https://github.com/<your-username>/website $GOPATH/src/github.com/<your-username>/website

克隆 kubernetes/kubernetes 仓库的本地副本，命名为 k8s.io/kubernetes

git clone https://github.com/kubernetes/kubernetes $GOPATH/src/k8s.io/kubernetes

从 $GOPATH/src/k8s.io/kubernetes/vendor/github.com 中删除 spf13 包

rm -rf $GOPATH/src/k8s.io/kubernetes/vendor/github.com/spf13

kubernetes/kubernetes 仓库提供了 kubectl 和 kustomize 的源代码。

• 确定你的 kubernetes/kubernetes 仓库克隆的根目录。例如，如果你按照前面的步骤获取了仓库，你的根目录就是 $GOPATH/src/k8s.io/kubernetes。其余步骤将你的根目录称为 <k8s-base>。

• 确定你的 kubernetes/website 仓库克隆的根目录。例如，如果你按照前面的步骤获取了仓库，你的根目录就是 $GOPATH/src/github.com/<your-username>/website。其余步骤将你的根目录称为 <web-base>。

• 确定你的 kubernetes-sigs/reference-docs 仓库克隆的根目录。例如，如果你按照前面的步骤获取了仓库，你的根目录就是 $GOPATH/src/github.com/kubernetes-sigs/reference-docs。其余步骤将你的根目录称为 <rdocs-base>。

在你的本地 k8s.io/kubernetes 仓库中，检出你感兴趣的分支，并确保它是最新的。例如，如果你想生成 Kubernetes 1.33.0 的文档，可以使用以下命令

cd <k8s-base>
git checkout v1.33.0
git pull https://github.com/kubernetes/kubernetes 1.33.0

如果你不需要编辑 kubectl 源代码，请按照 设置构建变量 中的说明进行操作。

编辑 kubectl 源代码

kubectl 命令参考文档是根据 kubectl 源代码自动生成的。如果你想更改参考文档，第一步是更改 kubectl 源代码中的一个或多个注释。在你的本地 kubernetes/kubernetes 仓库中进行更改，然后向 github.com/kubernetes/kubernetes 的 master 分支提交一个拉取请求。

PR 56673 是一个修复了 kubectl 源代码中拼写错误的拉取请求示例。

监视你的拉取请求，并回复审稿人的评论。继续监视你的拉取请求，直到它被合并到 kubernetes/kubernetes 仓库的目标分支。

将你的更改挑选到发布分支

你的更改现在已合并到 master 分支，该分支用于开发下一个 Kubernetes 版本。如果你希望你的更改出现在已发布 Kubernetes 版本的文档中，你需要提议将你的更改挑选（cherry-pick）到发布分支。

例如，假设 master 分支正在用于开发 Kubernetes 1.34，而你想将你的更改反向移植到 release-1.33 分支。有关如何执行此操作的说明，请参阅 提议挑选（Cherry Pick）。

监视你的挑选（cherry-pick）拉取请求，直到它被合并到发布分支。

设置构建变量

转到 <rdocs-base> 目录。在命令行中，设置以下环境变量。

• 将 K8S_ROOT 设置为 <k8s-base>。
• 将 K8S_WEBROOT 设置为 <web-base>。
• 将 K8S_RELEASE 设置为你想要构建的文档版本。例如，如果你想构建 Kubernetes 1.33 的文档，请将 K8S_RELEASE 设置为 1.33。

例如

export K8S_WEBROOT=$GOPATH/src/github.com/<your-username>/website
export K8S_ROOT=$GOPATH/src/k8s.io/kubernetes
export K8S_RELEASE=1.33

创建版本化目录

createversiondirs 构建目标会创建一个版本化目录，并将 kubectl 参考配置文件复制到该目录中。版本化目录的名称遵循 v<major>_<minor> 的模式。

在 <rdocs-base> 目录中，运行以下构建目标

cd <rdocs-base>
make createversiondirs

在 k8s.io/kubernetes 中检出发布标签

在你的本地 <k8s-base> 仓库中，检出你想要记录的 Kubernetes 版本的 ist-release 分支。例如，如果你想生成 Kubernetes 1.33.0 的文档，请检出 v1.33 标签。确保你的本地分支是最新的。

cd <k8s-base>
git checkout v1.33.0
git pull https://github.com/kubernetes/kubernetes v1.33.0

运行文档生成代码

在你的本地 <rdocs-base> 目录中，运行 copycli 构建目标。命令以 root 用户身份运行

cd <rdocs-base>
make copycli

copycli 命令会清理临时构建目录，生成 kubectl 命令文件，并将汇总的 kubectl 命令参考 HTML 页面和资源复制到 <web-base> 目录。

查找生成的文件

验证这两个文件已生成

[ -e "<rdocs-base>/gen-kubectldocs/generators/build/index.html" ] && echo "index.html built" || echo "no index.html"
[ -e "<rdocs-base>/gen-kubectldocs/generators/build/navData.js" ] && echo "navData.js built" || echo "no navData.js"

查找复制的文件

验证所有生成的文件是否已复制到你的 <web-base> 目录

cd <web-base>
git status

输出应包含已修改的文件

static/docs/reference/generated/kubectl/kubectl-commands.html
static/docs/reference/generated/kubectl/navData.js

输出可能还包括

static/docs/reference/generated/kubectl/scroll.js
static/docs/reference/generated/kubectl/stylesheet.css
static/docs/reference/generated/kubectl/tabvisibility.js
static/docs/reference/generated/kubectl/node_modules/bootstrap/dist/css/bootstrap.min.css
static/docs/reference/generated/kubectl/node_modules/highlight.js/styles/default.css
static/docs/reference/generated/kubectl/node_modules/jquery.scrollto/jquery.scrollTo.min.js
static/docs/reference/generated/kubectl/node_modules/jquery/dist/jquery.min.js
static/docs/reference/generated/kubectl/node_modules/font-awesome/css/font-awesome.min.css

本地测试文档

在你的本地 <web-base> 目录中构建 Kubernetes 文档。

cd <web-base>
git submodule update --init --recursive --depth 1 # if not already done
make container-serve

查看 本地预览。

在 kubernetes/website 中添加和提交更改

运行 git add 和 git commit 来提交文件。

创建拉取请求

向 kubernetes/website 仓库创建拉取请求。监视你的拉取请求，并根据需要回复审阅评论。继续监视你的拉取请求，直到它被合并。

在你的拉取请求合并几分钟后，你更新的参考主题将显示在 已发布的文档 中。

下一步

• 生成参考文档快速入门
• 生成 Kubernetes 组件和工具的参考文档
• 生成 Kubernetes API 的参考文档