Kubernetes SIG Docs, 7 Aug 2018

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Kubernetes Sig Docs 20180807 (partial)

Description

Note: This is a partial recording. The host's internet connection died midway through the meeting.

Meeting notes: https://docs.google.com/document/d/1Ds87eRiNZeXwRBEbFr6Z7ukjbTow5RQcNZLaSvWWQsE/

The Kubernetes special interest group for documentation (SIG Docs) meets weekly to discuss improving Kubernetes documentation. This video is the meeting for 07 August 2018.

https://github.com/kubernetes/website

A

ah Good morning, everyone this is Tuesday August, 7th 2018, and this is the weekly meeting of kubernetes sig docks I had to undergo a momentary cellular transformation to become not myself, but kubernetes sync lead in order to record this meeting, as you can tell I have done it.

A

Let's start by asking, if there are any new contributors here, folks who are attending for the first time.

B

I so I work for a Forex pace with the Aquarius team at Rackspace and recently team wanted to contribute more to the end. You know upstream communities and there was opportunity to attend.

A

B

Interest group so I decided to join and listen so today, I'm just listening, basically great.

A

Well, welcome I used to work at Rackspace too. We can catch up on slack and see who we know in common sure.

A

Any other folks who are new welcome back Dominic, welcome back Dan Jay.

A

Think that is it for novelty, so as an update, I've got some ongoing health stuff and I'm only going to be semi available. I need to pull back my hours significantly until we get until we figure out what's going on and get it dealt with, so I will be around, but I want to be sort of around as a default. The best way to get a hold of me if you need my attention for something, is to send me a direct message on slack.

A

Hopefully that will change, and you can just message me any old time or I'll start showing up randomly in common threads again, but for now, if you, if you want to make sure that I see something it's best to assume that I don't see it unless you vent should be into the into the thread all right. We have two things to revisit from last week before we move back well, we need to get two quick things to talk about from last week: I don't see Zach Arnold here. So let's skip the one that twelve update.

A

So, let's see Andrew, do you want to talk about the Google search problem with indexing? Yesterday, yeah.

C

So we started getting a lot of like issues and notices that the search results for Anaya weren't coming up and Google search and I traced it back to a couple changes that happened, and actually these changes happened maybe about a month ago, but they only the search results only started changing slowly.

C

So the issue was the way it was set up. The way I set it up originally was for, by default, all of the.

C

For all the branches, when they're deployed to to have like the header like no index tag in there and then and then switch that off only for the master branch, but so there's a series of changes where I think they didn't know what they were changing, and so it got like pulled into the header for like all of the branches, including master. So so I reverted those changes and set it back and then I think I had some notes in the net lafete tamil file to say what those things were, but I think.

C

Maybe they weren't descriptive enough. So I have a PR in there to explicitly say do not remove this, and you know a little bit more information on what it's for.

A

Awesome yeah I have to apologize for that because I approved one of those PRS, the one that looks submitted and when I looked that I. The the the changes to no indexing just flew right. Past me, I, didn't I, didn't even realize. Well,.

C

I I didn't either like I think when I saw at PR I didn't occur to me that this is what would happen and because it was split across two different ones. There's also a change from depth, and then so it kind of just you know, got through the cracks.

A

So do you are you getting enough attention on the PR to update that the fly that tunnel, if you, if you need more review on it, I would be happy to if you want to assign me into it. Okay,.

C

Sure I mean it's a really short. One is just making sure there's like comments in there that better.

A

Yeah cool, thank you for fixing that that yeah I started. I saw the flood of PRS come in and it was awesome awesome that you were on this I think so. Thank you. Yeah.

C

No problem, the search results may start may take a little while for them to start showing up in Google search again right yeah, they didn't D index overnight and yeah. Take them.

A

Time to reindex yeah.

D

I I'm curious about that. How do we actually know that it's fixed because, like how long does it take, do we know.

C

I can try to force re-index, but it's not immediate, like I can go into the Google the search console and put in a request for it to rien Dex the site, but I still think it would take. Maybe like a week or so so we.

D

Should surprise that it didn't happen really quickly because like, for instance, the 1.4 site, when you guys shut that down last week, it went off the search results really fast. So I guess it's a different sort of a thing.

C

Yeah because that was shut down is like probably 404 now, whereas when we just put the no index header stuff it the site was still there and there's no 404 is it's just like it couldn't be indexed anymore, so it gradually declined.

D

Yeah, that makes sense. Thank you.

A

Cool misty: do you wanna any? We were gonna follow up on this from last week for.

A

