SIG Docs and You: The New Chapter of the Kubernetes API Ref... Kat Cosgrove, Lavish Pal & Rey Lejano

This talk discusses the challenges and improvements associated with the Kubernetes API reference generator, an essential component for documenting Kubernetes APIs. The speakers, who are members of the SIG Docs community, highlight the complexities involved in generating accurate reference documentation for various Kubernetes components, including the cube API server and the control plane. They explain their experiences with frequent failures in the generation process and the hurdles faced by new contributors. Key improvements include implementing error handling, simplifying the repository structure, and enhancing navigation features within the documentation. The speakers also express the importance of community involvement in optimizing the generator and share their goals to make the documentation process more straightforward and less reliant on manual configuration.

Hello everyone. Thank you for being here. I know this is one of the last talk and on the last day, so you are a bit tired, but bear with us and believe me, this is going to be really good one. So, here we are and sig docs and you, the new chapter of Kubernetes API reference generator. Before starting, here's a quick intro about mine. Hi everyone, I'm

Lavish Pal. I'm an LF experimenter at Kubernetes and at CD contributor. Hello everybody. My name is Kat Cosgrove. I am a tech lead for sig docs. I'm also on the Kubernetes steering committee and I'm the release team subproject owner. Hello, my name is Ray Lahano. I'm a co-chair of sig docs, a tech lead as well. I'm also a sig security subproject lead as well. So, this talk

is about the API reference generator. So, if you've used our documentation, um you know that we have a reference guide to all the APIs to uh to the cube API server, to cube control, and metric server, and other components as well. Uh so, generating these docs is during uh before write every release is usually very difficult. Uh so, someone from the release team, so for if you

don't know, Kubernetes releases three times a year, and one of my favorite uh hobbies is to look at the docs on the new alpha features and the graduating features as well. Uh part of the uh new docs is the API reference docs, and someone from the release team uh generates the tries to generate the the reference docs. Uh and you could see here there's a number of

dependencies. There are GCC, uh Python, Go, very specific versions as well, uh PyYAML, uh and a lot more. And the example here is the some of the commands uh to generate the cube the reference docs for the Kubernetes API. So, as you could see, it is quite complex, especially for someone who has not used it before. So, that's most time if you don't know the release team

does have a lot of new folks into into the project. So, this might be the very first time that they're looking at these steps and looking at these dependencies. So, we often get lots of failures. This example for me back in 5 years ago where I tried to generate some of the reference stocks and it failed. And this happens quite frequently for about the past 4 years

or so. And we also get a lot and we hear about it. So, this example is from Slack that hey, the API reference stocks for this for the latest versions is not updated. We also get GitHub issues on as well. And we know about this. I know a month before each release, I know that this is going to come. So, we hear about it and we we

do try to work on it to try to make it better. And this is where uh this project or this this talk comes about and we'll hand it off to Lavish. Yeah, so so building on that as we already really already shared that there will be some problem in running the Kubernetes API reference generator and like it fails regularly without any error or message and all. during

my LF X mentorship, I focused on improving some of those areas and I finished this one. Let me start with this one. So, this is one of the main step while when you are following all the process to generate the API reference stocks and when you run the make API command which is just generally used to generate the API reference stocks, the build would complete and generate

files like index.html but a file name navdata.js was missing, and this file is really important to navigate the API docs and the data. So, I end up finding that data for navigation was already there in the table of context, but it wasn't being written to a file. So, I did a So, I added a step to serialize that data into JSON, and that will write into navdata.js

file. And the next one is while I was digging into some code and find out that there will there are so many errors which is not so uh not easy to debug and requires some error handling there in the code. So, I implemented some error handling in the writer.go file then because when you run the reference generator, you will end up in so many errors, and you

will never know that what is failing there. And so now, after this pull request, you will get the clear message like what went wrong. And the another area uh where things were a bit confusing that how the tool look uh locates the Kubernetes repo because the build expected it to be in a fixed path like k8s.io/kubernetes, I don't know how most people actually clone it, and so

even with a correct step, the build can also fail. So, instead of trying to guess different paths, the approach was simplified by requiring a k8s root variable, and my intention was to add that you don't need to follow that step that you have to rename the k8s uh Kubernetes repo to k8s.io/kubernetes every time. You can just clone in a folder any at any location also. So, now

you will not not get any error, and your build will not fail after this pull request. And the another one is the generator was only handling some simple top-level structure, but in a real Kubernetes CR APIs and all, especially with CRDs, schema can be deeply nested. You will see things like nested objects and combination like one of, all of, any of. So, I added there a recursive

traversal to walk through all these nested stuff and parts of the schema. for and this pull request, it resolves reference, keep tracks of visited nodes to avoid loops, and avoid duplicates. analog with this, the overall workflow also needs some cleanup because the documentation is since we are sick dogs, we need a documentation, and the documentation was still based on GOPATH, and which isn't really used anymore, and

there was reference to files that were no longer part of the process. The setup was selected to updated a simple Git clone-based approach, and this makes the setup much easier to follow and closer to how actual Go projects work today. So, now let's go to how the current process looks like. So, you still have to follow these steps, and these are really I Believe me, these are

