Generating Reference Documentation for the Kubernetes API

    The Kubernetes API reference documentation is built from the Kubernetes OpenAPI spec using the generation code.

    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 spec, continue reading this page.

    • You need a machine that is running Linux or macOS.

    • You need to have these tools installed:

    • 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.

    Setting up the local repositories

    Create a local workspace and set your GOPATH.

    1. go get -u github.com/kubernetes-sigs/reference-docs
    3. go get -u github.com/go-openapi/loads
    4. go get -u github.com/go-openapi/spec

    If you don’t already have the kubernetes/website repository, get it now:

    1. 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:

    1. 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 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-sigs/reference-docs repository is $GOPATH/src/github.com/kubernetes-sigs/reference-docs. The remaining steps refer to your base directory as <rdocs-base>.

    This section shows how to generate the .

    • Set K8S_ROOT to <k8s-base>.
    • Set K8S_WEBROOT to <web-base>.
    • Set to the version of the docs you want to build. For example, if you want to build docs for Kubernetes 1.17.0, set K8S_RELEASE to 1.17.0.

    For example:

    The updateapispec build target creates the versioned build directory. After the directory is created, the Open API spec is fetched from the <k8s-base> repository. These steps ensure that the version of the configuration files and Kubernetes Open API spec match the release version. The versioned directory name follows the pattern of v<major>_<minor>.

    1. cd <rdocs-base>
    2. make updateapispec

    The copyapi target builds the API reference and copies the generated files to directories in <web-base>. Run the following command in <rdocs-base>:

    1. cd <rdocs-base>
    2. make copyapi

    Verify that these two files have been generated:

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

    Go to the base of your local <web-base>, and view which files have been modified:

    The output is similar to:

    1. static/docs/reference/generated/kubernetes-api/v1.23/css/bootstrap.min.css
    2. static/docs/reference/generated/kubernetes-api/v1.23/css/font-awesome.min.css
    3. static/docs/reference/generated/kubernetes-api/v1.23/fonts/FontAwesome.otf
    4. static/docs/reference/generated/kubernetes-api/v1.23/fonts/fontawesome-webfont.eot
    6. static/docs/reference/generated/kubernetes-api/v1.23/fonts/fontawesome-webfont.ttf
    7. static/docs/reference/generated/kubernetes-api/v1.23/fonts/fontawesome-webfont.woff
    8. static/docs/reference/generated/kubernetes-api/v1.23/fonts/fontawesome-webfont.woff2
    9. static/docs/reference/generated/kubernetes-api/v1.23/index.html
    10. static/docs/reference/generated/kubernetes-api/v1.23/js/jquery.scrollTo.min.js
    11. static/docs/reference/generated/kubernetes-api/v1.23/js/navData.js
    12. static/docs/reference/generated/kubernetes-api/v1.23/js/scroll.js

    Updating the API reference index pages

    When generating reference documentation for a new release, update the file, <web-base>/content/en/docs/reference/kubernetes-api/api-index.md with the new version number.

    • Open <web-base>/content/en/docs/reference/kubernetes-api/api-index.md for editing, and update the API reference version number. For example:

      1. ---
      2. title: v1.17
      3. ---
      5. [Kubernetes API v1.17](/docs/reference/generated/kubernetes-api/v1.17/)

    • 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 .

    1. cd <web-base>
    2. git submodule update --init --recursive --depth 1 # if not already done
    3. make container-serve

    Commit the changes

    Submit your changes as a 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.