This page shows how to contribute documentation fixes to the upstream
kubernetes/kubernetes project. You can fix bugs found in the Kubernetes API
reference or in the reference pages for Kubernetes components such as kubeadm,
kube-apiserver, and kube-controller-manager.
If you instead want to regenerate the reference documentation from the upstream code, see the following instructions:
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.
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 Open a pull request.
You do not need to set GOPATH or use go get to clone Kubernetes repositories.
Clone the repositories with git.
The reference documentation for the Kubernetes API and the kube-* components,
such as kube-apiserver and kube-controller-manager, is generated from source
code in the upstream Kubernetes
repository.
When you see bugs in generated reference documentation, consider fixing the
authoritative comments or generated inputs in the upstream project. After the
upstream change is merged, regenerate the published reference documentation in
the kubernetes/website repository.
Create a workspace and clone the repositories you need:
mkdir -p ~/src/k8s.io
cd ~/src/k8s.io
git clone https://github.com/kubernetes/kubernetes.git
git clone https://github.com/kubernetes-sigs/reference-docs.git
git clone https://github.com/<your-username>/website.git
You use the kubernetes/kubernetes clone to fix the upstream source comments
and regenerate upstream generated files. You use the reference-docs and
website clones later to verify and publish the reference documentation.
The remaining steps refer to these local paths:
<k8s-base>: your kubernetes/kubernetes clone<rdocs-base>: your kubernetes-sigs/reference-docs clone<web-base>: your kubernetes/website fork cloneThe Kubernetes API reference documentation is 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 upstream
source code. You must change the code related to the component you want to fix
in order to fix the generated documentation.
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
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 source
changes and generated changes separated into two commits.
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 next stage of the
reference documentation generation process.
Run git add and git commit to commit your generated 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. 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.
staging directory
in the kubernetes/kubernetes repository. In your situation, the staging
directory might not be the authoritative source. For guidance, check the
README files in the
kubernetes/kubernetes
repository and in related repositories, such as
kubernetes/apiserver.In the preceding section, you edited a file in the master branch, ran scripts
to generate an OpenAPI spec and related files, and 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.36, and you want to backport your change into the
release-1.35 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.35 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.35 branch, run these scripts in the release-1.35 branch of your local environment:
./hack/update-codegen.sh
./hack/update-openapi-spec.sh
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.35 branch.
At this point, both the master branch and the
release-1.35 branch have your updated types.go file
and a set of generated files that reflect the change you made to types.go.
The generated OpenAPI spec and other generated files in the
release-1.35 branch are not necessarily the same as the
generated files in the master branch. The generated files in the release
branch contain API elements only from Kubernetes 1.35.
The generated files in the master branch might contain API elements that are
not in 1.35, but are under development for Kubernetes
1.36.
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.