本页面展示了如何为 Kubernetes API 更新自动生成的参考文档。
你需要安装以下软件:
在环境变量中设置 $GOPATH,并且 etcd 的路径必须配置在 $PATH 环境变量中。
你需要知道如何在一个 GitHub 项目仓库中创建一个 PR。一般来说,这涉及到创建仓库的一个分支。想了解更多信息,请参见创建一个文档 PR 和 GitHub 标准 Fork&PR 工作流。
更新 Kubernetes API 参考文档有两个步骤:
If you don’t already have the kubernetes/kubernetes repository, get it now:
mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes/kubernetes
确定 kubernetes/kubernetes 仓库的本地主目录。例如,如果按照前面的步骤来获取该仓库,则主目录是 $GOPATH/src/github.com/kubernetes/kubernetes
。下文将该目录称为 <k8s-base>
。
如果你还没有下载过 kubernetes/website
仓库,现在下载:
mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes/website
确定 kubernetes/website 仓库的本地主目录。例如,如果按照前面的步骤来获取该仓库,则主目录是 $GOPATH/src/github.com/kubernetes/website
。下文将该目录称为 <web-base>
。
如果你还没有下载过 kubernetes-incubator/reference-docs 仓库,现在下载:
mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes-incubator/reference-docs
确定 kubernetes-incubator/reference-docs 仓库的本地主目录。例如,如果按照前面的步骤来获取该仓库,则主目录是 $GOPATH/src/github.com/kubernetes-incubator/reference-docs
。下文将该目录称为 <rdocs-base>
。
Kubernetes API 参考文档是基于 OpenAPI 规范自动生成的,而该规范是从 Kubernetes 源码生成的。如果想要修改参考文档,可以从修改 Kubernetes 源码中的一个或多个注释开始。
Note:以下步骤是一个示例,而不是通用步骤。在你操作过程中,细节会有所不同。
下面是在 Kubernetes 源码中编辑注释的示例。
进入 kubernetes/kubernetes 仓库的本地目录,检出 master 分支,并确保它是最新的:
cd <k8s-base>
git checkout master
git pull https://github.com/kubernetes/kubernetes master
假设 master 分支中的这个源文件有一个拼写错误 “atmost”:
kubernetes/kubernetes/staging/src/k8s.io/api/apps/v1/types.go
在本地环境中,打开 types.go
文件,然后将 “atmost” 修改为 “at most”。
确认文件已修改:
git status
输出展示了在 master 分支上,types.go
文件已被修改:
On branch master
...
modified: staging/src/k8s.io/api/apps/v1/types.go
运行 git add
和 git commit
提交到目前为止所做的修改。在下一步中,你将进行第二次提交。将修改拆分为两个提交是很重要的。
进入 <k8s-base>
目录运行以下脚本:
hack/update-generated-swagger-docs.sh
hack/update-swagger-spec.sh
hack/update-openapi-spec.sh
hack/update-generated-protobuf.sh
hack/update-api-reference-docs.sh
运行 git status
查看生成的文件。
On branch master
...
modified: api/openapi-spec/swagger.json
modified: api/swagger-spec/apps_v1.json
modified: docs/api-reference/apps/v1/definitions.html
modified: staging/src/k8s.io/api/apps/v1/generated.proto
modified: staging/src/k8s.io/api/apps/v1/types.go
modified: staging/src/k8s.io/api/apps/v1/types_swagger_doc_generated.go
检查 api/openapi-spec/swagger.json
的内容确认拼写错误是否被修复。例如,你可以运行 git diff -a api/openapi-spec/swagger.json
。这个步骤很重要,因为 swagger.json
是文档生成过程的第二个步骤的输入。
运行 git add
和 git commit
提交修改。现在你有两个提交:一个是已编辑的 types.go
文件,另一个是已生成的 OpenAPI 规范和相关文件。把这两个提交分开。也就是说,不要将它们合并提交。
将你的修改以 pull request 提交到 kubernetes/kubernetes 仓库的 master 分支。跟踪你的 PR,并根据需要回应评审人的评论。继续跟踪你的 PR,直到它被合入。
PR 57758 是一个对 Kubernetes 源码中的拼写错误进行修复的 PR 示例。
Note:定位要修改的具体源文件可能很困难。在前面的示例中,正确的源文件位于
kubernetes/kubernetes
仓库的staging
目录下。但在你的情况下,staging
目录可能不是查找正确源的位置。有关指导,请查看 kubernetes/kubernetes 仓库的README
文件和相关仓库 kubernetes/apiserver。
在上文中,你在 master 分支中编辑了一个文件,然后运行脚本来生成 OpenAPI 规范和相关文件。然后你在一个 PR 中向 kubernetes/kubernetes 仓库的 master 分支提交了修改。现在假设你想要将你的修改合入到一个发布分支中。例如,假设 master 分支用于开发 Kubernetes 1.10 版本,而你希望将你的修改合入到 release-1.9 分支中。
回想一下 PR 中有两个提交:一个用于编辑 types.go
,另一个用于脚本生成的文件。下一步是对你在 release-1.9 分支的第一次提交提议一个 cherry-pick 合入。其目的是挑出对 types.go
的编辑的那次提交,而不是对运行脚本结果的提交。有关说明,请参见提议一个 cherry-pick 合入。
Note:提议一个 cherry-pick 合入,需要你有在 PR 中设置标签和里程碑的权限。如果你没有,你需要与有权限为你设置标签和里程碑的人合作完成。
当你有一个对 release-1.9 分支进行 cherry-pick 合入的 PR 时,下一步是在 release-1.9 分支的本地环境中运行这些脚本。
hack/update-generated-swagger-docs.sh
hack/update-swagger-spec.sh
hack/update-openapi-spec.sh
hack/update-generated-protobuf.sh
hack/update-api-reference-docs.sh
现在向 cherry pick 的 PR 添加一个提交,该 PR 包含最近生成的 OpenAPI 规范和相关文件。跟踪你的 PR,直到它合入到 release-1.9 分支中。
此时,master 和 release-1.9 分支都更新了 types.go
文件和一组生成的文件,这些反映了你对 types.go
做的修改。注意,在 release-1.9 分支中生成的 OpenAPI 规范和其他文件不一定与在 master 分支中生成的文件相同。在 release-1.9 分支中生成的文件只包含 Kubernetes 1.9 版本的 API 元素。master 分支中生成的文件可能包含正在 1.10 版本中开发的 API 元素,而这些元素却不在 1.9 版本中。
前一章节展示了如何编辑源文件,然后生成几个文件,包括 kubernetes/kubernetes
仓库中的 api/openapi-spec/swagger.json
。
本章节介绍如何生成已发布的 Kubernetes API 参考文档,该文档由 kubernetes-incubator/reference-docs 中的工具生成。这些工具以 api/openapi-spec/swagger.json
文件作为输入。
进入 <rdocs-base>
目录, 打开 Makefile
进行编辑:
将 K8SROOT
设置为 kubernetes/kubernetes 仓库的本地主目录。将 WEBROOT
设置为 kubernetes/website 仓库的本地主目录。将 MINOR_VERSION
设置为要构建的文档的副版本号。例如,如果要为 Kubernetes 1.9 版本构建文档,请将 MINOR_VERSION
设置为 9。保存并关闭 Makefile
。
文档生成代码需要 Kubernetes API 的 OpenAPI 规范的本地副本。进入 <k8s-base>
目录,检出有你想要使用的 OpenAPI 规范的分支。例如,如果要为 Kubernetes 1.9 版本生成文档,请检出 release-1.9 分支。
返回 <rdocs-base>
目录。输入以下命令将 OpenAPI 规范从 kubernetes/kubernetes
仓库复制到本地目录:
make updateapispec
输出显示文件已被复制:
cp ~/src/github.com/kubernetes/kubernetes/api/openapi-spec/swagger.json gen-apidocs/generators/openapi-spec/swagger.json
文档生成代码需要 pwittrock/brodocs Docker 镜像。
该命令用于创建 pwittrock/brodocs
Docker 镜像。它还尝试将镜像推送到 DockerHub,但是如果该步骤失败也没关系。只要镜像在本地,就可以成功生成代码。
make brodocs
确认 brodocs 镜像是否存在:
docker images
输出显示 pwittrock/brodocs
是可用镜像之一:
REPOSITORY TAG IMAGE ID CREATED SIZE
pwittrock/brodocs latest 999d34a50d56 5 weeks ago 714MB
构建并运行文档生成代码。你可能需要以 root 用户运行命令:
cd <rdocs-base>
make api
这两个文件是成功构建的产物。验证它们是否存在:
<rdocs-base>/gen-apidocs/generators/build/index.html
<rdocs-base>/gen-apidocs/generators/build/navData.js
前面的章节展示了如何编辑 Kubernetes 源文件,生成 OpenAPI 规范,然后生成用于发布的参考文档。
本章节介绍如何将生成的文档复制到 kubernetes/website 仓库。kubernetes/website
仓库中的文件发布在 kubernetes.io 网站上。特别是,生成的 index.html
文件发布在这里。
输入以下命令将生成的文件复制到 kubernetes/website 仓库的本地目录:
make copyapi
进入 kubernetes/kubernetes 仓库的本地主目录,查看哪些文件已被修改:
cd <web-base>
git status
输出显示修改后的文件:
On branch master
...
modified: docs/reference/generated/kubernetes-api/v1.9/index.html
在本例中,只修改了一个文件。回想一下,你生成了 index.html
和 navData.js
。但显然生成的 navata.js
与 kubernetes/website仓库中已有的
navData.js` 没有什么不同。
在 <web base>
目录下运行 git add
和 git commit
将提交修改。
将你的修改作为 pull request 提交到 kubernetes/website 仓库。跟踪你的 PR,并根据需要回应评审人的评论。继续跟踪你的 PR,直到它被合入。
在 PR 合入的几分钟后,你的修改将出现在已发布的参考文档。
此页是否对您有帮助?
Thanks for the feedback. If you have a specific, answerable question about how to use Kubernetes, ask it on Stack Overflow. Open an issue in the GitHub repo if you want to report a problem or suggest an improvement.