Maintenance releases by number that need manual bumping. Have you have you had a chance to think about what more ideal solution might look like? I have.

D

It and I'm not sure that I'm gonna come up with a solution all by myself. I, don't really know enough about what's available in Hugo and I haven't had time to dig down it. I just reiterate that the situation that we have now is really brittle and I'm, not necessarily sure what to do about it. I'm still not convinced that putting dot X on everything is the right way to go, because that forces users to change something every single time.

D

So yeah I don't have a solution: okay, something together. I.

A

Mean this sounds like honestly like something to approach like sega architecture with maybe is like release naming policy.

D

Well, I, don't think that's the problem. I think the problem is. We have some places in the docks where people have to specify a kubernetes point version right.

E

D

Don't ever go and update the docks every time. There's a point release their point releases all the time, including in older branches, and we don't update that, even though, like frontmatter exists about what the current point release is. But it's not a rotational duty or anything like that to go and update those and it's a manual process in each branch anyway, and.

A

I'm sorry I'm, just coming back, my brain is finally catching up from a week ago. Do we have? Is it that I am I, remembering correctly that we were thinking about trying to replace each one of those instances with a variable that.

D

Was one option I mean we have the variables now we just don't, keep them up-to-date and we're not using the variables in those places actually.

A

So is it something that, like a contractor, could throw a few hours at and and at least get us to where we ostensibly claim to be right? Now, oh yeah,.

D

Pretty easily I think then the matter is keeping it up-to-date. So we don't currently assign anybody as the release Meister or anything like that for those point releases, because there's not a lot of work on our part. But it's also interesting that I'm not sure that we update the release notes in our Docs. Even though we have the release notes, we have a copy of the release, notes for the major releases or minor releases.

D

I guess is the right name for them, but we I don't believe that we go back and add release notes for point releases into the back. So that's also a little bit of a weird thing, because we sort of train people that release notes are going to be there and then, as far as I know, like I, never I didn't update them for one dot, 11.1 great.

A

D

Some unevenness in the processes and we probably need to figure out what the desired end state is and then we can make a plan to get there and I don't know if we need to do that today.

A

No, this is I think this is a longer a longer term issue to solve, but I do think. I agree with you. I think that we do need to solve it. I think our release process could could definitely be better, especially for, like you point out the consistency of release, note expectations and content.

A

Okay, I I'm, going to take a look and see if I can I'll, be it right. The duck Cincinnati and that's I'm, hiring territory for contractors, so I'm gonna see if I can wrangle a couple of folks to get to the work that we all sort of look at and say gosh. That needs to get done and there are some contractors in it specifically.

D

For release, notes, I, really like as an end user and when I've been maintaining dog sets before also it's fairly easy to have like one release, notes page for like 1.11 and then that release notes page gets the 1.11, not released notes and then, as there's one that 11.1 those get added on the top, adding on the top any of a table of contents. That way, it's obvious. What's the latest, we.

A

Specifically, what's what that could actually look like when we have the resources to put against it? Yep.

F

A

Right and bringing up how to import content from internationalization repos into K website again, because it's still it's a it's a thing that we haven't solved yet I, the more I look at subtree, the more I agree, it's kind of a nightmare and I, don't know that we need to have the the kind of commit history associated or the commit history associations that one gets with subtree.

A

It could be possible that we could just open a giant PR initially to import all of the contents of like content, /z, h or K or J, just sort of one big dump initially and then set up web hooks to make that work. But I, don't know if that kind of a web hook chain is possible between repost, like that, we we are getting to the point, though, where we've got maybe like three months before this needs to all work.

A

So I don't know Andrew, you I know that you've had thoughts, but I don't know if this is something that you want to tackle or if we want to like try and get a small working group with multiple people on it. I, don't know what are your preferences there yeah.

C

Maybe we might want to get working group because I am not sure what the right answer is either.

A

I will start working group or automation.

A

All right uh all right, so let's go let's move on to fundamental modeling concepts, part two! Okay, so.

C

Based on the feedback from last week, because I think Tom and some other people asked about instead of doing pod, what if we did more of like a high-level architecture of criminais, so Dominic was sort of noodling around on that, and he has sort of a presentation that will kind of give us an idea of what that might look like awesome.

A

Thank you for coming back darling thanks.

G

For having it and I like the word noodling around, so let me share the presentation, really quick. You know get acquainted here with I think that should do it.

G

You can see my screen correct, wonderful, so, as Andrew already mentioned last time, when we were talking about modeling the pod, there were also some requests about. Well. Can we actually start on a high level and talk about kubernetes, what it is, what it does and on the highest level, how it does it so, as Andrew said, I was noodling around and nothing you're gonna see here is definite, it's just the first step and so that you guys can see what approach we're taking what direction we're going.

