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

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

如果你不需要编辑 kubectl 源代码，请遵循 设置构建变量 的说明。

编辑 kubectl 源代码

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

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

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

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

你的更改现在在主分支中，该分支用于开发下一个 Kubernetes 版本。如果你希望你的更改出现在已经发布的 Kubernetes 版本的文档中，你需要提出将你的更改 cherry-pick 到发布分支的请求。

例如，假设主分支正在用于开发 Kubernetes 1.35，而你想将你的更改回溯到 release-1.34 分支。有关如何执行此操作的说明，请参阅 提出 Cherry Pick。

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

设置构建变量

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

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

例如

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

创建版本化目录

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

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

cd <rdocs-base>
make createversiondirs

签出 k8s.io/kubernetes 中的发布标签

在你的本地 <k8s-base> 仓库中，签出包含你想要记录的 Kubernetes 版本的分支。例如，如果你想为 Kubernetes 1.34.0 生成文档，签出 v1.34 标签。确保你的本地分支是最新的。

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