大网数据广告活动
Kubernetes 部署与运维

为 Kubernetes API 生成参考文档

· 52CE 我爱测

Kubernetes API 参考文档是从 Kubernetes OpenAPI 规范构建的, 且使用 kubernetes-sigs/reference-docs 生成代码。

本页面显示了如何更新 Kubernetes API 参考文档。

Kubernetes API 参考文档是从 Kubernetes OpenAPI 规范构建的, 且使用 kubernetes-sigs/reference-docs 生成代码。

如果你在生成的文档中发现错误,则需要在上游修复。

如果你只需要从 OpenAPI 规范中重新生成参考文档,请继续阅读此页。

配置本地仓库

创建本地工作区并设置你的 GOPATH:

mkdir -p $HOME/<workspace>
export GOPATH=$HOME/<workspace>

获取以下仓库的本地克隆:

git clone github.com/kubernetes-sigs/reference-docs

将其移动到 reference-docs 仓库的 gen-apidocs 目录中, 并安装所需的 Go 包:

go get -u github.com/go-openapi/loads
go get -u github.com/go-openapi/spec

如果你还没有下载过 kubernetes/website 仓库,现在下载:

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

克隆 kubernetes/kubernetes 仓库:

git clone https://github.com/kubernetes/kubernetes
  • kubernetes/kubernetes 仓库克隆后的根目录为 <your-path-to>/src/k8s.io/kubernetes。 后续步骤将此目录称为 <k8s-base>。

  • kubernetes/website 仓库克隆后的根目录为 <your-path-to>/src/github.com/<your username>/website。后续步骤将此目录称为 <web-base>。

  • kubernetes-sigs/reference-docs 仓库克隆后的基本目录为 <your-path-to>/src/github.com/kubernetes-sigs/reference-docs。 后续步骤将此目录称为 <rdocs-base>。

生成 API 参考文档

本节说明如何生成已发布的 Kubernetes API 参考文档。

设置构建变量 {#set-build-variables}

进入 <rdocs-base> 目录,然后打开 Makefile 文件进行编辑:

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

例如:

export K8S_WEBROOT=<your-path-to>/website
export K8S_ROOT=<your-path-to>/kubernetes
export K8S_RELEASE=1.17.0

创建版本目录并复制 OpenAPI 规范

构建目标 updateapispec 负责创建版本化的构建目录。 目录创建了之后,从 <k8s-base> 仓库取回 OpenAPI 规范文件。 这些步骤确保配置文件的版本和 Kubernetes OpenAPI 规范的版本与发行版本匹配。 版本化目录的名称形式为 v<major>_<minor>。

在 <rdocs-base> 目录中,运行以下命令来构建:

cd <rdocs-base>
make updateapispec

构建 API 参考文档

构建目标 copyapi 会生成 API 参考文档并将所生成文件复制到 <web-base 中的目录下。在 <rdocs-base> 目录中运行以下命令:

cd <rdocs-base>
make copyapi

验证是否已生成这两个文件:

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

进入本地 <web-base> 目录,检查哪些文件被更改:

cd <web-base>
git status

输出类似于:

static/docs/reference/generated/kubernetes-api//css/bootstrap.min.css
static/docs/reference/generated/kubernetes-api//css/font-awesome.min.css
static/docs/reference/generated/kubernetes-api//css/stylesheet.css
static/docs/reference/generated/kubernetes-api//fonts/FontAwesome.otf
static/docs/reference/generated/kubernetes-api//fonts/fontawesome-webfont.eot
static/docs/reference/generated/kubernetes-api//fonts/fontawesome-webfont.svg
static/docs/reference/generated/kubernetes-api//fonts/fontawesome-webfont.ttf
static/docs/reference/generated/kubernetes-api//fonts/fontawesome-webfont.woff
static/docs/reference/generated/kubernetes-api//fonts/fontawesome-webfont.woff2
static/docs/reference/generated/kubernetes-api//index.html
static/docs/reference/generated/kubernetes-api//js/jquery.scrollTo.min.js
static/docs/reference/generated/kubernetes-api//js/navData.js
static/docs/reference/generated/kubernetes-api//js/scroll.js

API 参考位置和版本控制

生成的 API 参考文件(HTML 版本)被复制到 <web-base>/static/docs/reference/generated/kubernetes-api//。 此目录包含了独立的 HTML API 文档。

API 参考的 Markdown 版本位于 <web-base>/content/en/docs/reference/kubernetes-api/, 是使用 gen-resourcesdocs 生成器单独生成的。

在本地测试 API 参考

发布 API 参考的本地版本。 检查本地预览。

cd <web-base>
git submodule update --init --recursive --depth 1 # 如果尚未完成
make container-serve

提交更改

在 <web-base> 中运行 git add 和 git commit 来提交更改。

基于你所生成的更改创建 PR, 提交到 kubernetes/website 仓库。 监视你提交的 PR,并根据需要回复 reviewer 的评论。继续监视你的 PR,直到合并为止。

来源:Kubernetes 文档贡献者 · 作者与贡献记录 · CC BY 4.0。离线整理了版式、链接和媒体显示。

资料来源与适用范围

资料来源
Kubernetes 文档贡献者
适用范围
请按文中版本与环境说明核对
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-15
授权说明
CC BY 4.0

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。