Documenting Jenkins on Kubernetes Introduction
I’m thrilled to announce that I will be participating in Google Season of Docs (GSoD) 2020 with the Jenkins project. I started contributing to Jenkins documentation during the technical writer exploration phase for Google Season of Docs 2020 and I must say, my journey so far has been nothing short of amazing majorly because of the supportive community behind this project. I chose the Jenkins project because I understood this project from a user point of view as I had been exposed to setting up, configuring, and using Jenkins to automate CI/CD processes. I piqued interest in two of Jenkins project ideas, Plugin documentation migration and update and Document Jenkins on Kubernetes, submitted proposals for these two projects and to my utmost joy, the latter was selected.
In this article, I’m going to be explaining what my selected project is about and why this project is important to the Jenkins community and its users.
Introduction
Kubernetes is a platform-agnostic container orchestration tool created by Google and heavily supported by the open-source community as a project of the Cloud Native Computing Foundation. It allows you to use container instances and manage them for scaling and fault tolerance. It also handles a wide range of management activities that would otherwise require separate solutions or custom code, including request routing, container discovery, health checks, and rolling updates.
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 for the following reasons:
-
It is open-source and free.
-
it is user-friendly, easy to install and does not require additional installations or components.
-
Jenkins is also quite easy to configure, modify and extend.
-
It deploys code and generates test reports.
-
It also boasts a rich plugin ecosystem. The extensive pool of plugins makes Jenkins flexible and allows building, deploying and automating across various platforms.
-
Jenkins can be configured according to the requirements for continuous integrations and continuous delivery.
-
Jenkins is available for all platforms and different operating systems, whether it is OS X, Windows or Linux.
-
Most of the integration work is automated. Hence fewer integration issues. This saves both time and money over the lifespan of a project.
The following reasons have made Jenkins on Kubernetes a popular theme for Jenkins users, however, there’s currently no central location for documentation describing Jenkins on Kubernetes, thereby making it difficult for Jenkins on Kubernetes users to navigate and find information. This project would create a new Kubernetes Volume on Jenkins.io which would describe the concepts, techniques, and choices for Kubernetes users running Jenkins.
Current State
There are a lot of presentations and articles about running Jenkins on Kubernetes, however, there’s no central location for describing Jenkins on Kubernetes. This makes it difficult for:
-
Jenkins on Kubernetes users to navigate and find information
-
Track, update and maintain information on Jenkins on Kubernetes
Project Improvements
To solve the existing issue with Jenkins on Kubernetes documentation, a new Kubernetes volume will be created on Jenkins.io. This Volume is going to aggregate user guides, information on cloud providers and demos on Jenkins on Kubernetes. You can find the proposed contents for the new volume here. Feel free to comment on any suggestions you might have in the proposed content doc.
This project will also provide 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 using the Solutions page
-
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 will produce and release documentation in bits but continuously based on popular questions, feedback and area of interests gathered from the community and users.
Project Timeline
Find below a summary of the project timeline.
Community bonding (August 17 - September 13)
-
Set up a communication channel and time (due to time difference).
-
Refine my goals and set expectations on both sides.
-
Learn more about the community and Jenkins.
-
Gather and thoroughly study existing resources that will be useful and helpful to the project.
-
Pre-planning of the project
-
Contacting Stakeholders and onboarding contributors
Documentation Period
This period is going to be focused on creating contents which include user guides, tutorials, demos, etc. for Jenkins on Kubernetes. Some of the topics to be covered include Installing Jenkins on Kubernetes, Administering Jenkins on Kubernetes, Cloud providers and much more.
Documentation Timeline
1st Month (September - October)
Some basic prerequisites for installing jenkins on kubernetes include docker, a kubernetes cluster, and optionally Helm or the Jenkins Operator for Kubernetes.
Helm is a package manager which automates the process of installing, configuring, upgrading, and removing complex Kubernetes application. A Helm chart defines several Kubernetes resources as a set. Helm can make deployments easier and repeatable because all resources for an application are deployed by running one command.
Helm has two elements, a client (helm) and a server (Tiller). The server element runs inside a Kubernetes cluster and manages the installation of charts. With Helm, configuration settings are kept in values.yaml file separate from the manifest formats. The configuration values can be changed according to application need without touching the rest of the manifest.
On the other hand, the Jenkins operator is a Kubernetes native operator which fully manages Jenkins on Kubernetes. It is easy to install with just a few manifests and allows users to configure and manage Jenkins on Kubernetes. To run jenkins-operator, you need to have a running Kubernetes cluster and kubectl installed.
The Jenkins Operator provides out of the box:
-
Integration with Kubernetes — preconfigured kubernetes-plugin for provisioning dynamic Jenkins Slaves as Pods
-
Pipelines as Code — declarative way to version your pipelines in VCS
-
Extensibility via Groovy scripts or Configuration as Code plugin-customize your Jenkins, configure OAuth authorization and more
-
Security and Hardening — an initial security hardening of Jenkins instance via Groovy scripts to prevent security vulnerabilities
In the first month, the focus will be on documenting an introductory section. This section will include but is not limited to Setting up Kubernetes cluster, Installing Jenkins on Kubernetes, exploring the various approaches by which this can be achieved such as using helm package manager or the Jenkins Operator as explained above and Administering Jenkins on Kubernetes.
2nd Month (October - November)
In the second month, the focus will be on documenting how to setup up CI/CD pipelines using Jenkins and Kubernetes on different cloud providers. Some of the cloud providers we will be looking at include but are not limited to:
-
Amazon Web Service (AWS)
-
Azure Kubernetes Service
-
Google Cloud
3rd Month (November - December)
In the final month, the focus will be on creating demos and tutorials, submitting project report, evaluation of mentors and finally, publishing a report of my experience as a participant in Season of Docs.
Conclusion
Jenkins community is actively working towards improving its documentation to create a better experience for Jenkins users and invites technical writers to join the community and contribute to the Jenkins on Kubernetes project.
To contribute to the Jenkins on Kubernetes project, simply join the Jenkins documentation Gitter channel and drop a message, you can also find the Google season of docs office hour notes and recordings for Jenkins on Kubernetes here. GSOD office hours take place twice a week on Mondays and Thursdays between 6pm GMT+1 and 7pm GMT+1, if you would like to be part of these meetings, you can indicate interest in the Jenkins Documentation Gitter channel and we would be happy to have you.
If you are also a newcomer and would like to contribute to Jenkins, documentation is a great place to contribute. A lot of small patches can be done from the GitHub web interface even without cloning repositories locally. You can find some good first issues to get started with here.
Additional Resources
-
Google Season of Docs on jenkins.io
About the author