# Generating Reference Documentation for Configuration APIs

LLMS index: [llms.txt](/llms.txt)

---

<!-- overview -->

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/](/docs/reference/config-api/).

`genref`, in [kubernetes-sigs/reference-docs](https://github.com/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](/docs/contribute/generate-ref-docs/contribute-upstream/).

## Before you begin


	<h3 id="requirements">Requirements:<a class="td-heading-self-link" href="#requirements" aria-label="Heading self-link"></a></h3>
<ul>
<li>
<p>You need a machine that is running Linux or macOS. On Windows, use
<a href="https://learn.microsoft.com/en-us/windows/wsl/install">Windows Subsystem for Linux (WSL)</a>,
since the build tooling relies on <code>make</code> and Bash scripts.</p>
</li>
<li>
<p>You need to have these tools installed:</p>
<ul>
<li><a href="https://git-scm.com/book/en/v2/Getting-Started-Installing-Git">Git</a></li>
<li><a href="https://go.dev/dl/">Go</a>, any recent release (Go downloads the exact toolchain a generator needs automatically)</li>
<li><a href="https://www.gnu.org/software/make/">make</a></li>
<li><a href="https://gcc.gnu.org/">gcc compiler/linker</a></li>
<li><a href="https://docs.docker.com/engine/installation/">Docker</a> (required only for the local website preview with <code>make container-serve</code>)</li>
</ul>
</li>
<li>
<p>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 <a href="/docs/contribute/new-content/open-a-pr/#fork-the-repo">Work from a local clone</a>.</p>
</li>
</ul>


<!-- steps -->

## 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](/docs/contribute/new-content/open-a-pr/#fork-the-repo).
Clone `reference-docs`:

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

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

## Build and publish the Configuration API reference

From `<rdocs-base>`:

```shell
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:
```shell
cd <web-base>
git status
```

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

```text
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:
```shell
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](/docs/contribute/new-content/open-a-pr/)
to [kubernetes/website](https://github.com/kubernetes/website).

## What's next

* [Generating Reference Documentation for the Kubernetes API](/docs/contribute/generate-ref-docs/kubernetes-api/)
* [Generating Reference Documentation Quickstart](/docs/contribute/generate-ref-docs/quickstart/)
* [Contributing to Upstream Reference Docs](/docs/contribute/generate-ref-docs/contribute-upstream/)