> 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
> 
>

Reply via email to