为 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.30.0 生成文档，可以使用以下命令

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

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

编辑 kubectl 源代码

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

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

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

将您的更改 cherry-pick 到发布分支

您的更改现在在 master 分支中，该分支用于开发下一个 Kubernetes 版本。如果您想让您的更改出现在已发布的 Kubernetes 版本的文档中，您需要提议将您的更改 cherry-pick 到发布分支。

例如，假设 master 分支正在用于开发 Kubernetes 1.31，而您想将您的更改回滚到 release-1.30 分支。有关如何执行此操作的说明，请参阅 提议 cherry-pick。

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

设置构建变量

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

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

例如

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

创建版本化的目录

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

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

cd <rdocs-base>
make createversiondirs

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

在您本地的 <k8s-base> 存储库中，检出包含您要记录的 Kubernetes 版本的分支。例如，如果您想为 Kubernetes 1.30.0 生成文档，请检出 v1.30 标签。确保您本地的分支是最新的。

cd <k8s-base>
git checkout v1.30.0
git pull https://github.com/kubernetes/kubernetes v1.30.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 生成参考文档