This page shows how to update the generated reference docs for the Kubernetes API. The Kubernetes API reference documentation is built from the Kubernetes OpenAPI spec and tools from kubernetes-incubator/reference-docs.
If you find bugs in the generated documentation, you need to fix them upstream.
If you need only to regenerate the reference documentation from the OpenAPI spec, continue reading this page.
You need to have these tools installed:
You need to know how to create a pull request (PR) to a GitHub repository. Typically, this involves creating a fork of the repository. For more information, see Creating a Documentation Pull Request and GitHub Standard Fork & Pull Request Workflow.
Create a local workspace and set your GOPATH
.
mkdir -p $HOME/<workspace>
export GOPATH=$HOME/<workspace>
Get a local clone of the following repositories:
go get -u github.com/kubernetes-incubator/reference-docs
go get -u github.com/go-openapi/loads
go get -u github.com/go-openapi/spec
If you don’t already have the kubernetes/website repository, get it now:
git clone https://github.com/<your-username>/website $GOPATH/src/github.com/<your-username>/website
Get a clone of the kubernetes/kubernetes repository as k8s.io/kubernetes:
git clone https://github.com/kubernetes/kubernetes $GOPATH/src/k8s.io/kubernetes
The base directory of your clone of the
kubernetes/kubernetes repository is
$GOPATH/src/k8s.io/kubernetes.
The remaining steps refer to your base directory as <k8s-base>
.
The base directory of your clone of the
kubernetes/website repository is
$GOPATH/src/github.com/<your username>/website.
The remaining steps refer to your base directory as <web-base>
.
The base directory of your clone of the
kubernetes-incubator/reference-docs
repository is $GOPATH/src/github.com/kubernetes-incubator/reference-docs.
The remaining steps refer to your base directory as <rdocs-base>
.
This section shows how to generate the published Kubernetes API reference documentation.
Go to <rdocs-base>
, and open the Makefile
for editing:
K8SROOT
to <k8s-base>
.WEBROOT
to <web-base>
.MINOR_VERSION
to the minor version of the docs you want to build. For example,
if you want to build docs for Kubernetes 1.15, set MINOR_VERSION
to 15. Save and close the Makefile
.For example, update the following variables:
WEBROOT=$(GOPATH)/src/github.com/<your-username>/website
K8SROOT=$(GOPATH)/src/k8s.io/kubernetes
MINOR_VERSION=15
Run the following command in <rdocs-base>
:
make updateapispec
The output shows that the file was copied:
cp ~/src/k8s.io/kubernetes/api/openapi-spec/swagger.json gen-apidocs/generators/openapi-spec/swagger.json
Run the following command in <rdocs-base>
:
make api
Verify that these two files have been generated:
[ -e "<rdocs-base>/gen-apidocs/generators/build/index.html" ] && echo "index.html built" || echo "no index.html"
[ -e "<rdocs-base>/gen-apidocs/generators/build/navData.js" ] && echo "navData.js built" || echo "no navData.js"
Create the directories in <web-base>
for the generated API reference files:
mkdir -p <web-base>/static/docs/reference/generated/kubernetes-api/v1.<minor-version>
mkdir -p <web-base>/static/docs/reference/generated/kubernetes-api/v1.<minor-version>/css
mkdir -p <web-base>/static/docs/reference/generated/kubernetes-api/v1.<minor-version>/fonts
Run the following command in <rdocs-base>
to copy the generated files to
your local kubernetes/website repository:
make copyapi
Go to the base of your local kubernetes/website repository, and see which files have been modified:
cd <web-base>
git status
The output shows the modified files:
static/docs/reference/generated/kubernetes-api/v1.15/css/bootstrap.min.css
static/docs/reference/generated/kubernetes-api/v1.15/css/font-awesome.min.css
static/docs/reference/generated/kubernetes-api/v1.15/css/stylesheet.css
static/docs/reference/generated/kubernetes-api/v1.15/fonts/FontAwesome.otf
static/docs/reference/generated/kubernetes-api/v1.15/fonts/fontawesome-webfont.eot
static/docs/reference/generated/kubernetes-api/v1.15/fonts/fontawesome-webfont.svg
static/docs/reference/generated/kubernetes-api/v1.15/fonts/fontawesome-webfont.ttf
static/docs/reference/generated/kubernetes-api/v1.15/fonts/fontawesome-webfont.woff
static/docs/reference/generated/kubernetes-api/v1.15/fonts/fontawesome-webfont.woff2
static/docs/reference/generated/kubernetes-api/v1.15/index.html
static/docs/reference/generated/kubernetes-api/v1.15/jquery.scrollTo.min.js
static/docs/reference/generated/kubernetes-api/v1.15/navData.js
static/docs/reference/generated/kubernetes-api/v1.15/scroll.js
Open <web-base>/content/en/docs/reference/kubernetes-api/index.md
for editing, and update the API reference
version number. For example:
---
title: v1.15
---
[Kubernetes API v1.15](/docs/reference/generated/kubernetes-api/v1.15/)
Open <web-base>/content/en/docs/reference/_index.md
for editing, and add a
new link for the latest API reference. Remove the oldest API reference version.
There should be five links to the most recent API references.
Publish a local version of the API reference. Verify the local preview.
cd <web-base>
make docker-serve
In <web-base>
run git add
and git commit
to commit the change.
Submit your changes as a pull request to the kubernetes/website repository. Monitor your pull request, and respond to reviewer comments as needed. Continue to monitor your pull request until it has been merged.
Was this page helpful?
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.