Updating Reference Documentation

• 1: Reference Documentation Quickstart
• 2: Generating Reference Documentation for a Release
• 3: Contributing to the Upstream Kubernetes Code
• 4: Generating Reference Documentation for the Kubernetes API
• 5: Generating Reference Documentation for Configuration APIs
• 6: Generating Reference Documentation for kubectl Commands
• 7: Generating Reference Documentation for Metrics
• 8: Generating Reference Pages for Kubernetes Components and Tools
• 9:

1 - Reference Documentation Quickstart

This page shows how to use the update-imported-docs.py script to generate the Kubernetes reference documentation. The script automates the build setup and generates the reference documentation for a release.

Before you begin

Requirements:

• You need a machine that is running Linux or macOS. On Windows, use Windows Subsystem for Linux (WSL), since the build tooling relies on make and Bash scripts.

• You need to have these tools installed:

  • Git
  • Go, any recent release (Go downloads the exact toolchain a generator needs automatically)
  • make
  • gcc compiler/linker
  • Docker (required only for the local website preview with make container-serve)

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

Getting the docs repository

Make sure your website fork is up-to-date with the kubernetes/website remote on GitHub (main branch), and clone your website fork.

mkdir github.com
cd github.com
git clone git@github.com:<your_github_username>/website.git

Determine the base directory of your clone. For example, if you followed the preceding step to get the repository, your base directory is github.com/website. The remaining steps refer to your base directory as <web-base>.

Overview of update-imported-docs

The update-imported-docs.py script is located in the <web-base>/update-imported-docs/ directory.

The script builds the following references:

• Component and tool reference pages
• The kubectl command reference
• The Kubernetes API reference

The update-imported-docs.py script generates the Kubernetes reference documentation from the Kubernetes source code. The script creates a temporary directory under /tmp on your machine and clones the required repositories: kubernetes/kubernetes and kubernetes-sigs/reference-docs into this directory. The script sets your GOPATH to this temporary directory. Three additional environment variables are set:

• K8S_RELEASE
• K8S_ROOT
• K8S_WEBROOT

The script requires two arguments to run successfully:

• A YAML configuration file (reference.yml)
• A release version, for example:1.17

The configuration file contains a generate-command field. The generate-command field defines a series of build instructions from kubernetes-sigs/reference-docs/Makefile. The K8S_RELEASE variable determines the version of the release.

The update-imported-docs.py script performs the following steps:

1. Clones the related repositories specified in a configuration file. For the purpose of generating reference docs, the repository that is cloned by default is kubernetes-sigs/reference-docs.
2. Runs commands under the cloned repositories to prepare the docs generator and then generates the HTML and Markdown files.
3. Copies the generated HTML and Markdown files to a local clone of the <web-base> repository under locations specified in the configuration file.
4. Updates kubectl command links from kubectl.md to the refer to the sections in the kubectl command reference.

When the generated files are in your local clone of the <web-base> repository, you can submit them in a pull request to <web-base>.

Configuration file format

Each configuration file may contain multiple repos that will be imported together. When necessary, you can customize the configuration file by manually editing it. You may create new config files for importing other groups of documents. The following is an example of the YAML configuration file:

repos:
- name: community
  remote: https://github.com/kubernetes/community.git
  branch: master
  files:
  - src: contributors/devel/README.md
    dst: docs/imported/community/devel.md
  - src: contributors/guide/README.md
    dst: docs/imported/community/guide.md

Single page Markdown documents, imported by the tool, must adhere to the Documentation Style Guide.

Customizing reference.yml

Open <web-base>/update-imported-docs/reference.yml for editing. Do not change the content for the generate-command field unless you understand how the command is used to build the references. You should not need to update reference.yml. At times, changes in the upstream source code, may require changes to the configuration file (for example: golang version dependencies and third-party library changes). If you encounter build issues, contact the SIG-Docs team on the #sig-docs Kubernetes Slack channel.

In reference.yml, files contains a list of src and dst fields. The src field contains the location of a generated Markdown file in the cloned kubernetes-sigs/reference-docs build directory, and the dst field specifies where to copy this file in the cloned kubernetes/website repository. For example:

repos:
- name: reference-docs
  remote: https://github.com/kubernetes-sigs/reference-docs.git
  files:
  - src: gen-compdocs/build/kube-apiserver.md
    dst: content/en/docs/reference/command-line-tools-reference/kube-apiserver.md
  ...

Note that when there are many files to be copied from the same source directory to the same destination directory, you can use wildcards in the value given to src. You must provide the directory name as the value for dst. For example:

  files:
  - src: gen-compdocs/build/kubeadm*.md
    dst: content/en/docs/reference/setup-tools/kubeadm/generated/

Running the update-imported-docs tool

You can run the update-imported-docs.py tool as follows:

cd <web-base>/update-imported-docs
./update-imported-docs.py <configuration-file.yml> <release-version>

For example:

./update-imported-docs.py reference.yml 1.17

Fixing Links