really easy one. You You can just create a folder and clone these all repo. And now you have to clone the Kubernetes website repo, Kubernetes KK repo. Now, you don't have to rename that Kubernetes repository again. You can just clone by Git clone command. And now you have to set some confusing build variables like it's still the same as the last process. And yeah, here is our

version directory. You can just run this command to update the API spec folder and all. And after that, you can just run make copy API and I fixed that. Now, you don't get any errors and you will get that file index.html and navdata.js, which is used to navigate the API okay, here here we are talking about API reference location and versioning. So, I did some changes there,

like you can find the HTML version and API reference this site on this path folder. And yeah, you can just run the now container and you will get the API reference docs. And over to you, you look at. Thank you. Okay, now we're going to talk about our overall goals for the reference docs generator and where we want to take it in the future. Um so, ideally

new contributors should be able to do this without much hand-holding from us. Um they should be able to build the reference docs without much hand-holding from us or ideally no hand-holding. Um and they should be able to help contribute to it without much hand-holding. So, um as mentioned, I run the release team, which is almost entirely brand new contributors and we used to have the docs subteam

generate the reference docs for us. Um it is no longer possible to have them do that because of a lot of the problems mentioned. Now that many of them have been solved, we might be able to move back into the direction of offloading that to the docs subteam. Uh but we need a little bit more work before we can do that. Uh we would also like to

reduce the need for manually maintaining the config.yaml. That does require some like like very manual work and specialized knowledge, so that could be solved with some documentation changes, but also some refactoring of the way the reference docs generator behaves. Um we would also like it to infer some configuration automatically if possible. Um there's a lot of manual entering of uh release versions, and that that is something

that we should be able to have it figure out programmatically. Um you can help with this. This is a community effort. Everybody, uh whether you're involved in SIG Docs or not, um there is stuff to do in the reference docs generator that uh requires engineering work, and we don't have a lot of spare resources ourselves. So, we would like to borrow y'all if help us figure out

how to optimize it. Like some of the stuff it's doing is surely us reinventing the wheel um like kind of badly and not not wheel-shaped. Um so, if anybody has an idea of tooling that does like some part of what the reference docs generator is doing, we would like to hear about it. Please come talk to us. Please come suggest alternatives. Um if there is a drop-in

replacement for it that already does all of this and doesn't require like asking four people, one of which is kind of barely involved in the project today, uh to help us generate the reference docs, that would be great. Uh there is a lot of work to do in the existing code, too. Uh if you've never actually dug into the actual code of the reference docs generator, it

is, I'm not kidding, uh bash that calls Python that calls go. Okay? It was developed over the course of years by a sequence of I think like five people, right? Um who all had clearly very different ideas of what this thing should look like architecturally, and you can you can see the different personalities of engineers in the reference docs generator code over the years. Um and it

has resulted in something that's kind of spaghetti-ish at times. And it's it's how we ended up with no error handling until he fixed it. Um so now at least it doesn't fail silently. That's extremely helpful. So there are all kinds of improvements and refactors and small tweaks that wouldn't take a ton of time that you are all welcome to do and we would we would love it.

A wish list item, containerize it so that it's easier for anybody to run instead of having to install a whole crap load of uh dependencies on your actual machine. and we're also open to suggestions on what you think needs improving in it cuz we're not, you know, we don't know everything, right? We just have to babysit this monstrosity and do do our best to raise a child

that uh behaves in the world. And right now it kind of doesn't, but it's getting there. It's getting there. So does anybody have any questions for the docs team? It's your microphone. He can go if anybody has a question. >> Who? I can run it. Sorry. So I'm not familiar with uh release doc process like the current process, but what do you take as input? Like is

it like a big JSON schema, a bunch of CRDs? Like basically what does doc generator takes in and cuz I suppose like it's uh output like a bunch of like HTML and JavaScript, but what is the input? Uh it's either coding Kubernetes Kubernetes we use open API schema and please correct me if I'm wrong since I spent 5 years since I've looked at it, but yeah. It's

all in Kubernetes Kubernetes and we use the open API schema. So before I would do a get pull of KK and just do a get pull of KK and then run through all the code. And so it's a long process to generate, but if you want to add some Yeah, we are implementing some swagger stuff and open API other stuff and we are making so looking forward

to like making this generator more smarter. So it will not need manual intervention to figure out that which API version and configs specs are adding every new releases. Okay. >> Yeah. Thank you. Anybody else? Yeah, thanks for the talk, but I think as you mentioned as well you are not having to reinvent the wheel I guess multiple projects are doing it. So what is so different about

Kubernetes there? Like why is there such a complex doc generator even implemented? I don't know. I wish I knew. I wasn't there at the time. I also find it baffling. Honestly, so do who who is still around that can answer that? Do you know why it's like that? We inherited this. That's the right answer. and I think I was the last person to run a success feed

the old way. And it was and you saw from the PR that was that error was 5 years ago. And so from 2021. So it was inherited and I wish we could just refactor it and take a look at some you know what other folks do because it's you know, it's swagger. It's open API. It's not new. So, it's yeah. So, I I I could say that