G

So this is a first try for definition, kubernetes as container orchestration engine designed to host container eyes applications. That raises numerous questions right off the bat. That is what is a container orchestration engine? What does it actually mean to host and what are containerized applications?

G

So then, you basically go deeper down the rabbit, hole and look for a definition of a container orchestration engine, as I said very first, very rough step where you serve a container orchestration engine, make sure that for each container in an application there is most one node so that this node hosts this container.

G

Now then, the question oh yeah and the goal obviously, is that the number of containers that is not hosted on a node is minimized. So obviously you cannot always guarantee that you can host all containers sensor resource restrictions, but that is basically the overall overall target of the orchestration engine. Then the question is: what does it actually mean to host a container right? And so here you come up with the idea that for each container there is a most one. Node that hosts this container and eventually the state of the container is terminated.

G

Now eventually is, is a tricky business, because the definition in temporal logic states this does not need to ever come, but once it comes, it holds forever true. So this actually accommodates the common kubernetes workloads quite nicely some applications for ever running. For example, if you have applications, some applications actually are intended to terminate. If you talk about batches and then lastly, containerized applications, what are containerized applications and the simple scenario?

G

Containerized application is nothing more about a set of containers which also actually addresses kubernetes quite nicely because for kubernetes the container is a smallest unit of concern. Anything deep down, kubernetes does not really care about it's actually OPEC could kubernetes cannot further look into it, so that basically comes to a definition where an application is a set of containers and the containers are hosted on most one node in the situation, and this this slide is very iffy.

G

However, I still want to throw it in there in the context of kubernetes, then you break it down to application specifications that will eventually lead to desired containers that are met by current containers that are hosted on the individual nodes, and you can also see the areas of concern for the individual components of kubernetes controllers are mostly concerned with application specifications and desired containers. The scheduler is concerned to actually assign a note for a desired container to turn it into a current container and the cubelets are the ones running the containers.

G

Now, as I said, this is a very very first initial step has multiple issues associated with it. For example, the notion of current state and desired state is a notion that actually deserves to be further investigated.

G

Also, it appears to be the case that kubernetes, the individual controllers and the scheduler of kubernetes actually work in the control in control loop fashion, comparing desired state to current state. The cubelets, however, do not so for a cubelet.

G

The cubelets are basically just operating on a large process table like an operating system process table where each part is a process, but since pods are ephemeral, pots may go away and the cubelets do not further care about that, because otherwise you would have to have the notion that the desired state also effects the desired state, always effects the current state.

G

But in that case you would also have the notion that the current state affects a desired state, because then, eventually, a pot has to be removed from the desired state when it terminates in the current state. Otherwise you would doom the pot to run forever. However, this notion is completely counterproductive, so it seems that there is a hard stop at the scheduler where we talk about desired state and current state and the cubelet operates on a simple process table and once a port dies, the process in the process table is removed.

G

So, as I said, there are, there are multiple, multiple issues with this presentation, but this is basically the direction that we want to take. So the takeaway here is that we try to nail down definitions even of sub concepts like, for example, cons, container orchestration engine like host and use these definitions to then define what kubernetes is specify. What kubernetes does and FM ceylon comes into play for the highest level of how does kubernetes actually do it.

A

Thank you very much.

A

So thoughts, thoughts and feedback I have some, but I would like to hold it for others.

H

So so, looking at this, so so two things popped in my mind. The way you did the definitions was something I was very, very comfortable with, but I do have a master's degree in mathematics. I was a little concerned that, for people like me, that was very elegant and a good fit and very intuitive for a lot of the folks who are not very strong, and you know, math is their first language.

H

Those those definitions could usually be also done and non-mathematical sentences and the concepts were simple enough. That I think people could grasp from a non mathematical sentences.

H

So so that meant give me little worried and then on this chart this was good, the one that you're showing now, but what I noticed is I, don't know if you're missing some entity relationships or what, but you really had to verbally describe to me what the couplet does and what the scheduler does and I'm not able to get those from the diagram without the the added verbal description that you gave. So you know the suggestion would be if you're going to try and use this modeling approach to really capture the essence of kubernetes.

H

Somehow there's got to be, you know either through entity relationships or something else a way that makes clear what you were able to tell us verbally, hey the couplets responsible for this, and the schedule is responsible for that. Those are the things act that popped in my head.

G