The release.yml configuration file contains instructions to fix relative links. To fix relative links within your imported files, set thegen-absolute-links property to true. You can find an example of this in release.yml.

Adding and committing changes in kubernetes/website

List the files that were generated and copied to <web-base>:

cd <web-base>
git status

The output shows the new and modified files. The generated output varies depending upon changes made to the upstream source code.

Generated component tool files

content/en/docs/reference/command-line-tools-reference/kube-apiserver.md
content/en/docs/reference/command-line-tools-reference/kube-controller-manager.md
content/en/docs/reference/command-line-tools-reference/kube-proxy.md
content/en/docs/reference/command-line-tools-reference/kube-scheduler.md
content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm.md
content/en/docs/reference/kubectl/kubectl.md

Generated kubectl command reference files

static/docs/reference/generated/kubectl/kubectl-commands.html
static/docs/reference/generated/kubectl/navData.js
static/docs/reference/generated/kubectl/scroll.js
static/docs/reference/generated/kubectl/stylesheet.css
static/docs/reference/generated/kubectl/tabvisibility.js
static/docs/reference/generated/kubectl/node_modules/bootstrap/dist/css/bootstrap.min.css
static/docs/reference/generated/kubectl/node_modules/highlight.js/styles/default.css
static/docs/reference/generated/kubectl/node_modules/jquery.scrollto/jquery.scrollTo.min.js
static/docs/reference/generated/kubectl/node_modules/jquery/dist/jquery.min.js
static/docs/reference/generated/kubectl/css/font-awesome.min.css

Generated Kubernetes API reference directories and files

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

Run git add and git commit to commit the files.

Creating a pull request

Create a pull request to the kubernetes/website repository. Monitor your pull request, and respond to review comments as needed. Continue to monitor your pull request until it is merged.

A few minutes after your pull request is merged, your updated reference topics will be visible in the published documentation.

What's next

To regenerate every reference set for a release and submit the output as pull requests, see Generating Reference Documentation for a Release.

To generate the individual reference documentation by manually setting up the required build repositories and running the build targets, see the following guides:

• Generating Reference Documentation for Kubernetes Components and Tools
• Generating Reference Documentation for kubectl Commands
• Generating Reference Documentation for the Kubernetes API

2 - Generating Reference Documentation for a Release

This page shows how to regenerate every set of Kubernetes reference documentation for a new release, and how to divide the generated output into pull requests that reviewers can handle one at a time.

Work through the sections in order. Each reference set has its own section that builds it, copies it into your website clone, and ends with a page to check, so you can finish one set before you start the next. The summary at the end lists every target, its output, and the pull requests to open.

Before you begin

Requirements:

• You need a machine that is running Linux or macOS. On Windows, use Windows Subsystem for Linux (WSL), since the build tooling relies on make and Bash scripts.

• You need to have these tools installed:

  • Git
  • Go, any recent release (Go downloads the exact toolchain a generator needs automatically)
  • make
  • gcc compiler/linker
  • Docker (required only for the local website preview with make container-serve)

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

Set up the local repositories

You need local clones of kubernetes/website and kubernetes-sigs/reference-docs.

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 build variables

Set these in your shell. They apply to every make command in the steps that follow.

export K8S_WEBROOT=<your-path-to>/website     # your website clone (<web-base>)
export K8S_RELEASE=1.38.0

Set K8S_RELEASE to a full release version, such as 1.38.0 or 1.38.0-rc.1. The build targets derive the versioned directory name, such as v1_38, from the major and minor version.

Create the versioned directories

Run this in <rdocs-base>:

make createversiondirs

This creates the configuration directory for the new release under gen-apidocs/config/, copying config.yaml from the previous release.

You rarely need to edit that file. The settings that change with every release, the API groups and the list of resources, are empty in it: the build targets on this page pass --auto-detect, so the generator reads them from swagger.json. What stays in the file is operation naming and exclusion, which follows the API machinery rather than the API surface.

When the generated reference looks wrong, fix the cause upstream where you can: descriptions and deprecation notices come from Go comments in kubernetes/kubernetes, and a fix there reaches every reader of that API. Edit config.yaml only for what the generator alone decides, such as an untitled operation (operation_categories), an endpoint that the reference should not publish (excluded_operations), or a group whose operation IDs spell it differently from its resources (operation_group_map). Each entry is carried into every later release, so keep the file lean.

Fetch the OpenAPI specification

The API reference generator reads gen-apidocs/config/<version>/swagger.json. The specification that kubernetes/kubernetes commits is built with the OpenAPIEnums feature gate turned off, so it omits the allowed values of enumerated fields, and a reference built from it omits them too. It's better to generate a reference that does list allowed values, so you take some additional steps to make that happen.

Choose one of the following two options.

Option 1: Generate the specification from source

Use this option unless you cannot meet the requirements below. It needs no kubernetes/kubernetes clone of your own, it leaves any clone you already have untouched, and it produces a specification that includes enum values.

make updateapispec-enums-from-source

