> On Jan. 7, 2016, 11:55 p.m., Neil Conway wrote: > > Can we link this page from `home.md`? > > > > Overall: looks great! Only major feedback is to move the implementation > > details down to the bottom (or remove them), and refactor things slightly > > so that any user-visible behavior (e.g., failover and capacity check > > heuristic) are discussed outside the "implementation details" section.
That was exactly our intention to surface capacity heuristic and rescinding, see my comment below on the proposal how we can restructure this. > On Jan. 7, 2016, 11:55 p.m., Neil Conway wrote: > > docs/quota.md, line 226 > > <https://reviews.apache.org/r/42040/diff/1/?file=1186512#file1186512line226> > > > > Fix this link -- probably just link to roles.md. Although we don't > > really call the feature "implicit roles" in the user-facing docs (we just > > talk about whether a "role whitelist" has been configured), so maybe we can > > just remove this. Though it indeed seems weird to mention random features in this user doc, I would love to mention implicit roles somewhere here. The motivation is that it's a new (read: relatively unknown) feature, which is highly related to quota. I would like to make sure an operator reading this doc is aware of the feature and can use it appropriately. The best solution would be to add a `NOTE` or a sentence and remove it in ~6 month, when implicit roles become standard. Unfortunately, we do not support remove `TODO`s in user docs : ) > On Jan. 7, 2016, 11:55 p.m., Neil Conway wrote: > > docs/quota.md, line 61 > > <https://reviews.apache.org/r/42040/diff/1/?file=1186512#file1186512line61> > > > > These kinds of implementation details belong at the bottom of the > > document, I think -- it is more important to tell the user/operator how to > > define quota before we worry about allocator details. > > > > We could also remove a lot of this information -- the specific steps we > > take to implement a set/remove quota request are not an important thing to > > document (and might change over time). Our intention was *not* to provide implementation details, but to mention some of those, which are important and affect cluster behaviour. There are 3 things: capacity heuristic, rescinding offers, allocator logic (quota first, fair share second). I do think we should explain operators how these things work so that they don't break their clusters. However, if the section feels like an "implementation details" section, we didn't achieve our goal. The reason we decided to briefly mention other stages is in order not to be misleading and leave an impression, that there is nothing else. Do you think leaving only these 3 sections and adding a sentence that those are most important stages in quota processing is a good compromise? > On Jan. 7, 2016, 11:55 p.m., Neil Conway wrote: > > docs/quota.md, line 21 > > <https://reviews.apache.org/r/42040/diff/1/?file=1186512#file1186512line21> > > > > Is the analogy between quota and dynamic reservation accurate/helpful? > > A dynamic reservation reserves _particular_ resources on a _specific_ > > agent, and the reservation fails if the resources are unavailable; quota > > just ensures that _sufficient_ resources in one or more agents are > > dedicated for the role. Calling quota a "cluster-wide dynamic reservation" > > doesn't capture this, IMO. A dynamic reservation does not reserve a _particular_ resource. The difference between reserving on a specific agent and anywhere in the cluster is captured by "cluster-wide". You are right that a dynamic reservation fails if there are not enough resources, but same does quota due to the capacity heuristic check. The reason we decided to add this sentence is to give operators better understanding what this new feature is about using analogy with things they are already familiar with. However, if folks think the analogy is more misleading than helpful, we can remove this sentence. I personally prefer being slightly imprecise but give the big picture and intuition. I remember a poster in the Institute for Nuclear Research in Dubna, here is my translation: "One should explain a scientific problem to a big boss not in the precise and correct way, but in a way the big boss understands. It is a lie for good." Original for those who reads Russian: "????????? ??????? ?????????? ??????? ???????? ????? ?? ?????????, ? ???, ??? ??? ????? ???????. ??? ???? ?? ?????." - Alexander ----------------------------------------------------------- This is an automatically generated e-mail. To reply, visit: https://reviews.apache.org/r/42040/#review113358 ----------------------------------------------------------- On Jan. 7, 2016, 11:17 p.m., Joerg Schad wrote: > > ----------------------------------------------------------- > This is an automatically generated e-mail. To reply, visit: > https://reviews.apache.org/r/42040/ > ----------------------------------------------------------- > > (Updated Jan. 7, 2016, 11:17 p.m.) > > > Review request for mesos, Alexander Rukletsov, Bernd Mathiske, Joris Van > Remoortere, and Neil Conway. > > > Bugs: MESOS-3877 > https://issues.apache.org/jira/browse/MESOS-3877 > > > Repository: mesos > > > Description > ------- > > Added Quota Operator Documentation. > > > Diffs > ----- > > docs/quota.md PRE-CREATION > > Diff: https://reviews.apache.org/r/42040/diff/ > > > Testing > ------- > > Rendered version: https://gist.github.com/joerg84/a2c32e25d91e33045b56 > > > Thanks, > > Joerg Schad > >
