This page explains how you can generate an updated version of the Kubernetes API reference documentation. It is aimed at people who are contributing to Kubernetes.
The kubernetes-sigs/reference-docs
gen-apidocs generator builds the API reference from the
Kubernetes OpenAPI spec.
If you find bugs in the generated content, you most likely need to fix them upstream.
You need a machine that is running Linux or macOS.
You need to have these tools installed:
Your PATH environment variable must include the required build tools, such as the Go binary and python.
You need to know how to create a pull request to a GitHub repository. This involves creating your own fork of the repository. For more information, see Work from a local clone.
You need local clones of kubernetes/website and kubernetes-sigs/reference-docs.
You do not need a local kubernetes/kubernetes checkout — the spec-preparation
step fetches it for you.
If you have not already forked and cloned kubernetes/website, see
Work from a local clone.
Clone reference-docs:
git clone https://github.com/kubernetes-sigs/reference-docs
The remaining steps refer to your kubernetes/website clone as <web-base> and
your reference-docs clone as <rdocs-base>.
Set these in your shell. They apply to every make command in the steps that
follow, whichever directory you run it from.
export K8S_WEBROOT=/path/to/your/website # your website clone (<web-base>)
export K8S_RELEASE=1.36.0 # the release you want to build
The swagger.json checked into kubernetes/kubernetes is missing many enum
values that the reference needs. The updateapispec-enums-from-source target
regenerates an enum-complete spec: it shallow-clones the release tag into a
temporary directory, enables enum generation, verifies the result, and removes
the checkout — so you never maintain a local kubernetes/kubernetes clone.
From <rdocs-base> (your reference-docs clone):
cd <rdocs-base>
make updateapispec-enums-from-source
kubernetes/kubernetes uses (for example, etcd). Set KEEP_TMP=1 to keep the
temporary checkout for debugging.gen-apidocs auto-detects API groups and versions from swagger.json, so there
is no per-release config.yaml to edit. From <rdocs-base>, build the backend
you need and copy it into <web-base>:
cd <rdocs-base>
make copyapimd # Hugo-native Markdown -> <web-base>/content/en/docs/reference/kubernetes-api/
make copyapi # single-page HTML -> <web-base>/static/docs/reference/generated/kubernetes-api/<version>/
The first make run downloads the Go module dependencies, which can take a few
minutes.
gen-apidocs produces both backends. The older gen-resourcesdocs generator,
which once produced the Markdown reference, is deprecated. However, you may
see pages that mention gen-resourcesdocs because those guides are not yet
updated.
Check what changed in your website clone:
cd <web-base>
git status
Preview your changes:
cd <web-base>
git submodule update --init --recursive --depth 1 # if not already done
make container-serve
Using a web browser, open the local preview of the Kubernetes website, and check the pages you updated. Hugo serves that local preview at http://localhost:1313/ so the page to check is: http://localhost:1313/docs/reference/kubernetes-api/
In <web-base>, run git add and git commit, then open a
pull request to
kubernetes/website. Monitor the pull
request and respond to review comments until it is merged.