Let me address both of these comments. If you don't mind so number one, if you have a math degree, you you probably cut me out taste, they are already good, but I do agree. That mathematical formulas are by no means sufficient to actually be put in front of end-users. So my approach, usually when I use these mathematical definitions, is to force myself and then also the collaborators to actually agree on a model, and then this model has to be put into words, absolutely correct.

G

So, for example, this one I much like because you can actually read it like a sentence say for each container. There is at most one node where this container is part of this node.

G

However, I do use the mathematical formulas in order to force myself to be precise and I also use a formal modeling tool, alloy that uses first-order logic and set theory in order to specify these models and see. If my thinking actually has any inconsistencies once these inconsistencies are ironed out in a mathematical sound model, then I go ahead and put these back into words. But for me these are very important for us to collaborate on that. We have a very strict, very specific definition of what we're actually talking about yeah.

C

And if I could interject like I, think of it as part of the process right, this isn't the output that we're giving to the users but we're creating a model and what's more rigorous of model than mathematics. So once we have my model, then it's easier for all of us, including the tech writers, to be on the same page and then craft, like the the words around it to convey to the to the end-user. Yes,.

I

We need the wordsmith very true yeah I, do like that distinction and I appreciate that no.

F

Worse on my math is um no I'm, not years old, but decades old and I know.

E

F

Very approachable and are precisely the reasons that Dominic's and that getting it simple and right and having a really, really clear, succinct definition that we all agree on I think this is really a fantastic approach. Thank.

G

You, and also it will enable us to actually strictly define what our synonyms somebody says. An application is being executed. Somebody says an application is being hosted now we actually do have the possibility to have these two terms. We two distinct concepts, but we can also easily now define pseudonyms by saying that the predicate being hosted strictly equals accredited the predicate being executed or we can specify where the differences actually lie.

G

Now, when we come to the to the second statement once again, absolutely absolutely true. None of this. What we have in this presentation shows yet how kubernetes does anything of what it does. It only shows relations between the individual concepts diving into how diving into the agents and the events and actions of the individual agents or individual components of kubernetes is then basically the first level and first output that we need to derive from the definitions and then, of course, from the implementation of kubernetes. My.

H

Simple point is: if you look where you've got the line for coublon and if you look where you've got the line for scheduler I couldn't tell from this diagram what exactly we're trying to get across with regards to you know: ownership or responsibilities, or what have you by the way, there's lines, work, I, simply thought you know, there's going to be an either way to annotate this, to give you more information to to really express what I think you said verbally eloquently, but if I didn't have you saying it verbally? That was hard.

H

I had a hard time following.

A

H

Are you able to look at this diagram and get a feel for you know what scheduler has responsible and Trueblood is responsible or or did you need the verbal description as well.

F

The verbal description as well and I have been not really recently but within the last month to six weeks digging into cubelet stuff and the cubelet is part of the control plane, but it's also a different kind of critter yeah.

F

You don't see that at all here it looks like it's the same kind of critter as a controller and those scheduler where critter is not well-defined, I agree, but yeah and I mean that's one of the things that makes this stuff hard to describe right um so and I thought that Dominic's, like, like you, Brad I, thought that Dominic's explanation was immensely useful, yes or the expanded definition so yeah. If.

A

I mean, as Dominic has clearly pointed to us, that this is a first draft, that this is a work in progress. Is there enough here that we could give this kind of feedback in a pull request? For example, are we satisfied that the the direction the Dominic is headed with what he has is going to be.

A

For the the fundamental nature and direction of the project, without are we satisfied with it and could we offer this kind of feedback at the PR comment level, or do we need to revisit the fundamental nature of the thing itself? Is it sounds.

C

Like closer would be to create a working group so that by the time it gets to the PR process, it's already mostly kind of refined sure all.

H

Right and the other side, some of us find this. You know personally enjoyable to see right. So please don't take my my comments as far as criticism and you know pulling out the Kleenex box and you know III think there's a lot of potential here. I think you see me making these comments because I really like this stuff, I really like it and you know, I- think the interest is interesting to see.

H

You know where you know where he goes when it comes to things like deployments and staple sets and I would be happy to participate in a working group. You know III, wouldn't when, when he gives these presentations I just leave really enjoying them. So so don't take the criticism too hard. Please I'm, just trying to help make sure it really we get the most out of it. If that makes sense,.

G

Actually, let me jump on to that. That is what I would like to accomplish in a first step right. That is that we start to share a mental model right and then also, as Andrew said, when we bring in the wordsmith, they share a mental model with us and from that we derive an end user description right. This is nothing you can just throw in front of an end user. No.

