 All right so welcome to this Jenkins online meetup for Google season of docs. Documentation is code. Our documenting Jenkins on Kubernetes. I'm going to share my screen and let's take a look at some slides. So here's what we've got today. This is documenting Jenkins on Kubernetes and we're very grateful to have Xenob Avubakar presenting to us today. Xenob has been mentored for the last several months by a team of three of us from Jenkins documentation and we're looking forward to our presentation today on her experience with Google season of docs and what it means to do Google season of docs and what it's meant to her to do Jenkins on Kubernetes documentation. My welcome and then we're going to turn it over to Xenob and I'm going to stop sharing my screen and let it let you take over Xenob. Oops you're muted. Okay so let me know if you can see my screen. We can looks great. Okay so I'm going to start with presenting a slide just a little bit of information on the project overview what we're able to achieve then we'll branch to a short demo before coming back to discuss challenges lessons learned and then a Q&A session. So I'm going to start with the slides. Sorry let me just show you that. Okay so um about me um it developed at inter-swich um book Nigeria inter-swich is a fintech um company Nigeria um also an open source um the open source program's manager for Sheikode Africa a non-profit organization um specialized in um creating opportunities for women in tech and I'm also a technical writer you can find me on Twitter and github at Sheikode. So um today we're going to be discussing the problem statements for this project and what informed this Google season of docs project. We're going to look at how we plan the solution. I broke down this part into two because it was majorly two phases for me that's before getting accepted into Google season of docs what were the things I did to prepare for this project and what were the things we did to prepare after getting accepted before the documentation development phase. We're going to look a little bit at the documentation development phase what did we do before we branch to a short demo discuss challenges lessons learned and a Q&A session. So let's start with the problem statement. So um when I started contributing to Jenkins during the technical writer exploration phase there was no central documentation for Jenkins on Kubernetes and this was the problem. So um users and Jenkins on Kubernetes users did not really have any central location on Jenkins.io to find information relating to Jenkins on Kubernetes and that was why we decided to work on this project considering that Jenkins on Kubernetes is a popular team team for Jenkins user and why we took up this project. So um planning the solution. Um before I got accepted um to Google season of docs um I went through the list of project ideas and I was particularly um entailed by this particular project to document Jenkins on Kubernetes. So um the first thing I did was to make some research um um find out um a lot about Jenkins on Kubernetes see if it was something I could actually do I could actually take up. So um one of the reasons why I chose this project was because um I had an interest in Jenkins because in the organization where I work we currently use Jenkins and spinnaker for our CICD pipelines and I had a thrill in setting up Jenkins when I had the opportunity to. So um seeing this project was more like an opportunity for me to understand more of Jenkins and to get more into um DevOps. So I did my research and um I worked on my project um let me just um show you um something so it's not like I'm just talking talking talking. So um okay so this was all my project proposal looked like in my while working on my project's proposal some of the informations I um put in there was um project abstracts what I thought was the problem um with Jenkins on Kubernetes um documentation on Jenkins.io I did an analysis and in this analysis what I did was to create a sample structure of what I thought um the Jenkins on Kubernetes documentation should look like on Jenkins.io. So um in this structure I gathered um all the links I had um all the links that I had found from my research I gathered them into the structure to help me um work on the content when the time came. So after working on the structure um yeah after working on the structure I submitted my proposal. So um when I got accepted into Google Season of Dogs this were the things we did um in preparation for the project. So pre-planning of the project um in this um phase this was where we um discussed and agreed on communication channels um this was where we um discussed um things that would probably be necessary for the project like permissions and other useful um tools or resources that would be um useful for the Jenkins on Kubernetes project. After that we discussed knowledge transfer what were the um knowledge um sessions that I was going to need what where was I lacking um in knowledge to be able to properly work on this project and this was where we agreed um to have knowledge sharing sessions on help and Cata Coda during the Google Season of Dogs program um refined project goals. So here we kind of expanded um on my proposal and the structure I had created. So we looked at it I am my mentors looked at it and we decided on the content that were necessary to be there and the ones that were in there and we kind of like um also um rated it according to the most important so I could start working on the most important and go down the list. Then finally we worked on um announcing the project here and we announced it on social media handles. I also wrote um a blog post to announce the Jenkins on Kubernetes project and what this project was going to entail. Now during the um documentation development phase um I broke this down into three. So the first part is the knowledge sharing sessions. So um here I had um the opportunity of having two knowledge sharing sessions from two um very very knowledgeable people one of them being um my mentor and Ogadmin and the other person um Tostin. The first person Maki Jackson is my mentor. He gave a session on Helm and Cata Coda and um the second person Tostin was is a member of Jenkins community and he also gave me a knowledge um sharing session on Helm which really helped me in properly documenting Jenkins on Kubernetes. After that I and the mentors worked on a skeleton. So um this was where the initial structure that I created and I am my mentors refined during the planning phase. This was where it actually came to life. So what we did in this um session in this um part was to create a skeleton on Jenkins.io with all the content that we actually intend to document and map them with work in progress um tags. So the idea was for us to continue um updating updating this skeleton as time went on. So um on Jenkins.io here I'm just going to show um some of the sections that we added to Jenkins.io during the um in the skeleton. So we're able to work on some during the Google Season of Dogs program but um some of them are still currently pending which we still intend to complete as time goes on with um the help of the mentors and community and other people out there who would like to contribute to Jenkins on Kubernetes. So um under the installing Jenkins session this session was one of the sessions um was one of the sections we added um under using Jenkins um no sorry that would be managing or system administration. Okay so under uh system administration yeah. So um this is an example of a section that we were not able to complete during the Google Season of Dogs program as you can see is still showing um work in progress but um hopefully with time we intend to complete this. Um then um lastly we went on to um I went on to start working on the actual documentation. So this was where um I worked with the mentors to add um contents to the skeleton that we had previously um created. So um now we're going to go through um a short demo um on installing Jenkins on Kubernetes using Jenkins operator and in this demo we're going to use the documentation that I worked on. We're going to follow the documentation through and through and see that um the documentation actually works. Yeah. Okay so um under the installing Jenkins section um so um before I go to the demo I'd just like to give a brief summary of the sections that I was able to add. So um I was able to add um section on installing Jenkins on Kubernetes and in this section it covers um three methods. We have um using Helm using um using a set of YAMU files and um using the Jenkins operator. So in this um demo we're going to be um working with the installing Jenkins with Jenkins operator section. So I'm just going to bring up my terminal. Yep so we can get right to the demo. So okay um so first of all what's the Jenkins operator? So the Jenkins operator is a Kubernetes native operator which manages um operations for Jenkins on Kubernetes. It is easy to install with just a few manifest and it allows users to configure and manage Jenkins on Kubernetes. So some of the advantages that um the Jenkins operator provides is that it provides um an out of the box integration with Kubernetes that you have the um Kubernetes plug-in pre-configured. It also provides um pipeline as code that's a declarative way to version your pipeline. Then extensibility via groovy script and configuration as code and finally it provides security. So um for you to use um the Jenkins operator to install Jenkins one of um the pre-precise is the Jenkins operator. You need to have the Jenkins operator installed on your local machine. So um to install the Jenkins operator you need access to a Kubernetes cluster and if you don't already have access to a Kubernetes cluster don't worry we have a section just above um clicking this link okay I think we have a section just above here um that shows um how to create yeah a Kubernetes cluster. So if you don't already have a Kubernetes cluster you could just come up to this section and follow the steps here to um achieve that. So I already have um that installed on my PC so I'm not going to need to do that. So the next thing we're going to need to do is to configure a custom resource definition and um the custom resource definition um enables users to add custom APIs to your Kubernetes cluster which can be used like any other native Kubernetes object. So um to install this we are going to use um CRD file from the official um Kubernetes operator repository. So um this is a command we're going to run so I'm just going to run this on my box to install that. So I'm just going to wait for that to yeah so um I hope my terminal is not too tiny. I just want to make sure that we can see the content on the documentation and also my terminal as I go. So um from the output here we can see that it has installed two um um CRDs here Jenkins dot Jenkins dot io and Jenkins image dot Jenkins um io. So after doing that successfully we're going to deploy Jenkins operator. So to deploy Jenkins operator um there are two options here that we could use. We could decide to use YAML files or the Helm chart. But um for this demo I'm going to be using um Helm chart to install um the Jenkins operator. So what's a Helm chart? A Helm chart is a package package manager for Kubernetes and its format is called a chart. Helm charts um basically provide a push button deployment for um push button function to deploy and delete applications. So it makes um the adoption of Kubernetes apps easier. It helps you to manage your Kubernetes applications um easy. So um for you to use Helm I need to mention I forgot to mention this. So for you to use Helm you need to make sure that you have Helm installed already on your PC4. In my case I already have Helm installed but if you don't um there's a link in the documentation. Clicking this will take you to Helm's um doc um will take you to a documentation yeah on how to install Helm. So um since I already have um Helm installed I'm just going to go straight to um configuring Helm on the documentation. Yeah so what is it? Yeah exactly. So since I already have um Helm installed okay so before I configure Helm I'll create a namespace for the operator. So um um also on the documentation we have a section that explains um how to create a namespace. So I'm just going to run that command cube CTO create um namespace. So I'm going to be doing my deployment in the Jenkins namespace. So Zina are you okay if if I we ask questions as you're proceeding as panelists or would you like to just oh your your headset. Sorry I'll bother you later. You can you can ask the questions also if you'd like to whichever one is fine with me. Actually this is great you just keep going you're doing wonderfully. All right thank you so um from my terminal here we can see that my namespace Jenkins has been um created successfully. So I'm just going to configure Helm. I'm going to add um Jenkins decubanitis operator Helm charts. So I'm going to do that by running this command here. Okay so um I already have this installed in my book so that's why I didn't install Jenkins already exists with the same configuration. So if you don't already have this before it's going to show you that your Helm chart has been added. So I'm going to move on to the next step which is to install the Jenkins operator in the Jenkins namespace and we're going to be using um so okay so I'm going to creating this in the namespace I created Jenkins. Okay so um when you're installing installing um with Helm charts so um you also have the option of um customizing why you install so you can add labels you can add um annotations yes so you can see that my Jenkins operator was successfully deployed. So um as I was saying you can add um labels you can add um annotations to customize your installation that's um to customize the official um Jenkins value. In this installation I've used um the values in the official Helm charts um repository. I didn't make any changes or why you're doing yours depending on your needs you can um customize the values um using labels while deploying. So after we successfully installed the Jenkins operator the next thing is to now deploy our actual um Jenkins instance. So to deploy this we'll need um a YAML file um a Jenkins instance YAML file containing the details the name the image we're going to use for our Jenkins and other information for our Jenkins instance. So on my PC um as you can see I already have my Jenkins instance file here um so um there are a number of you could use um whichever IDE or text editor you prefer to edit your YAML files but um I just have a preference for using um visual studio code for YAML files but there are other ideas you could use out there like um IntelliJ and others and if you like to format your file your YAML file there are extensions or even online formators that you could use to properly format your YAML file. So um and I'm currently in the directory where I stored my um Jenkins instance. So yeah so when I checked you could see that my Jenkins instance. YAML is stored in this directory so I'm good to go next thing I'm going to do is to create my deploy Jenkins using this file. Okay and I'm going to do this in the Jenkins namespace I created. So we can see that my Jenkins instance has been has been created so to um show that this is Jenkins. Yes so we can see that my Jenkins example instance is up and running my April Jenkins or April instance is running my Jenkins example um instance is also running. So this Jenkins example is the instance I just created. So if you check the file you can see that the name of the file here is example. So that's why it's Jenkins example if you named your own file Jenkins is going to be Jenkins Jenkins if you named it Jenkins key is going to be Jenkins Jenkins key. So depending on what you named it so um my pod is not here ready because normally when you do this um Jenkins is going to it's going to install again so until this is pod it's going to be this way. So let's see if I can see the logs if it's possible for me. So we can see it's installing plugins and this is not done yet so that's why our pod is in that state. So um for you to be able to access your Jenkins obviously you need to get the login credentials to do that and to do that we're going to run this. So um secret name here Jenkins operator credential name. So credential name here being the name you used in your Jenkins instance file as I explained earlier. So in this case my credential name is going to be example. So I'm going to run this um to see to get my credentials. I assume see now that until the plugin downloads are complete it probably has not yet started the Jenkins process has it? I thought that the plugin downloads. So um yeah so um mark your right there. So because um my plugins has not installed and this takes um this plugin installation takes a lot of time here because of my internet internet connectivity and all that but um once um the plugin is installed successfully you should be able to get your credentials and you can connect to Jenkins using either mini-cube through the service or you can put forward and access the actual Kubernetes cluster. But I'm just going to go ahead and um explain something about uh readiness proof before I end the demo session. So we're going to describe Jenkins um Jenkins port and see what um the information that we have on the port looks like um successful. So I'm saying it's expected let's check it once again. Okay so it's still not up yet and I'm going to assume that it's still um installing. So um what I wanted to explain is there are some instance where um when you describe your port here because um Jenkins is not yet ready to handle requests it's still um um installing plugins. You might see a warning here or an error here that tells you readiness proof failed unable to connect. So what this means is that um Jenkins is up but it's not yet um ready to handle requests. So um basically Kubernetes has um three types of health checks um the start-up check the readiness check and the liveness check. So the start-up check is um basically to check if um the application has started and if it has it moves to the readiness group. So the readiness check um checks if the application is ready to handle requests. If it's ready then Kubernetes sends um request to this port but if it's not then um Kubernetes keeps trying. So um when an application fails a readiness check Kubernetes doesn't delete the port it just um keeps retrying until the port is ready to handle um request. Why um the last one which is a liveness check is when Kubernetes checks the application to see if it's actually up. So when an application fails a liveness checks Kubernetes um deletes that port and creates a new instance because it's assumed that the application is dead. So um I'm going to end my demo session here and yeah so we're going to continue with this slide. So um what are the challenges I faced during um during this project? So I think the major challenge I faced was um using a Windows laptop. So um there were a lot of um I had some difficulties running some commands but um the good side of this challenge is that it gave me the opportunity to actually work on different environments and test the documentation on different environments to ensure that um whoever is using a Windows PC or a Linux PC would be able to scale through and use the documentation without um having any issues. So if you go through the installation guide you see um that there are some places where I put options like option one and option two. These are um instances where probably I had issues using one option on Windows and it worked on Linux or I had issues using one option on Linux and it worked on Windows. So um what are the lessons learned? I learned more about Jenkins project. I learned more about Kubernetes, Helm, Jenkins or Grito and this project also helped improve my technical writing skills, communication skills because I had to communicate with my mentors um constantly and even from um the exploration phase when I was working on my proposals on my structure I had to share the structure with members of Jenkins community. My colleagues at work who I knew were um good at um who who are good at DevOps and who I knew used Jenkins on Kubernetes um properly. So I shared the structure with them, I shared my proposal with them to review and um make comments on and suggestions on what information they think would be best to add to this documentation. So um this project definitely improved my um collaboration skills also. So um that'll be all from me so um you can ask your questions and I'll be happy to answer them and if I can't I know one of my mentors will be able to help me. Thank you. Thank you Zinab. So we do have one question online actually and this one I confess we may have to call on the mentors I'm not sure so the question asked was how how can we manage adding new plugins and upgrading plugins after the Jenkins installation is done? Can we manage Jenkins plugins as code? So do you want to give some commentary on that? Do you want to call for mentors? What's your preference? Okay so um I'll just give a little so my mentors can help me complete it. So I know when you're using Helm to install Jenkins as I said um there are two um instructions you can use you can use that either use the Helm install or Helm upgrade. So with the Helm upgrade command you can use that to um add additional plugins and even additional functionalities to your Jenkins instance. So um I think my mentors can take two. You are you are exactly correct if you add that to your uh your template for your charts in Helm you can then run the Helm update and it will update those plugins. You could add a little bit extra and keep that in git and use git op so any time there is a change to the repo some type of webhook and delivery will push those changes out to a given cluster. Thank you. Okay so so it is managing plugins as code works and and do I then maintain specific versions of those plugins in a list somewhere? How does how does that feed how does that feel to the developer who's trying to trying to get a new plugin upgraded in their Kubernetes installation? You could some I've seen some individuals use like requirement text files that they'll put the versions in and they can have their Helm chart call that that is totally doable. Okay thank you. Now Xena for me you mentioned that you were running on Windows and I confess I'm very commonly used to seeing people run on Linux or macOS and not as frequently on Windows running Kubernetes and yet you showed us the entire demonstration on on Windows. Any other insights you want to share with those users who are Windows users about hey do this or do that get this experience or that experience? Well for me to be able to use Windows I think one thing that helped me was actually a lot of research trying this trying that and I actually had to when I see a particular command in Linux I try to research if there's a corresponding command in Windows and if there's not I find an alternative so for instance there is a command here I'll just go to Jenkins.io sorry yeah so okay I just want to give an example of how I was able to work around some of the issues I had okay so yes for instance this section on getting credentials so when I try to run this command on my Windows box I get an error that base64 is not installed or does not exist or something like that so what I just do is I take out the base64 part and actually get the secret in base64 and I just go to base64 encode.com and I decode the secret by myself just to get work around that. I know there probably might be better solutions but that's just basically how I do it so when I find this tumbling book I just do some research and hopefully we're able to work around that. Excellent thank you thanks thanks very much the Windows is so were you an expert in Kubernetes before you started this project what was it like for you to begin on a project like this were you already deeply skilled with Kubernetes and so it was just doing what you'd already done or did you have a bunch of things you had to learn? So I won't say I was deeply skilled though I wasn't at least I had some background knowledge of Kubernetes because again where I work currently at InterState we use Kubernetes a lot that's where we deploy our application so I'm familiar with creating deployments creating config maps doing some edits literally to commands like that so I was already familiar with that before I started working on this project but obviously when I started working on this project I had to do more research on Kubernetes try and learn more learn more about things like health checks, liveness probes and all that so those were no really things I was so familiar with before this project but this project helped me understand better. Thank you so now the install guide lists three different forms of install methods helm, base yaml and operator are there any guidance you want to give the audience on when they would choose one of those versus the others particularly for somebody who's not a kubernetes expert me for instance I'm not expert in this is there one I should prefer rather than another? Okay so um well I'll just say this is um a personal evaluation I'm not going to say is um general so um what I think is before you um decide on which method you want to use you need to analyze your mid-term goals do you want to be able to deploy faster do you want to change your continuous deployment pipeline regularly or do you just want something simple um to begin with and then focus on the details later so when you're able to answer these questions then you can then decide on okay hey I'm going to use yaml files because if um you're going to be using yaml files I think I'll advise that it's on small project cause you you know you're going to have to be setting up things like your deployment, service, ingress, persistent volumes and all that you're going to have to have to be applying um files for all that and if you have a lot of um apps that you're managing on kubernetes or you have a lot of things that you want to do or your project is very very large at the end of the day this could um become difficult to manage so depending on how large your application is or the project you're working on so you can decide um on which process because um things like helm charts and Jenkins operator makes it easier for you to manage your Jenkins installation rather than doing it um with the yaml files where you have to um manage this um files separately yeah excellent okay so so ease for ease I would buy us towards helm or the operator but if I want to control every last detail for a little prototype yaml files okay thank you thanks very much yes now were there things that surprised you while working Oleg did you have a question uh no questions I just wanted to thank for this project because yeah documentation for Jenkins and Kubernetes is very important it's part of the public projects roadmap um yeah there was great progress over the past months so thanks a lot for that thank you I have some questions about uh computing experience but yeah we can talk about it later so I'll let that put mark uh finish these questions actually that that those questions are great as well so for me I'm very interested in in your experience Zina contributing and any guidance you wanted to offer to others about what they might do as they consider contributing as they consider helping the Jenkins project or some other open source project okay so um well surprises I wouldn't really say surprises just that I had some issues that I didn't envisage from the beginning which is normal with every developer you know that um when you're writing code or you're working on anything technical um issues tends to come up that you didn't plan so I'll say yes I had that but surprises well I don't know because maybe because I I already knew okay I was working with Kubernetes and I already saw Kubernetes as a huge project and Jenkins another huge project so I already had expectations that I was going to see a lot I was going to learn a lot so I wouldn't say I was so surprised then um for advice on people that like to work on open source project I'll say um if you want to you need to be ready to do your research because um you don't want to get on the project and be asking questions that are already available um questions on information that is readily available for you already so you need to do your research first um try to engage with the community ask questions when you have issues it'll help a lot and try and cause I think when I try when I started contributing to open source um I was shy actually um to ask questions um I was in outreach year um 19 round and I think that was one of my takeaway from that program to ask questions there were times when I had issues even with things like Git and I felt too ashamed because I was like how would I be working on open source project and be having issue with something like Git even if I should be asking questions it's be something about projects not something about Git but the truth is we are always learning no matter how um experience you think you are issues will pop up along the way that you've not come across and sometimes you might have even come across them before but you can just remember how to solve it so it's important that um you ask questions you know how to ask questions it's important that you um learn to collaborate because there can't be open source without collaboration so um I think that's that's it for me research ask questions collaborate and write and also once you write um try and push it out for as much people as you can to review because when you finish writing it might look perfect to you but someone looking at it from another angle might see issues and things that you didn't see while you were writing so it's very important that um you um push out your work for people also to review thank you thanks for the detailed answer and yeah do you think uh google season of docs did you communicate with other technical writers or do you mostly isolated in the Jenkins community of how do you work for your sorry I didn't get your question okay did you communicate with other google season of docs technical writers or were you mostly independent during this project so I think it was mostly independent because I know um other google season of docs writers but with other projects so um what they were working on was not really related to what I was working on so um working on this project was majorly me mentors and um obviously I had some help from um other members of my organizations who were very knowledgeable in Jenkins and Kubernetes so I asked them for help when I needed it so yeah thank you so are there are there things that you see as sort of next steps you know things that you might see as next steps for documenting Jenkins on Kubernetes next steps for where should things go what any any things you want to suggest there or recommend hey we should be doing these things okay so um definitely we're still going to need more content on Jenkins or IO documentation we're going to need more contents on administering Jenkins on Kubernetes we're going to need more content on Jenkins on cloud then aside that also um some other um future plans good future plans will be to have a Jenkins on Kubernetes solutions page which could include um tutorials on Jenkins on Kubernetes using tools like um Katacoda where people could actually um work on the environment and get um that um experience of actually um working on an environment doing things with Jenkins on Kubernetes so yeah thank you so I think we're at a point where we may be willing to open up to the audience end the recording and and switch to open questions from the audience are there any panelists questions before we stop the recording and switch to open question and answer mode from the audience uh I this is Markey I would just like to say Xenob you did an amazing job super super proud of you also to the other mentors Mark awesome job uh round of applause all around thank you so much Markey and thank you very much to the mentors for being so so patient with me and being always ready to help it's really really motivated my success in this project a lot the fact that I knew that the mentors were always there when I needed help and um there was no putting me down I never felt bad at any point in time when I had issues because um the atmosphere the reception was very very welcoming thank you so much all right I'd like to echo Markey's um comments yeah because like a lot of what I was going to ask her about like getting started continuing writing in the project I think we did a great job of like explaining the process of how to work with the documentation and get out there and um the importance of working within the community and asking questions and stuff that was great and yeah everything was wonderful it was a great experience so congrats the documentation looks wonderful so thanks everyone thank you all right so I'm going to go ahead and stop the recording we what we'd like to do at this point is we intentionally stop the recording so that we can open it up for anyone to ask questions we'll make everyone live Xenob if you want to switch off the screen sharing we'll we'll just go and let the cameras work okay and and I'm going to go ahead and stop the recording then we can we can actually ask questions openly in the forum