kube-api.ninja

Background

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 example.com in v1 available?

or

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

One important aspect to me was to create a site that is as static as possible. Since a cronjob regularly checks for new Kubernetes patch releases (so I do not have to manually keep those up-to-date), I potentially rebuild the site at least once a month. From there it wasn’t difficult to make the decision to rebuild it every 6 hours. This makes it possible to even statically mark currently supported releases (the green columns on the site) with fixed CSS. There is no JavaScript on the site to check the current date and then perform calculations on that.

API documentation

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.