为 kubectl 命令生成参考文档

本页面介绍如何生成 `kubectl` 命令参考。

准备工作

要求

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

• 您需要安装以下工具

  • Python v3.7.x+ 版本
  • Git
  • Golang 1.13+ 版本
  • 用于安装 PyYAML 的 Pip
  • 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.31.0 生成文档，您可以使用以下命令

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

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

编辑 kubectl 源代码

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

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

监控您的拉取请求，并回复审阅者的评论。继续监控您的拉取请求，直到它合并到 kubernetes/kubernetes 仓库的目标分支中。

将您的更改遴选到发布分支中

您的更改现在位于 master 分支中，该分支用于开发下一个 Kubernetes 版本。如果您希望您的更改出现在已发布的 Kubernetes 版本的文档中，您需要建议将您的更改遴选到发布分支中。

例如，假设 master 分支正用于开发 Kubernetes 1.32，并且您希望将您的更改反向移植到 release-1.31 分支。有关如何执行此操作的说明，请参阅 建议遴选。

监控您的遴选拉取请求，直到它合并到发布分支中。

设置构建变量

转到 `<rdocs-base>`。在您的命令行上，设置以下环境变量。

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

例如

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

创建版本化目录

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

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

cd <rdocs-base>
make createversiondirs

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

在您本地的 `<k8s-base>` 仓库中，检出具有您要记录的 Kubernetes 版本的分支。例如，如果您想为 Kubernetes 1.31.0 生成文档，请检出 `v1.31` 标签。确保您的本地分支是最新的。

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

运行文档生成代码

在您本地的 `<rdocs-base>` 中，以 `root` 身份运行 `copycli` 构建目标。

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 生成参考文档