(Providing documentation the OpenShift way – Part 4)
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.
The Build Pipeline
Looking at the generic asciidoc s2i builder first, we want to have a nice build pipeline. The pipeline uses the built in jenkins of OpenShift to run the actual build, deploys a test docpod (using the asciidoc-s2i-builder documentation for these tests). If the docpod runs (which means that the readiness and liveness probes can access the index.html on the pod) the test succeeds and the generated image gets labeled „latest“.
The pipeline uses the second build definition for the actual build. That one uses the dockerstrategy as pointed out in part 2 of this blog series. Result is the generic s2i builder with the label „test“. Then the test deployment is run (using the documentation template we discuss in a few seconds). If that succeeds, the result is labeled „latest“ and can be consumed by other projects.
If you want to grant access to the generic s2i builder to all projects, you need either grant this access to the building namespace you use for this pipeline or you create an imagestream in the namespace „openshift“ that automatically pulls the „latest“ tagged image from your building namespace. I provide a small sample in the github repository for this builder.
https://github.com/klenkes74/openshift-asciidoctor/blob/master/asciidoctor-s2i-openshift.yaml
Last not least you can create the webhook to start the pipeline. Calling „oc describe bc/nginx-asciidoctor-base-2.0.9“ will provide the link to use for the webhook(s). Don’t forget to replace <secret> by the actual secret you chose (if you forgot, you can look it up in the WebUI, but that is another story to tell).
The Documentation Template
Now we can take a closer look to documentation.yaml – this is the template for the concrete documentation. It generates all the little objects needed.
You will need it in the building environment of the asciidoc s2i builder (to get the tests working) and you need a slightly modified version in the namespace „openshift“ for consumption by all other projects. The little change is, that the builder pod is not loaded locally. You need to set the namespace to „openshift“ in the build config. And that’s all. Now you can use the „browse catalog“ to create your documentation pods needed for your project(s).
This article is part of the small series:
- Part 1: Providing documentation the OpenShift way
- Part 2: Creating the s2i builder with ASCIIDOC generation software included
- Part 3: Creating the documentation site
- Part 4: Bundling the components for OpenShift