Kubernetes is not kubernetes. Every cluster is configured in a special way and offers additional features. Some of them are build in the distribution, like OpenShift contains for example a default ingress service (the router) – others are provided by the team maintaining the cluster. Or the maintaining team of the cluster decided not to provide certain features of k8s or the distribution used.
How do you communicate the feature set you provide to your customers. For a single cluster and a small group of users it’s easy: you explain it to your users. But the bigger the cluster grows and the more users you have, you find out: this does not scale. And adding multiple clusters in different versions, it becomes a mess.
But you could use a k8s feature to build a catalogue of features of the current cluster. You define the feature sets and add the installed features to the cluster and your users may query the cluster about the supported features of the cluster they want to use.
The k8s feature I’m talking about is the custom resource. Just create a custom resource containing the information you want to provide and add the features to the catalogue. Then the catalogue can be queried like this:
$ oc get ift
NAME GROUP VERSION AGE DOCUMENTATION
features-catalogue cluster-info 1.0.0-alpha1 1d https://github.com/klenkes74/k8s-installed-features-catalogue/
The last two posts described the creation of the generic s2i builder and the concrete documentation site. This blog post now will put all the pieces together and provide a nice package to use on OpenShift or OKD. You get the templates, the build pipeline.
For building the documentation pod, we need two components: the asciidoc html generator and the webserver for delivering the static pages later. There are several base containers published containing either the asciidoc generator or the webserver. I liked the converter published on https://github.com/asciidoctor/docker-asciidoctor. But that is only the generator part. On the other hand there are default bsic containers like httpd or nginx containing the web server part. Or, as third option you could use a ruby s2i builder as starting point and add both, Asciidoc and the web server later.
Documentation is one of the most hated part of the life of a developer. So the documentation is often the most neglected part of a project. At work I use Asciidoctor to write my customer documentation and it is quite acceptable. I loved LaTeX and Asciidoctor is an acceptable replacement for technical documentation – especially with the alternatives being google doc or word.