we've been in here we've inherited and we just try to fix it but we haven't really looked at let's just refactor it as a you know, project. But that takes a lot of cycles as well. I was about to say I can I can also help answer that question. I'm also SIG Docs co-chair, Natalie Vlatko. Um a former co-chair Jim Angel who was actually also a kind

of co-chair and tech lead kind of at once used to be the one that would actually run the generator for release also by himself. And so it's also going off of a team of one building on top of things and sometimes people just helping out and not actually looking at it in a holistic way of what how this needs to exist. It is I'm one person. I

will accept any help I can get. And then and another now former tech lead Chiming was able to come in and also do some work specifically on the part that Bash calls Python plus Go to help out with this but it unfortunately is is a story of long ago docs was so under-cared for with only a couple of people we just made it work. We have a

lot more people now but unfortunately we also have a lot more work. Release has also grown with how we also have to support the release team in the cycles each year three times a year. So, this is one of those things of this is a really great technical chunk of SIG Docs that someone can help us out with but the majority of us in Docs are actually

in Docs from our JavaScript and CSS experience because we also own the website or our Docs experience and none of us are that other than maybe Ray that great with Go. So, we'd like to get some folks to help out especially folks who know Python because we think this can actually just be solved very easily. It can sorry? It can. It can. It can. So, so that's

the answer. It is legacy. >> Mhm. Yeah. Yeah, and it's it just to add to that I think we just saw it as easier to patch than easier to refactor and move away from some parts of that of that generator. Yeah, okay. So, um but are there like at least we are not Kubernetes maintainers and we are not contributing at the moment. I mean, it might change,

of course. Um but what we do is we, for example, work on operators. Um is there some lessons learned for operator maintainers concerning generation or Can you repeat that question, the last part? >> Yes. So, um like for example, if you're writing a CRD or something, like we document in the CRD, of course, and we need some way of generating the docs the same way as it

is with Kubernetes. So, is there some lessons learned you could give us? Um I would say keep it simple, stupid uh would be it. Um I think part of why the reference docs generator is the way it is because we over-engineered it. Um like we we looked to a more complex engineering solution than we actually needed because um like Natalie said, Python is really good at parsing

text. This whole thing could just be Python. There is no reason for Bash and Go to be involved. It could be a Python file. Um so, we we over-engineered it. For what reason, I can't say. Um but I I would advise you to um keep it as as simple and minimal as possible. Sometimes you do not need a fancy solution. Sometimes you don't need a fancy tool.

Sometimes you just need some Python parsing text and outputting JSON or HTML or whatever. Yeah, okay. Thank you very much. And make sure you document your API reference Oh my god. >> Yeah. That is that is one tip that we can definitely give you because if you do not document the process of actually running the API reference generator, nobody in your team after you is going to

be able to run it. Yeah, I think our largest shame as a SIG is that we're SIG Docs and our own tool was undocumented. Like Yeah, barely any instructions on how to run the thing, uh errors that fail silently for no reason. He he really did quite a lot of work on just like error handling and documentation that made it possible to use the thing. So, don't

assume that you in 6 months are going to know what the you were talking about. Certainly nobody else is going to know. Document it. Thanks. For operators, there's a very nice project from the Elastic folks. They built like the reference a reference generator which doesn't really fit the Kubernetes needs because it parses the Go AST, but it works very well for any kind of like Go region

operator. So, it just out of the box. Like I fixed a couple bugs, but it's like perfect. What is it called? Uh I think you can search like Elastic Kubernetes reference. Uh they have a good product. It's pretty simple to use and also kind of nice to extend. They give you good templates. You write what it should like what the output should look like in like regular

Go templates and it just generates everything. My one uh so, like Cluster API, they have their own docs as well. Um and I think you should ask the Cluster API folks as well or or go on Slack channel and just ask them what what you use. Um for us on our part since uh we run we help run the infra but like the uh management part of

hosting it, but like in terms of like generating the code and generating the the docs for Cluster API, yeah, that's a good resource to go to in Slack channel. That's good. Are you looking to get I would say to replace everything or do you want to like get contribution contribution to just incrementally fix or is this like are you open to just having a big replacement with

a Yes. I knew that was going to be the answer. So So I have a slightly different opinion. I mean, yes, but with it's with a caveat. So the Kubernetes docs need to be online all like and the reference generator needs to be working all the time in the sense that we release three times a year and we also um our docs are really uh are really

really important to just be working all the time. So a big one over fix is actually probably not the the software development that we are looking to kind of like push there as a as a as a strategy because it's it's it's more prone to failure and and and mistakes. definitely like refactoring over time is what we prefer. As an example, we're doing that with our Doxie

upgrade right now so that our site continues to stay online and not be broken. So it's actually really really important that the reference docs generator works and it is barely working now. Uh so while yes, I also agree yes, if it can be done like in a small place that we can like verify that like that one big change would actually like be effective, cool, but we

don't know enough about the legacy of it to actually like attempt to like replace it all at once.