As a developer who maintains a couple of Kubernetes controllers and operators, keeping those compatible with the current Kubernetes releases can sometimes be a pain. I often ask myself questions like
Since when is
Is this API over here still supported?
For the last few years I either checked the Kubernetes source code repository or looked at the generated
API documentation. This was cumbersome and so I had the idea to collect all this information in one single place and offer a nice
timeline view of each and every Kubernetes core API. Thus,
kube-api-timeline was born and later renamed
kube-api.ninja (because that TLD is cool and relatively cheap).
Where the data comes from
Originally I dumped the required data from a running Kubernetes cluster: Using kind I was spinning up a cluster and then use Kubernetes’ Service Discovery API to extract all available API groups, versions and resources.
However this had the downside of being slow and requiring
kind for all Kubernetes releases. But would I nowadays
be able to even spin up a Kubernetes 1.0 cluster?
kind certain can’t do it.
For these reasons I later refactored everything to just use the
swagger.json spec that is available both via
Service Discovery API (at
/openapi/v3), but also as a simple JSON file right in the Kubernetes repository. Parsing the Swagger spec and extracting
what actual API types are is a bit finicky, but once coded it’ super fast.
This works fine for all Kubernetes releases after 1.5, but before that Swagger 1.2 was used and since these releases will definitely not change anymore, I manually extracted the necessary data and saved me some coding efforts.
How the site is built
All of it was written ad-hoc, so there is no well-known static site generator to be seen. Instead it’s a bunch of home-grown Go programs that parse the Swagger specs, combine them into a timeline and spit out HTML.
I wanted to include the generated API documentation for every Kubernetes release. Primarily because I had bookmarks to them on the Kubernetes website, but those API documentations were regularly cleaned up and documentation for older releases is not available anymore.
At first I embarked on a journey to the Web Archive, in order to cobble together the documentation for older
Kubernetes releases. However this turned out to be trickier than expected, because the JS/CSS used in the API
documentation is not versioned and figuring out when the
style_apiref.css changed was super annoying and tedious.
Additionally the API documentation is not dark mode-ready and so I felt that visitors on kube-api.ninja would be annoyed by a sudden bright white browser page when they leave kube-api.ninja. That is why I contributed some work upstream in the reference-docs to make the documentation look a bit more modern and also come with a dark mode.
Thankfully I encountered super nice maintainers and so getting all my changes into the upstream repositories was quick and painless. The result can be seen now also in the official documentation on kubernetes.io.