mesos-reviews mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Neil Conway" <neil.con...@gmail.com>
Subject Re: Review Request 42040: Added Quota Operator Documentation.
Date Fri, 08 Jan 2016 18:07:50 GMT


> 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.
> 
> Alexander Rukletsov wrote:
>     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 : )

Maybe we can rephrase this to talk in terms of whether a "role whitelist" has been configured?


> 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).
> 
> Alexander Rukletsov wrote:
>     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?

I think we could improve things in two ways:

1. Move the "How does it work?" section to the end of the document. Although this is useful
material, it is fairly advanced; a lot of users will want to just know how to configure/examine
quota.
2. Remove some of the implementation details. For example, the fact that we authenticate,
parse, validate, and authorize a quota request is not important for the information we want
to convey to operators about how quotas behave.


- Neil


-----------------------------------------------------------
This is an automatically generated e-mail. To reply, visit:
https://reviews.apache.org/r/42040/#review113358
-----------------------------------------------------------


On Jan. 8, 2016, 10:26 a.m., Joerg Schad wrote:
> 
> -----------------------------------------------------------
> This is an automatically generated e-mail. To reply, visit:
> https://reviews.apache.org/r/42040/
> -----------------------------------------------------------
> 
> (Updated Jan. 8, 2016, 10:26 a.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/home.md 6f0f4b9cb9d0da1f9960ebe7f36ce186c1317535 
>   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
> 
>


Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message