H

That's a fair approach and a very good one. The way both you and Andrew explain hey this is the process to get us to the end user writing stuff so that we're always on the same page I. Think we've all been in meetings where you can tell everybody is thinking about the problem completely different and there's that frustration and so getting a model to unify everybody up front is really cool.

H

C

To make sure we kind of move along the action items I see are that the next once everyone agrees, this is kind of a project we want to do then Dominic. We need to do this as a contractor, so he and the CNC F I, guess be a Zack. We need to come up with a contract and then we should form a working group so that we can just have a like a weekly or whatever cadence work on this stuff.

A

Agreed I'm in favor of it I think it's an awesome idea. Dominic, if you will contact me by email. Let me put my email and chat really quick.

A

Then we can get the ball rolling, but yes, let's proceed and we have a lot on the agenda today. We do alright. So thank you for coming back Dominic. Yes, let's proceed, and now, let's move on. Thank you.

A

Let's see done on Jay. Do you want to you? Have a presentation for cluster operator docks? That's.

E

Right, yes, perfect, so both made a little presentation.

E

So the idea of the docks this first time I'm doing a little presentation so micron, but the idea is to sort of bring out something that I found, while using kubernetes I've been using community about three years now and talked to a lot of folks in the community- and this is just what people see was some of the flaws in the kubernetes documentation.

E

It's really good to get started and all of that, but as cluster operators as people who maintain these systems, one of the kind of challenges we face when we look at communities as this upstream platform that we all use and what the docs sort of do, focus on and do a really good job of is how do you get started right?

E

They give you examples and if we were posed in terms of defining stuff like pods an object and all of that, but when you start actually is running this, what you try to try and do. Is you set up a POC? You start running your workloads out there and then silently you run into this whole mess of things that actually is involved in running communities in production.

E

So I put out an example here which, which is like I set up the cluster and I, have a bunch of things that the docs talk about and the expectation that the documentation sets to a cluster operator, for instance, is you simply need to run this application and it will be highly available if a node goes down Kubla from detected and pods in microwave to a different node, and one of the questions that then comes up?

E

Is community silently dies on that note right and when you start digging into these things, you find that you have to use stuff like node operators or no problem detectors to figure out if something else is broken and the. Nor do you need metric and other kind of probes sitting on the node to actually detect these flaws in the infrastructure and to get to that point, you need to access a lot of other tools say like Prometheus or few Integra fauna and use all these tools.

E

As an operator to debug and pinpoint problems and get to that point, itself takes a lot of time for a bulk us to users, and it takes a lot of reading around, like the community has built a lot of these really cool tools and we find them eventually, but the discovery part is sort of not being able right.

E

The other thing is there: are these great tools which some of them are a part of the CNCs like Prometheus and fluent? But if you actually look at the tasks documentation out here it, it is sort of fallen out of maintenance, and when you go into the details of it, for example, if I just go, do something like monitoring cluster health right monitoring, node health, it talks about a bunch of things that do exist: players, communities. There are a few limitations and it talks about what to do. In an operator.

E

Specific environment like yes set up, GCE and you'll have everything in stackdriver, so this is sort of out here and then I need to go. Google around and figure out, okay. So what do I really use if I'm, not on GC or if I'm running a different flavor of communities and what has also happened? It's a good thing and a bad thing for communities. It's like no Jaso!

E

You have a lot of different tools, doing the same thing and there's no way that as a person, community itself might be intimidating when I walk in, but as an operator even more intimidating. What tool do I pick right and one good example of this is at least in the documentation of volumes in communities.

E

We explain what volumes is and then we go to different types of volumes where you've listed everything that a community and sort of build bath, repair, fee systems right and people can actually click on each one of these things and figure out what are their options and what they sort of advice. So this really helps me in making more informed choice while picking my entire stack and one more thing is the previous examples.

E

Like no trouble detector, we say yes, communities, point updates for the next version fixes it, but for a lot of operators doing that version upgrade. May not be possible because of a very complex matrix of dependencies or how stuff is running or how it's being set up and as the community grows you're going to have more of these problems.

E

I think one point I am missed out of here is I did notice this specifically like when I found this link I found it really helpful where you have these different parts and I went to the cluster operator part out here and I clicked on the links in this, and this has sort of again fallen out a few.

E

So if I want to actually see what do I do, how do I define quotas or whatever else I'll find that, but that does not sort of give me the story of an operator from an operator perspective, so one good place to start learning and what I thought I would do is see what my competitors are doing right and my competitors. These are three or four firms which work in the communities domain are very, very active contributor.

E