First off, if we're going to have a /reservations endpoint, we should follow the same PUT+DELETE pattern for reserve+unreserve, instead of POST+PUT. And we should consider converting /create and /destroy to PUT+DELETE verbs on a /volumes endpoint.
Secondly, we're going to have to support the previous endpoints through a deprecation cycle (~6mo), so there's no rush to get those changes in at the same time as or before dynamic weights. Finally, it seems like the only real difference between the two proposals is whether (1) /roles will be the catch-all "show me everything about each role" endpoint that admins/users will request when they want to see the current state of their reservations/quota/weights(/volumes?), or (2) each endpoint with create/update (PUT/POST) and DELETE actions will also have a GET action that lists the current state of quotas or weights or whatever, and /roles can (continue to) show whatever subset of information it wants. In the long-run, I like the idea of consistency among these types of endpoints, but for the near-term scope of dynamic weights, I think you can leave the other endpoints alone (including /roles) and just implement the PUT/POST+DELETE for /weights to create/update+delete weight configurations. Since weights are already displayed in /roles, you can leave them there and not worry about creating a GET for /weights. That's the least amount of work/disruption you have to do to deliver the feature/functionality, includes no wasted work no matter whether we go with your proposal 1 or 2 in the long run. On that note, we should create a JIRA Epic for defining a proper RESTful API for these actions and migrating all relevant endpoints to the new model. Cheers, -Adam- P.S. Seems like RESTful APIs prefer plural nouns over singular, so it would be /weights instead of /weight. On Wed, Dec 16, 2015 at 4:02 AM, Yongqiao Wang <grady.w...@foxmail.com> wrote: > Hi guys, > > Currently, Mesos uses the following ways to configure role-related objects: > 1. For dynamic reserve resources for a role, /reserve endpoint is used to > reserve, another /unreserve endpoint is used to unreserve, maybe the third > endpoint should be added to show resource reservation of a role later due to > someone has issue a requirement of this. > > 2. For configuring quota for a role, only one endpoint /quota is provided to > set/remove/show quota information. > > 3. For role information, /roles endpoint is only provided to show role > information(contains role name, weight and the registered frameworks and > their used resources) that master is configured with (specified by --roles > when Mesos master startup), and the configured roles do not be changed by > this endpoint at runtime(without restart Mesos master). And current there > are two proposals in progress to support re-configure roles at runtime: > - Dynamic Roles(MESOS-3177): roles are stored in the registry and > added/deleted/removed/shown via /roles HTTP endpoints with the authorized > principles. > - Implicit Roles(MESOS-3988): any role will be allowed, subject to the > ACL/authorization system. > > After having a discussion, we all prefer to implement Implicit Roles rather > than Dynamic Roles, but dynamic weight is out scope of Implicit Roles, so a > new project will need be issued for dynamic weight, and like quota, a new > endpoint(such as /weight) will be added to update weight of a role at > runtime. > > For above design and implementation, they are all different. In order to > improve the user experience, some enhancements should be done for the same > behaviours between above endpoints. I have two proposals as below: > > Proposals 1, using /roles endpoint to centralizely show all roles > information and using other endpoints(/weight,/quota,/reservation) to only > set the role-related configuration. > - Implement Implicit Roles to support dynamically implicitly add/remove role > at runtime. and enhance /roles endpoint to centralizely show all role > information which contains role name, weight, resource reservation, > quota,etc. > - For reservation, merge /reserve and /unreserve together, end user can use > one endpoint /reservation(should better be a noun for a Restful endpoint) to > reserve(POST method) and unreserve(PUT method) resource, and does not > support to show reservation with this endpoint; > - For setting quota, end user can only use /quota endpoint to set and remove > quota, and does not support to show quota with this endpoint; > - For dynamic weight, add a new endpoint /weight, end user can use to update > weight of a role, and does not support to show weights with this endpoint. > > > Proposals 2, keep the old behaviour of /roles endpoint and using other > endpoints(/weight,/quota,/reservation) to set and show the role-related > configuration. > - Implement Implicit Roles to support dynamic implicitly configure role at > runtime. and keep the old behaviour of /roles to only show role information > which contains role name, weight and the registered frameworks and their > used resources. > - For reservation, merge /reserve and /unreserve together, end user can use > one endpoint /reservation to reserve(POST method) resource, unreserve(PUT > method) resource, show reserved resources(GET method); > - For setting quota, keep the current behaviour, and end user can use /quota > endpoint to set(PUT method), remove(DELETE method) and show(GET method) > quota; > - For dynamic weight, add a new endpoint /weight, end user can use to > update(PUT method) weight of a role, and show(GET method) weight > information. > > I prefer the proposal 1, because cluster administrator can use /roles > endpoint to show the global resource plan of the cluster. I would like to > listen from you guys on the above proposals, and any other comments are > welcome. > > ------------------ > Regards! > Grady YQ. Wang（王勇桥） >