The target shallow-clones kubernetes/kubernetes at tag v$K8S_RELEASE into a temporary directory, turns on OpenAPIEnums=true in that checkout only, runs the upstream hack/update-openapi-spec.sh, copies the resulting specification into the versioned configuration directory, checks that it contains enum values, and removes the checkout. Beyond the tools in the prerequisites, it needs:

• jq, curl, and openssl on your PATH
• network access, to clone the tag and to download Go modules and etcd
• free TCP ports 2379 and 8050

The upstream script starts etcd on port 2379 and a temporary API server on port 8050; set ETCD_PORT or API_PORT if either is taken. It downloads its own copy of etcd and builds kube-apiserver, so expect the first run to take several minutes.

To keep the temporary checkout and the generation log for troubleshooting:

KEEP_TMP=1 make updateapispec-enums-from-source

Option 2: Copy the committed specification from a local clone

This option needs a local kubernetes/kubernetes clone, and it copies the specification much faster.

In your kubernetes/kubernetes clone, run hack/update-openapi-spec.sh and commit the regenerated api/openapi-spec/swagger.json at tag v$K8S_RELEASE. Then copy it into reference-docs:

export K8S_ROOT=<your-path-to>/kubernetes
cd <rdocs-base>
make updateapispec

The target reads the file as it is committed at that tag, not the file in your working tree. This is the only step on this page that reads K8S_ROOT.

Check the specification

Whichever option you use, you can check a specification for enum values at any time:

./hack/verify-enum-swagger.sh gen-apidocs/config/<version>/swagger.json

Start the local preview

Start the preview once, in a second terminal, and leave it running. Hugo reloads each page as the copy targets replace it, so you can check each reference set as soon as you generate it.

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

Hugo serves the preview at http://localhost:1313/.

Generate the Kubernetes API reference

gen-apidocs builds this set, the HTML API reference, from the OpenAPI specification you fetched. The build output goes to gen-apidocs/build/html/ before the target copies it.

cd <rdocs-base>
make copyapi

The target writes two files to <web-base>:

static/docs/reference/generated/kubernetes-api/v1.38/index.html
static/docs/reference/generated/kubernetes-api/v1.38/js/navData.js

Check /docs/reference/generated/kubernetes-api/v1.38/ in the preview. Open a resource such as Pod and search the page for Possible enum values, which confirms that the specification carried the enum values through.

See Pull requests for what to open for this set.

Generate the API reference pages in Markdown

gen-apidocs also builds this set, the Markdown API reference that Hugo renders as regular pages, from the same specification. The build output goes to gen-apidocs/build/markdown/.

cd <rdocs-base>
make copyapimd

The target replaces <web-base>/content/en/docs/reference/kubernetes-api/ and keeps the _index.md that people maintain by hand.

Check /docs/reference/kubernetes-api/ in the preview. Compare the number of generated pages with the previous release:

find <web-base>/content/en/docs/reference/kubernetes-api -name '*.md' | wc -l

See Pull requests for what to open for this set.

Generate the component reference

gen-compdocs builds from k8s.io/kubernetes and from the k8s.io staging modules that go.mod pins with replace directives. go get updates the first and leaves the rest, so move the whole set at once:

cd <rdocs-base>/gen-compdocs
STAGING=v0.${K8S_RELEASE#*.}
go get k8s.io/kubernetes@v$K8S_RELEASE
KK=$(go list -m -f '{{.Dir}}' k8s.io/kubernetes)

# every staging module of this release
for m in $(awk '/=> \.\/staging\/src\//{print $1}' "$KK/go.mod"); do
  go mod edit -replace="$m=$m@$STAGING" -require="$m@$STAGING"
done

# entries left from a release with a different set of staging modules
for m in $(go mod edit -json | jq -r '.Replace[].Old.Path'); do
  grep -q "$m => ./staging/src/$m" "$KK/go.mod" ||
    go mod edit -dropreplace="$m" -droprequire="$m"
done

go mod tidy
go mod edit -go=$(go list -m -f '{{.GoVersion}}' k8s.io/kubernetes)
go mod tidy

git ls-remote --tags https://github.com/kubernetes/api.git "v0.${K8S_RELEASE#*.}"

The loops read the module set from kubernetes/kubernetes, because releases add and remove staging modules and go.mod can still list ones from an older release. The go directive comes last: while old modules are still in the graph, go mod tidy raises it again.

Check what moved:

git diff go.mod

Every k8s.io requirement, every replace, and the go directive should now name the new release. Requirements outside the staging set, such as k8s.io/klog/v2 and the Goldmark packages, keep their own versions.

Then build and copy the core component pages:

cd <rdocs-base>
make copycomp-core

gen-compdocs writes every component page to gen-compdocs/build/, and the target copies kube-apiserver.md, kube-controller-manager.md, kube-scheduler.md, kube-proxy.md, and kubelet.md from there to <web-base>/content/en/docs/reference/command-line-tools-reference/.

Check /docs/reference/command-line-tools-reference/ in the preview.

See Pull requests for what to open for this set.

Generate the kubectl reference

The kubectl pages come from the same gen-compdocs build as the component reference, and belong in their own pull request.

cd <rdocs-base>
make copycomp-kubectl

The target writes kubectl.md and a directory for each subcommand to <web-base>/content/en/docs/reference/kubectl/generated/, and keeps the _index.md that people maintain by hand.

Check /docs/reference/kubectl/generated/ in the preview, and open a subcommand page such as kubectl apply.

See Pull requests for what to open for this set.

Generate the kubeadm reference

The kubeadm pages also come from gen-compdocs, and belong in their own pull request.

cd <rdocs-base>
make copycomp-kubeadm

The target writes kubeadm.md and a directory for each subcommand to <web-base>/content/en/docs/reference/setup-tools/kubeadm/generated/, and keeps the _index.md and README.md that people maintain by hand.

Check /docs/reference/setup-tools/kubeadm/generated/ in the preview.

See Pull requests for what to open for this set.

Generate the configuration API reference

genref reads the Go configuration types of each component from the k8s.io staging modules. It has no replace directives, so the requirements alone decide which release you document:

cd <rdocs-base>/genref
STAGING=v0.${K8S_RELEASE#*.}
OLD=$(go mod edit -json | jq -r '.Require[] | select(.Path=="k8s.io/api") | .Version')

# every k8s.io module pinned to the previous release
go get $(go mod edit -json | jq -r --arg v "$OLD" --arg s "$STAGING" \
  '.Require[] | select(.Version==$v and (.Path|startswith("k8s.io/"))) | .Path + "@" + $s')

go mod tidy
go mod edit -go=$(go list -m -f '{{.GoVersion}}' k8s.io/api)
go mod tidy

Selecting by the old version picks up the staging modules and leaves k8s.io/klog/v2, k8s.io/gengo, and the other independent repositories alone. Check what moved:

git diff go.mod

Also update the release in the externalPackages link target in genref/config.yaml, which points readers at the published API reference.

Check for new API versions

genref generates one page for each entry in genref/config.yaml, and each entry names a Go package and a path that ends in an API version:

  - name: kubelet-config
    title: Kubelet Configuration (v1)
    package: k8s.io/kubelet
    path: config/v1

A component that starts serving a new version of its configuration API adds a version directory in its Go source. List the version directories of a component to see what exists in this release:

cd <rdocs-base>/genref
go mod download
ls "$(go list -m -f '{{.Dir}}' k8s.io/kubelet)/config"

To compare every entry in config.yaml against the source at once, run:

awk '$1=="package:"{pkg=$2} $1=="path:"{print pkg, $2}' config.yaml | sort -u |
while read -r pkg path; do
  dir=$(go list -m -f '{{.Dir}}' "$pkg" 2>/dev/null) || continue
  parent=$(dirname "$path")
  for v in $(find "$dir/$parent" -maxdepth 1 -mindepth 1 -type d -name 'v[0-9]*'); do
    grep -q "path: $parent/$(basename "$v")\$" config.yaml ||
      echo "$pkg $parent/$(basename "$v")"
  done
done | sort -u

Each line is a candidate, not a gap to fill: several older versions are left out on purpose, and the comments in config.yaml record why. Add an entry when a component serves a version that readers configure, and keep the entry for an older version while the component still serves it.

Build and copy the pages

cd <rdocs-base>
make copyconfigapi

genref writes the generated pages to genref/output/md/, and the target sorts them as it copies: most go to content/en/docs/reference/config-api/, the metrics APIs go to content/en/docs/reference/external-api/, because the project defines them but does not serve them from the API server, and the pages the website does not publish are skipped.

Check both sections in the preview, and confirm that no page you published for the previous release disappeared:

cd <web-base>
git status content/en/docs/reference/config-api/ content/en/docs/reference/external-api/

See Pull requests for what to open for this set.

Summary

Each copy target builds first. To build every set without copying anything into your website clone, run make api apimd comp configapi.

Pull requests

Each reference set gets its own website pull request, six in all, and the generator side takes three. Open a website pull request together with the reference-docs pull request it needs, and hold the website one until that merges.

In each website pull request, say how you generated the output, so that a reviewer can reproduce it:

Regenerated the kubectl reference for v1.38.0.

- Generated with `make copycomp-kubectl` from kubernetes-sigs/reference-docs at commit <commit>
- Generator changes: kubernetes-sigs/reference-docs#<pull request>
- Generated files only, with no hand edits

For the two API reference sets, add how you produced the OpenAPI specification, because the generated output does not show it: generated from source with OpenAPIEnums=true, or copied from a clone.

What's next

• Generating Reference Documentation for the Kubernetes API
• Generating Reference Documentation for Configuration APIs
• Generating Reference Pages for Kubernetes Components and Tools
• Generating Reference Documentation for kubectl Commands
• Generating Reference Documentation for Metrics
• Contributing to the Upstream Kubernetes Code

3 - Contributing to the Upstream Kubernetes Code

This page shows how to contribute to the upstream kubernetes/kubernetes project. You can fix bugs found in the Kubernetes API documentation or the content of the Kubernetes components such as kubeadm, kube-apiserver, and kube-controller-manager.

If you instead want to regenerate the reference documentation for the Kubernetes API or the kube-* components from the upstream code, see the following instructions:

• Generating Reference Documentation for the Kubernetes API
• Generating Reference Documentation for the Kubernetes Components and Tools

Before you begin

• You need to have these tools installed:

  • Git
  • Golang version 1.13+
  • Docker
  • etcd
  • make
  • gcc compiler/linker

• Your GOPATH environment variable must be set, and the location of etcd must be in your PATH environment variable.

• You need to know how to create a pull request to a GitHub repository. Typically, this involves creating a fork of the repository. For more information, see Creating a Pull Request and GitHub Standard Fork & Pull Request Workflow.

The big picture

The reference documentation for the Kubernetes API and the kube-* components such as kube-apiserver, kube-controller-manager are automatically generated from the source code in the upstream Kubernetes.

When you see bugs in the generated documentation, you may want to consider creating a patch to fix it in the upstream project.

Clone the Kubernetes repository

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

Determine the base directory of your clone of the kubernetes/kubernetes repository. For example, if you followed the preceding step to get the repository, your base directory is $GOPATH/src/github.com/kubernetes/kubernetes. The remaining steps refer to your base directory as <k8s-base>.

Determine the base directory of your clone of the kubernetes-sigs/reference-docs repository. For example, if you followed the preceding step to get the repository, your base directory is $GOPATH/src/github.com/kubernetes-sigs/reference-docs. The remaining steps refer to your base directory as <rdocs-base>.

Edit the Kubernetes source code

The Kubernetes API reference documentation is automatically generated from an OpenAPI spec, which is generated from the Kubernetes source code. If you want to change the API reference documentation, the first step is to change one or more comments in the Kubernetes source code.

The documentation for the kube-* components is also generated from the upstream source code. You must change the code related to the component you want to fix in order to fix the generated documentation.

Make changes to the upstream source code

Here's an example of editing a comment in the Kubernetes source code.

In your local kubernetes/kubernetes repository, check out the default branch, and make sure it is up to date:

cd <k8s-base>
git checkout master
git pull https://github.com/kubernetes/kubernetes master

Suppose this source file in that default branch has the typo "atmost":

kubernetes/kubernetes/staging/src/k8s.io/api/apps/v1/types.go

In your local environment, open types.go, and change "atmost" to "at most".

Verify that you have changed the file:

git status

The output shows that you are on the master branch, and that the types.go source file has been modified:

On branch master
...
    modified:   staging/src/k8s.io/api/apps/v1/types.go

Commit your edited file

Run git add and git commit to commit the changes you have made so far. In the next step, you will do a second commit. It is important to keep your changes separated into two commits.

Generate the OpenAPI spec and related files

Go to <k8s-base> and run these scripts:

./hack/update-codegen.sh
./hack/update-openapi-spec.sh

Run git status to see what was generated.

On branch master
...
    modified:   api/openapi-spec/swagger.json
    modified:   api/openapi-spec/v3/apis__apps__v1_openapi.json
    modified:   pkg/generated/openapi/zz_generated.openapi.go
    modified:   staging/src/k8s.io/api/apps/v1/generated.proto
    modified:   staging/src/k8s.io/api/apps/v1/types_swagger_doc_generated.go

View the contents of api/openapi-spec/swagger.json to make sure the typo is fixed. For example, you could run git diff -a api/openapi-spec/swagger.json. This is important, because swagger.json is the input to the second stage of the doc generation process.

Run git add and git commit to commit your changes. Now you have two commits: one that contains the edited types.go file, and one that contains the generated OpenAPI spec and related files. Keep these two commits separate. That is, do not squash your commits.

Submit your changes as a pull request to the master branch of the kubernetes/kubernetes repository. Monitor your pull request, and respond to reviewer comments as needed. Continue to monitor your pull request until it is merged.

PR 57758 is an example of a pull request that fixes a typo in the Kubernetes source code.

Cherry pick your commit into a release branch

In the preceding section, you edited a file in the master branch and then ran scripts to generate an OpenAPI spec and related files. Then you submitted your changes in a pull request to the master branch of the kubernetes/kubernetes repository. Now suppose you want to backport your change into a release branch. For example, suppose the master branch is being used to develop Kubernetes version 1.37, and you want to backport your change into the release-1.36 branch.

Recall that your pull request has two commits: one for editing types.go and one for the files generated by scripts. The next step is to propose a cherry pick of your first commit into the release-1.36 branch. The idea is to cherry pick the commit that edited types.go, but not the commit that has the results of running the scripts. For instructions, see Propose a Cherry Pick.

When you have a pull request in place for cherry picking your one commit into the release-1.36 branch, the next step is to run these scripts in the release-1.36 branch of your local environment.

./hack/update-codegen.sh
./hack/update-openapi-spec.sh

Now add a commit to your cherry-pick pull request that has the recently generated OpenAPI spec and related files. Monitor your pull request until it gets merged into the release-1.36 branch.

At this point, both the master branch and the release-1.36 branch have your updated types.go file and a set of generated files that reflect the change you made to types.go. Note that the generated OpenAPI spec and other generated files in the release-1.36 branch are not necessarily the same as the generated files in the master branch. The generated files in the release-1.36 branch contain API elements only from Kubernetes 1.36. The generated files in the master branch might contain API elements that are not in 1.36, but are under development for 1.37.

Generate the published reference docs

The preceding section showed how to edit a source file and then generate several files, including api/openapi-spec/swagger.json in the kubernetes/kubernetes repository. The swagger.json file is the OpenAPI definition file to use for generating the API reference documentation.

You are now ready to follow the Generating Reference Documentation for the Kubernetes API guide to generate the published Kubernetes API reference documentation.

What's next

• Generating Reference Documentation for the Kubernetes API
• Generating Reference Docs for Kubernetes Components and Tools
• Generating Reference Documentation for kubectl Commands

4 - Generating Reference Documentation for the Kubernetes API

This page shows how to update the Kubernetes API reference documentation.

The Kubernetes API reference documentation is built from the Kubernetes OpenAPI spec using the kubernetes-sigs/reference-docs 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 OpenAPI spec, continue reading this page.

Before you begin

Requirements:

• You need a machine that is running Linux or macOS. On Windows, use Windows Subsystem for Linux (WSL), since the build tooling relies on make and Bash scripts.

• You need to have these tools installed:

  • Git
  • Go, any recent release (Go downloads the exact toolchain a generator needs automatically)
  • make
  • gcc compiler/linker
  • Docker (required only for the local website preview with make container-serve)

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

Set up the local repositories

Create a local workspace and set your GOPATH:

mkdir -p $HOME/<workspace>

export GOPATH=$HOME/<workspace>

Get a local clone of the following repositories:

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

Move into the gen-apidocs directory of the reference-docs repository and install the required Go packages:

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 

Get a clone of the kubernetes/kubernetes repository:

git clone https://github.com/kubernetes/kubernetes 

• The base directory of your clone of the kubernetes/kubernetes repository is <your-path-to>/kubernetes/kubernetes. The remaining steps refer to your base directory as <k8s-base>.

• The base directory of your clone of the kubernetes/website repository is <your-path-to>/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 <your-path-to>/reference-docs. The remaining steps refer to your base directory as <rdocs-base>.

Generate the API reference docs

This section shows how to generate the published Kubernetes API reference documentation.

Set build variables

• Set K8S_ROOT to <k8s-base>.
• Set K8S_WEBROOT to <web-base>.
• Set K8S_RELEASE 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:

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

Create versioned directory and fetch Open API spec

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

In the <rdocs-base> directory, run the following build target:

cd <rdocs-base>
make updateapispec

Build the API reference docs

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

cd <rdocs-base>
make copyapi

Verify that these two files have been generated:

[ -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"

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

cd <web-base>
git status

The output is similar to:

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

API reference location and versioning

The generated API reference files (HTML version) are copied to <web-base>/static/docs/reference/generated/kubernetes-api/v1.37/. This directory contains the standalone HTML API documentation.

Locally test the API reference

Publish a local version of the API reference. Verify the local preview.

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

Commit the changes

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.

What's next

• Generating Reference Documentation Quickstart
• Generating Reference Docs for Kubernetes Components and Tools
• Generating Reference Documentation for kubectl Commands

5 - Generating Reference Documentation for Configuration APIs

This page shows how you can generate updated reference documentation for Kubernetes Configuration APIs. It is aimed at people who are contributing to Kubernetes.

The Configuration API reference documents the configuration formats for Kubernetes tools and components — for example, kubelet, kube-apiserver, kube-scheduler, kubeconfig, and kubeadm formats. The published reference is at /docs/reference/config-api/.

genref, in kubernetes-sigs/reference-docs, is the generator that builds this reference. It reads each component's Go configuration types and renders them as markdown.

If you find bugs in the generated content, you most likely need to fix them upstream.

Before you begin

Requirements:

• You need a machine that is running Linux or macOS. On Windows, use Windows Subsystem for Linux (WSL), since the build tooling relies on make and Bash scripts.

• You need to have these tools installed:

  • Git
  • Go, any recent release (Go downloads the exact toolchain a generator needs automatically)
  • make
  • gcc compiler/linker
  • Docker (required only for the local website preview with make container-serve)

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

Set up the local repositories

You need local clones of kubernetes/website and kubernetes-sigs/reference-docs.

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 build variables

Set this in your shell. It applies 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>)

Build and publish the Configuration API reference

From <rdocs-base>:

cd <rdocs-base>
make copyconfigapi

This command runs in two stages:

1. configapi - builds and runs genref, which generates Markdown to genref/output/md
2. copyconfigapi - copies the generated files into your website clone at <web-base>/content/en/docs/reference/config-api/.

The first run downloads the Go module dependencies and it may take several minutes.

Check what changed in your website clone:

cd <web-base>
git status

Look for updates made under content/en/docs/reference/config-api - for example:

content/en/docs/reference/config-api/kubelet-config.v1beta1.md
content/en/docs/reference/config-api/kubeadm-config.v1beta4.md
content/en/docs/reference/config-api/apiserver-config.v1.md
content/en/docs/reference/config-api/client-authentication.v1.md

Preview website and test locally

Preview your updates:

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

Then open a local preview through your web browser and confirm that the pages you updated load properly. Hugo serves that local preview at http://localhost:1313/ So the page to check is http://localhost:1313/docs/reference/config-api/

Commit the changes

If you regenerated the Configuration API reference for a release update, commit the changed files under content/en/docs/reference/config-api/ in <web-base>, then open a pull request to kubernetes/website.

What's next

• Generating Reference Documentation for the Kubernetes API
• Generating Reference Documentation Quickstart
• Contributing to Upstream Reference Docs

6 - Generating Reference Documentation for kubectl Commands

This page shows how to generate the kubectl command reference.

Before you begin

Requirements:

• You need a machine that is running Linux or macOS. On Windows, use Windows Subsystem for Linux (WSL), since the build tooling relies on make and Bash scripts.

• You need to have these tools installed:

  • Git
  • Go, any recent release (Go downloads the exact toolchain a generator needs automatically)
  • make
  • gcc compiler/linker
  • Docker (required only for the local website preview with make container-serve)

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

Set up the local repositories

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/spf13/pflag
go get -u github.com/spf13/cobra
go get -u gopkg.in/yaml.v2
go get -u github.com/kubernetes-sigs/reference-docs

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

Remove the spf13 package from $GOPATH/src/k8s.io/kubernetes/vendor/github.com:

rm -rf $GOPATH/src/k8s.io/kubernetes/vendor/github.com/spf13

The kubernetes/kubernetes repository provides the kubectl and kustomize source code.

• Determine the base directory of your clone of the kubernetes/kubernetes repository. For example, if you followed the preceding step to get the repository, your base directory is $GOPATH/src/k8s.io/kubernetes. The remaining steps refer to your base directory as <k8s-base>.

• Determine the base directory of your clone of the kubernetes/website repository. For example, if you followed the preceding step to get the repository, your base directory is $GOPATH/src/github.com/<your-username>/website. The remaining steps refer to your base directory as <web-base>.

• Determine the base directory of your clone of the kubernetes-sigs/reference-docs repository. For example, if you followed the preceding step to get the repository, your base directory is $GOPATH/src/github.com/kubernetes-sigs/reference-docs. The remaining steps refer to your base directory as <rdocs-base>.

In your local k8s.io/kubernetes repository, check out the branch of interest, and make sure it is up to date. For example, if you want to generate docs for Kubernetes 1.36.0, you could use these commands:

cd <k8s-base>
git checkout v1.36.0
git pull https://github.com/kubernetes/kubernetes 1.36.0

If you do not need to edit the kubectl source code, follow the instructions for Setting build variables.

Edit the kubectl source code

The kubectl command reference documentation is automatically generated from the kubectl source code. If you want to change the reference documentation, the first step is to change one or more comments in the kubectl source code. Make the change in your local kubernetes/kubernetes repository, and then submit a pull request to the master branch of github.com/kubernetes/kubernetes.

PR 56673 is an example of a pull request that fixes a typo in the kubectl source code.

Monitor your pull request, and respond to reviewer comments. Continue to monitor your pull request until it is merged into the target branch of the kubernetes/kubernetes repository.

Cherry pick your change into a release branch

Your change is now in the master branch, which is used for development of the next Kubernetes release. If you want your change to appear in the docs for a Kubernetes version that has already been released, you need to propose that your change be cherry picked into the release branch.

For example, suppose the master branch is being used to develop Kubernetes 1.37 and you want to backport your change to the release-1.36 branch. For instructions on how to do this, see Propose a Cherry Pick.

Monitor your cherry-pick pull request until it is merged into the release branch.

Set build variables

Go to <rdocs-base>. On you command line, set the following environment variables.

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

For example:

export K8S_WEBROOT=$GOPATH/src/github.com/<your-username>/website
export K8S_ROOT=$GOPATH/src/k8s.io/kubernetes
export K8S_RELEASE=1.36

Creating a versioned directory

The createversiondirs build target creates a versioned directory and copies the kubectl reference configuration files to the versioned directory. The versioned directory name follows the pattern of v<major>_<minor>.

In the <rdocs-base> directory, run the following build target:

cd <rdocs-base>
make createversiondirs

Check out a release tag in k8s.io/kubernetes

In your local <k8s-base> repository, check out the branch that has the version of Kubernetes that you want to document. For example, if you want to generate docs for Kubernetes 1.36.0, check out the v1.36 tag. Make sure your local branch is up to date.

cd <k8s-base>
git checkout v1.36.0
git pull https://github.com/kubernetes/kubernetes v1.36.0

Run the doc generation code

In your local <rdocs-base>, run the copycli build target. The command runs as root:

cd <rdocs-base>
make copycli

The copycli command cleans the temporary build directory, generates the kubectl command files, and copies the collated kubectl command reference HTML page and assets to <web-base>.

Locate the generated files

Verify that these two files have been generated:

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

Locate the copied files

Verify that all generated files have been copied to your <web-base>:

cd <web-base>
git status

The output should include the modified files:

static/docs/reference/generated/kubectl/kubectl-commands.html
static/docs/reference/generated/kubectl/navData.js

The output may also include:

static/docs/reference/generated/kubectl/scroll.js
static/docs/reference/generated/kubectl/stylesheet.css
static/docs/reference/generated/kubectl/tabvisibility.js
static/docs/reference/generated/kubectl/node_modules/bootstrap/dist/css/bootstrap.min.css
static/docs/reference/generated/kubectl/node_modules/highlight.js/styles/default.css
static/docs/reference/generated/kubectl/node_modules/jquery.scrollto/jquery.scrollTo.min.js
static/docs/reference/generated/kubectl/node_modules/jquery/dist/jquery.min.js
static/docs/reference/generated/kubectl/node_modules/font-awesome/css/font-awesome.min.css

Locally test the documentation

Build the Kubernetes documentation in your local <web-base>.

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

View the local preview.

Add and commit changes in kubernetes/website

Run git add and git commit to commit the files.

Create a pull request

Create a pull request to the kubernetes/website repository. Monitor your pull request, and respond to review comments as needed. Continue to monitor your pull request until it is merged.

A few minutes after your pull request is merged, your updated reference topics will be visible in the published documentation.

What's next

• Generating Reference Documentation Quickstart
• Generating Reference Documentation for Kubernetes Components and Tools
• Generating Reference Documentation for the Kubernetes API

7 - Generating Reference Documentation for Metrics

This page demonstrates the generation of metrics reference documentation.

Before you begin

Requirements:

• You need a machine that is running Linux or macOS. On Windows, use Windows Subsystem for Linux (WSL), since the build tooling relies on make and Bash scripts.

• You need to have these tools installed:

  • Git
  • Go, any recent release (Go downloads the exact toolchain a generator needs automatically)
  • make
  • gcc compiler/linker
  • Docker (required only for the local website preview with make container-serve)

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

Clone the Kubernetes repository

The metric generation happens in the Kubernetes repository. To clone the repository, change directories to where you want the clone to exist.

Then, execute the following command:

git clone https://www.github.com/kubernetes/kubernetes 

This creates a kubernetes folder in your current working directory.

Generate the metrics

Inside the cloned Kubernetes repository, locate the test/instrumentation/documentation directory. The metrics documentation is generated in this directory.

With each release, new metrics are added. After you run the metrics documentation generator script, copy the metrics documentation to the Kubernetes website and publish the updated metrics documentation.

To generate the latest metrics, make sure you are in the root of the cloned Kubernetes directory. Then, execute the following command:

./test/instrumentation/update-documentation.sh

To check for changes, execute:

git status

The output is similar to:

./test/instrumentation/documentation/documentation.md
./test/instrumentation/documentation/documentation-list.yaml

Copy the generated metrics documentation file to the Kubernetes website repository

1. Set the Kubernetes website root environment variable.

   Execute the following command to set the website root:

   export WEBSITE_ROOT=<path to website root>
   

2. Copy the generated metrics file to the Kubernetes website repository.

   cp ./test/instrumentation/documentation/documentation.md "${WEBSITE_ROOT}/content/en/docs/reference/instrumentation/metrics.md"
   

   Note:

   If you get an error, check that you have permission to copy the file. You can use chown to change the file ownership back to your own user.

Create a pull request

To create a pull request, follow the instructions in Opening a pull request.

What's next

• Contribute-upstream
• Generating Reference Docs for Kubernetes Components and Tools
• Generating Reference Documentation for kubectl Commands

8 - Generating Reference Pages for Kubernetes Components and Tools

This page shows how to build the Kubernetes component and tool reference pages.

Before you begin

Start with the Prerequisites section in the Reference Documentation Quickstart guide.

Follow the Reference Documentation Quickstart to generate the Kubernetes component and tool reference pages.

What's next

• Generating Reference Documentation Quickstart
• Generating Reference Documentation for kubectl Commands
• Generating Reference Documentation for the Kubernetes API
• Contributing to the Upstream Kubernetes Project for Documentation

9 -

Requirements:

• You need a machine that is running Linux or macOS. On Windows, use Windows Subsystem for Linux (WSL), since the build tooling relies on make and Bash scripts.

• You need to have these tools installed:

  • Git
  • Go, any recent release (Go downloads the exact toolchain a generator needs automatically)
  • make
  • gcc compiler/linker
  • Docker (required only for the local website preview with make container-serve)

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