AI
Why the API Reference Generator Broke Every Release
Kubernetes releases three times a year. Before each release, someone on the docs sub-team had to generate reference docs for the kube-apiserver, kubectl, and metrics-server. The process required GCC, Python, Go, pyaml, and several other dependencies at specific versions. New release team members, who make up most of the team, hit failures regularly. Rey Lejano traced this problem back at least four years. Slack complaints and GitHub issues about outdated API reference docs arrived predictably, one month before every release.
Four Fixes Lavish Pal Shipped During His LFX Mentorship
The make api command completed but never wrote nav_data.js, the file that powers navigation in the API docs. Lavish found the data already existed in the table of contents and added a step to serialize it to JSON. He also added error handling to writer.go, so failures now print readable messages instead of failing silently. A hardcoded path (k8s.io/kubernetes) forced contributors to rename their local clone. A new K_ROOT variable removes that requirement. Finally, he added recursive schema traversal so deeply nested CRD fields, including oneOf, allOf, and anyOf, are fully processed.
What the Updated Workflow Looks Like
Contributors now clone the Kubernetes website repo and the Kubernetes repo to any folder, with no renaming required. They set build variables, run one command to update the API spec folder, then run make copy-api. The output includes index.html and nav_data.js. From there, a local container serves the finished API reference docs. The documentation itself was also updated from GOPATH-based instructions to a standard git clone approach, matching how Go projects are structured today.
Goals: Fewer Manual Steps, More Contributors
SIG Docs wants new contributors to build the reference docs without hand-holding. Right now config.yaml still needs manual edits, and release version numbers must be entered by hand. The team wants the generator to infer those values from the repo. The docs sub-team previously ran generation independently but stopped because the tool was too unreliable. With the recent fixes, handing that work back to them is possible, but more changes are needed first.
The Architecture Problem: Bash Calls Python Calls Go
The reference docs generator is a Bash script that calls Python that calls Go. Five engineers built it over several years, each with different architectural ideas. The result has no consistent design and, until Lavish’s fix, no error handling. Kat Cosgrove’s preferred next step is containerizing the tool so contributors stop installing a pile of dependencies locally. The team is also open to a Python-only rewrite, since Python handles text parsing well and Bash and Go may be unnecessary. Incremental refactoring is preferred over a full replacement, because the docs must stay online across all three annual releases.
Q&A
What does the generator take as input? It reads the Kubernetes/Kubernetes repo and processes the OpenAPI schema, doing a git pull of the full codebase before generating output. ▶ 13:15
Why is the generator so complex compared to other projects? The team inherited it. The last successful run under the old process was in 2021, and it was maintained by one person at a time, patching rather than redesigning. ▶ 14:59
What advice applies to operators and CRD maintainers generating their own docs? Keep it simple. Python parsing text to JSON or HTML is enough. The Elastic Kubernetes reference generator works well for Go-based operators and accepts Go templates for output formatting. ▶ 18:26
Is SIG Docs open to a full replacement of the generator? Incremental refactoring is preferred. A big rewrite is more prone to failure, and the team does not know the legacy well enough to safely replace everything at once. ▶ 21:25
Notable Quotes
it is I’m not kidding. a bash that calls Python that calls Go. Okay. It was developed over the course of years by a sequence of I think like five people, right? Kat Cosgrove · ▶ 11:30
our largest shame as a SIG is that we’re SIG docs and our own tool was undocumented like Kat Cosgrove · ▶ 19:28
I would say keep it simple stupid uh would be it. Um, I think part of why the reference docs generator is the way it is is because we overengineered it. Kat Cosgrove · ▶ 18:26
We inherited this. That’s the right answer. Rey Lejano · ▶ 14:59
Key Takeaways
- A missing
nav_data.jsfile and silent errors inwriter.gobroke API reference builds for four years. - The hardcoded
k8s.io/kubernetesrepo path is gone; contributors can clone anywhere usingK_ROOT. - SIG Docs needs Go and Python contributors to containerize and incrementally refactor the generator.
About the Speaker(s)
Kat Cosgrove is Head of Developer Advocacy at Minimus and a tech lead for SIG Docs. She also serves on the Kubernetes steering committee and owns the release team sub-project. Her focus is approachable 101-level content and the history of DevOps and cloud native technology.
Lavish Pal is a computer engineering student from India and an LFX Mentee at Kubernetes. He contributes to etcd and Kubernetes and was part of the Kubernetes release team for v1.32. His mentorship produced the four fixes to the API reference generator described in this talk.
Rey Lejano is a Solutions Architect at Red Hat and co-chair of SIG Docs. He contributes to SIG Security, Release, and Contributor Experience, and has served on seven Kubernetes release teams, including as Release Lead for 1.23 and Emeritus Adviser for 1.25.