生成 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 仓库创建 Pull Request。这包括创建你自己的仓库派生 (Fork)。有关更多信息，请参阅 从本地克隆仓库开始。

设置本地仓库

创建本地工作空间并设置你的 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.32.0 生成文档，可以使用以下命令

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

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

编辑 kubectl 源代码

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

PR 56673 是一个修复 kubectl 源代码中拼写错误的 Pull Request 示例。

监控你的 Pull Request，并回复评审者的意见。持续监控你的 Pull Request，直到它合并到 kubernetes/kubernetes 仓库的目标分支。

将你的更改 Cherry Pick 到发布分支

你的更改现在已合并到 master 分支，该分支用于开发下一个 Kubernetes 版本。如果你想让你的更改出现在已发布的 Kubernetes 版本的文档中，你需要提议将你的更改 Cherry Pick (拣选) 到发布分支。

例如，假设 master 分支用于开发 Kubernetes 1.33，并且你想将你的更改回溯 (Backport) 到 release-1.32 分支。有关如何执行此操作的说明，请参阅 提议 Cherry Pick。

监控你的 Cherry Pick Pull Request，直到它合并到发布分支。

设置构建变量

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

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

例如

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

创建版本化目录

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

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

cd <rdocs-base>
make createversiondirs

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

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

cd <k8s-base>
git checkout v1.32.0
git pull https://github.com/kubernetes/kubernetes v1.32.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 提交文件。

创建 Pull Request

向 kubernetes/website 仓库创建 Pull Request。监控你的 Pull Request，并根据需要回复评审意见。持续监控你的 Pull Request，直到它合并。

你的 Pull Request 合并几分钟后，你更新的参考主题将在已发布的文档中可见。

下一步

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