GSOD Project Report: Document Jenkins on Kubernetes
Jenkins is the world’s leading open-source automation server used by companies large and small around the globe to implement continuous integration and continuous delivery. Kubernetes is a portable, extensible, open-source platform for managing containerized workloads and services, that facilitates both declarative configuration and automation. Kubernetes is compatible with the majority of CI/CD tools which allow developers to run tests, deploy builds in Kubernetes and update applications with no downtime. One of the most popular CI/CD tools now is Jenkins thereby making Jenkins on Kubernetes a popular theme for Jenkins users.
During the Google Season Of Docs program, I worked with the Jenkins organization on the project - Document Jenkins on Kubernetes. The original proposal for this project can be found here.
Project Goals
After my proposal was accepted by the Jenkins organization, my mentors and I agreed on the expectations for the Google Season of Docs project. The goal of this project was to create a new Kubernetes Volume which would describe the concepts, techniques, and choices for Kubernetes users running Jenkins thereby providing the following advantages:
-
Improve the user experience of Jenkins on Kubernetes users by giving them a one-stop-shop for information on Jenkins on Kubernetes.
-
Make it easy to track, update and maintain information on Jenkins on Kubernetes
-
Reference the existing community documentation for Jenkins on K8s (plugins and tools/integrations).
-
How to guides, tutorials and explanations of concepts and techniques in Jenkins on Kubernetes.
-
Just-In-Time documentation which means that rather than documenting every feature comprehensively, we produce and release documentation in bits but continuously based on popular questions, feedback and area of interests gathered from the community and users.
Community Bonding: Planning the solution
Find below an outline of my activities during the community bonding phase:
-
Setting up communication channels: meetings, mailings, chats: My mentors and I agreed on the right time and channel for communication due to time difference. We agreed to meet twice weekly, on Mondays and Thursdays at 7:00 PM GMT +1 and use Jenkins documentation gitter channel for other communications.
-
Contacting Stakeholders and onboarding contributors: The project was announced on social media and different Jenkins channels. I wrote a blog post to announce the project and created a project page on Jenkins.io.
-
Knowledge transfer: I and my mentors planned knowledge sharing sessions and fixed tentative dates based on the availability of the trainers. My mentors also shared useful resources to help me prepare for the project.
-
Getting permissions: I and my mentors agreed I didn’t need any special permissions from the beginning, however, this topic was left open for discussion if the need arose later on in the project.
-
Pre-planning of the project: I refined my goals and set expectations with my mentor and also learned more about the community(Jenkins). I also had to ensure that the proposed documentation structure I drafted was in line with the goals of the organization so my mentors vetted it and we finalized on the proposed sections that I was supposed to work on.
Documentation Development Phase
Knowledge Sharing Sessions
During the development phase, my mentors hosted two knowledge sharing sessions:
Helm by Torsten Walter
See the slides
These sessions gave me an in-depth understanding of concepts and tools needed for the project.
Jenkins on Kubernetes Documentation Skeleton
At the application phase, I drafted a structure describing the proposed Jenkins on Kubernetes section. My intention was to use it as a guide during the implementation phase of the project, but when the development phase kicked off, my mentors and I thought of a better approach to creating a new Jenkins on Kubernetes section which was to add the Jenkins on Kubernetes contents to existing related sections for easier navigation and better user experience. An example of this approach would be creating the Installing Jenkins on Kubernetes section under the Installing Jenkins section rather than putting it under an entirely new section. With this new approach, I was assigned a task to create a skeleton with all the proposed Jenkins on Kubernetes sections on Jenkins.io and mark these sections as Work In Progress (WIP). The Plan was to use this skeleton as a guide throughout the GSOD Project. The Jenkins on Kubernetes skeleton PR can be found here.
Documenting Jenkins on Kubernetes
While working on this project, I had to do a lot of research and test all the documented steps locally before pushing the documentation out for review. I also made sure to use updated terms and terminologies where necessary like Controller instead of Master and Agents instead of Slave.
During the documentation phase, I was able to work on documenting Installing Jenkins on Kubernetes with three sections Helm, Set of Yaml files and Jenkins Operator. I also worked on creating a directory for Jenkins on kubernetes sample files in Jenkins.io repository, documenting Scaling Jenkins on Kubernetes and Jenkins on AWS which is still in progress.
Work Done
Pull Requests: All the pull requests I submitted to Jenkins.io documentation can be found here. This spreadsheet contains links to the published documentation on Jenkins.io. The spreadsheet also highlights the initial proposed tasks and the status of each of them.
Challenges
Using a Windows computer was a bit of a challenge for me. To run Jenkins.io locally, the project uses GNU/Make and Docker in order to generate the fully statically generated jenkins.io web site. The key tool for converting source code into the site is the Awestruct static site generator, which is downloaded automatically as part of the build process. To achieve this, I needed to have GNU/Make and Docker available on my machine. Docker was not a problem, but to achieve the latter, I needed to use Windows Subsystem for Linux (WSL). WSL had two versions WSL1 and WSL2. Using WSL2 would have been much more convenient, but my version of windows wasn’t compatible with WSL2 as it required Version 1903 or higher, with Build 18362 or higher for x64 systems. With this obstacle, I had to stick to making WSL1 work but I still couldn’t get this to work, a series of issues came up which I was able to pass through with the help of my mentors until I got stuck at permission issues. I raised the issue with my mentor and after looking through the issue with me and trying to solve it to no avail, he suggested setting up an Ubuntu VM in Hyper-V. This article helped me achieve this and that solved my problem.
What did I learn?
I learned a lot more about the Jenkins project, Kubernetes, helm package manager, Jenkins Operator and much more. This project also gave me the opportunity to work with cloud providers like AWS which was totally new to me and also learn from field experts through knowledge sharing sessions and weekly meetings with my mentors and org admin. My technical writing skill and communication skill have definitely become better and I owe it to this project.
Overall, contributing to the Jenkins.io project is an amazing experience for me. I have been using Jenkins, and the fact that I was able to contribute to the organization and collaborate with the community is an honor.
 | Zainab Abubakar Zainab is a software developer and technical writer who is passionate about contributing to open source, improving technical documentation and advocating for gender diversity in open source collaboration. She started contributing to Jenkins documentation during the technical writer exploration phase for Google Season of Docs 2020, and is currently working on Documentation for Jenkins on Kubernetes. |
