----------------------------------------------------------- This is an automatically generated e-mail. To reply, visit: https://reviews.apache.org/r/45967/#review152236 -----------------------------------------------------------
High-level comments: 1. We should tailor this towards the users/operators with a brief intro and remove things they don't care. We can link to the Epic and your MesosCon talk for more technical discussions. 2. We should write the doc as if we started writing it today, explaining all features already checked in. So we are not proposing things, nor should we include things that are still in the works (add them later). docs/home.md (line 54) <https://reviews.apache.org/r/45967/#comment221111> s/Shareable/Shared/ also, emphasize the usage in persistent volume? i.e., "allow tasks to set persistent volumes as shared"? docs/shared-resources.md (line 5) <https://reviews.apache.org/r/45967/#comment221134> I think we can s/Shared Resources/Shared Persistent Volumes/ even though we call this document shared-resources.md (for the reasons below). docs/shared-resources.md (lines 9 - 20) <https://reviews.apache.org/r/45967/#comment221182> Shared resources is an abstract concept and we have yet to generalize it in a way that it can be applied elsewhere other than the persistent volumes. Since the focus of this document is on using shared persistent volumes, I think it's more clear if we for now make it the only topic (until we can articulate it better to non-messo-core developers) We should jump right into "usage" after a very brief into. We just need to explain some basics first: - Access to regular persistent volumes are exclusive to one container/executor at a time. - Shared persistent volumes allow multiple executor/containers access to the same persistent volume simultaneously. - Simulatenous accesses to the same shared persistent volume are not isolated. docs/shared-resources.md (line 11) <https://reviews.apache.org/r/45967/#comment221131> `RW` not relevant here? docs/shared-resources.md (line 12) <https://reviews.apache.org/r/45967/#comment221136> `task` here is not precise, `executor/container` is. Shared persistent volume allows access from different containers, we can stick to this terminology so the distinction between this feature and the Pods is clear (without us needing to expand on that here). docs/shared-resources.md (lines 29 - 36) <https://reviews.apache.org/r/45967/#comment221114> No longer a proposal. We should describe that now that this feature exsits, how should the user leverage it. docs/shared-resources.md (lines 40 - 48) <https://reviews.apache.org/r/45967/#comment221248> This is not done and is potentially not going to be done this way (MESOS-6374). I think we can avoid saying too much about it for now. We can always add a paragraph when it MESOS-4324 is done. docs/shared-resources.md (lines 50 - 54) <https://reviews.apache.org/r/45967/#comment221250> I don't think we need to emphasize this here. Multiple tasks with the same executor can access the same regular persistent volume and overwrite each other's content whereas if multiple containers strictly want to access different sub-directories of a persistent volume, they gain nothing by sharing a persistent volume. docs/shared-resources.md (lines 58 - 65) <https://reviews.apache.org/r/45967/#comment221245> The doc should be written in either the user's or the "framework"'s perspective, not "we" as in "Mesos". docs/shared-resources.md (lines 67 - 71) <https://reviews.apache.org/r/45967/#comment221413> We should assume `SharedInfo` is already a thing (not a new thing, as compared to e.g., `RecocableInfo`, as least the operator shouldn't care) and we are just informing users how to use it. So I suggest we just skip this section jump into the usage examples. docs/shared-resources.md (lines 73 - 75) <https://reviews.apache.org/r/45967/#comment221412> Here we haven't included the scheduler DESTROY API or HTTP endpoints, presumably because they will be the duplicate of what's in the persistent volume doc, which I agree we shouldn't do. So I think we should just make it clear that we are only going to highlight a few things different than the regular persistent volumes in terms of usage, but with examples. Then we can refer the readers to the persistent volume doc for details. If we are not separately explaning all APIs, we probably don't need the `## Framework Scheduler API` heading. docs/shared-resources.md (lines 77 - 79) <https://reviews.apache.org/r/45967/#comment221408> To avoid duplicating the regular persistent volume doc, how about the following for using shared persistent volumes? --- The framework can create a shared persistent volume using the existing persistent volume workflow (See usage examples for Scheduler API and Operator HTTP Endpoints in [Persistent Volumes](persistent-volume.md). When creating a new persistent volume, the framework can marked it as shared by setting the `shared` attribute (borrowing the example from [Persistent Volumes](persistent-volume.md)). <The CREATE exmaple> If this succeeds, a subsequent resource offer will contain the following persistent volume: <The offer exmaple> The rest of the basic workflow is identical to the regular persistent volumes. The same shared persistent volume is offered to other frameworks of the same role in different offer cycles. --- The above feels sufficient to me? docs/shared-resources.md (line 175) <https://reviews.apache.org/r/45967/#comment221372> We can add a section for things that aren't in the doc for regular persistent volumes. i.e., --- ## Unique Shared Persistent Volume Features ### Launching multiple tasks on the shared persistent volume ### Destroying shared persistent volumes <This really applies to regular resources as well but frameworks needs to be more cautious about this for shared persistent volumes> --- I feel these are what make a separate doc for shared persistent volumes necessary (and we can continue to add more topics). Otherwise we could just bundle everything into the persistent volume doc. - Jiang Yan Xu On Sept. 27, 2016, 5:16 p.m., Anindya Sinha wrote: > > ----------------------------------------------------------- > This is an automatically generated e-mail. To reply, visit: > https://reviews.apache.org/r/45967/ > ----------------------------------------------------------- > > (Updated Sept. 27, 2016, 5:16 p.m.) > > > Review request for mesos and Jiang Yan Xu. > > > Bugs: MESOS-4325 > https://issues.apache.org/jira/browse/MESOS-4325 > > > Repository: mesos > > > Description > ------- > > Added documentation for shareable resources. > > > Diffs > ----- > > docs/home.md ad59eb1722b49cd72454795c095ddbd1ec1eb4dd > docs/shared-resources.md PRE-CREATION > > Diff: https://reviews.apache.org/r/45967/diff/ > > > Testing > ------- > > Tests successful. > > > Thanks, > > Anindya Sinha > >
