Repository: mesos Updated Branches: refs/heads/master fc4507da5 -> 71e5099c5
Documented quota authorization changes. Review: https://reviews.apache.org/r/47400/ Project: http://git-wip-us.apache.org/repos/asf/mesos/repo Commit: http://git-wip-us.apache.org/repos/asf/mesos/commit/71e5099c Tree: http://git-wip-us.apache.org/repos/asf/mesos/tree/71e5099c Diff: http://git-wip-us.apache.org/repos/asf/mesos/diff/71e5099c Branch: refs/heads/master Commit: 71e5099c55bb5fd064ef5efe59ed780ad1e93060 Parents: fc4507d Author: Zhitao Li <zhitaoli...@gmail.com> Authored: Thu May 19 09:04:20 2016 +0200 Committer: Alexander Rukletsov <al...@apache.org> Committed: Thu May 19 09:39:37 2016 +0200 ---------------------------------------------------------------------- CHANGELOG | 6 ++++++ docs/authorization.md | 33 +++++++++++++++++---------------- docs/quota.md | 6 +++++- docs/upgrades.md | 12 +++++++++++- 4 files changed, 39 insertions(+), 18 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/mesos/blob/71e5099c/CHANGELOG ---------------------------------------------------------------------- diff --git a/CHANGELOG b/CHANGELOG index 31ca5e5..ef9c630 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -56,6 +56,12 @@ Deprecations: * [MESOS-3781] - Deprecated flags with keyword 'slave' in favor of 'agent'. + * [MESOS-5155] - Deprecated `SET_QUOTA_WITH_ROLE` and + `DESTROY_QUOTA_WITH_PRINCIPAL` authorization actions together with the + corresponding ACLs in favor of a unified `UPDATE_QUOTA_WITH_ROLE`. This + change is applicable to both local authorizer as well as any custom + authorizer module. + Additional API Changes: * [MESOS-4580] - Returning `202` (Accepted) for /reserve and related endpoints. http://git-wip-us.apache.org/repos/asf/mesos/blob/71e5099c/docs/authorization.md ---------------------------------------------------------------------- diff --git a/docs/authorization.md b/docs/authorization.md index 9a359dc..723d98c 100644 --- a/docs/authorization.md +++ b/docs/authorization.md @@ -121,13 +121,13 @@ entries, each representing an authorizable action: |`register_frameworks`|Framework principal.|Resource [roles](roles.md) of the framework.|(Re-)registering of frameworks.| |`run_tasks`|Framework principal.|UNIX user to launch the task as.|Launching tasks/executors by a framework.| |`teardown_frameworks`|Operator username.|Principals whose frameworks can be shutdown by the operator.|Tearing down frameworks.| -|`set_quotas`|Operator username.|Resource role whose quota will be set.|Setting quotas for roles.| -|`remove_quotas`|Operator username.|Principals whose quotas can be destroyed by the operator.|Destroying quotas.| |`reserve_resources`|Framework principal or Operator username.|Resource role of the reservation.|[Reserving](reservation.md) resources.| |`unreserve_resources`|Framework principal or Operator username.|Principals whose resources can be unreserved by the operator.|[Unreserving](reservation.md) resources.| |`create_volumes`|Framework principal or Operator username.|Resource role of the volume.|Creating [volumes](persistent-volumes.md).| |`destroy_volumes`|Framework principal or Operator username.|Principals whose volumes can be destroyed by the operator.|Destroying [volumes](persistent-volumes.md).| -|`update_weights`|Operator username.|Roles whose weights can be updated by the operator.|Updating weights.| +|`get_quotas`|Operator username.|Resource role whose quota status will be queried.|Querying [quota](quota.md) status for roles.| +|`update_quotas`|Operator username.|Resource role whose quota will be updated.|Modifying [quotas](quota.md) for roles.| +|`update_weights`|Operator username.|Resource roles whose weights can be updated by the operator.|Updating weights.| ### Examples @@ -249,7 +249,7 @@ user. ``` Principals `foo` and `bar` can run tasks as the agent operating system user -`alice` and no other user. No other principals can run tasks. +`alice` and no other user. No other principal can run tasks. ```json { @@ -412,7 +412,7 @@ any role. The principal `foo` can unreserve resources reserved by itself and by the principal `bar`. The principal `bar`, however, can only unreserve its own -resources. No other principals can unreserve resources. +resources. No other principal can unreserve resources. ```json { @@ -496,7 +496,7 @@ The principal `foo` can create persistent volumes only for roles `prod` and The principal `foo` can destroy volumes created by itself and by the principal `bar`. The principal `bar`, however, can only destroy its own volumes. No other -principals can destroy volumes. +principal can destroy volumes. ```json { @@ -522,13 +522,14 @@ principals can destroy volumes. } ``` -The principal `ops` can set quota for any role. The principal `foo`, however, -can only set quota for `foo-role`. No other principals can set quota. +The principal `ops` can query quota status for any role. The principal `foo`, +however, can only query quota status for `foo-role`. No other principal can +query quota status. ```json { "permissive": false, - "set_quotas": [ + "get_quotas": [ { "principals": { "values": ["ops"] @@ -549,19 +550,19 @@ can only set quota for `foo-role`. No other principals can set quota. } ``` -The principal `ops` can remove quota which was set by any principal. The -principal `foo`, however, can only remove quota which was set by itself. No -other principals can remove quota. +The principal `ops` can update quota information (set or remove) for any role. +The principal `foo`, however, can only update quota for `foo-role`. No other +principal can update quota. ```json { "permissive": false, - "remove_quotas": [ + "update_quotas": [ { "principals": { "values": ["ops"] }, - "quota_principals": { + "roles": { "type": "ANY" } }, @@ -569,8 +570,8 @@ other principals can remove quota. "principals": { "values": ["foo"] }, - "quota_principals": { - "values": ["foo"] + "roles": { + "values": ["foo-role"] } } ] http://git-wip-us.apache.org/repos/asf/mesos/blob/71e5099c/docs/quota.md ---------------------------------------------------------------------- diff --git a/docs/quota.md b/docs/quota.md index 797e134..848254a 100644 --- a/docs/quota.md +++ b/docs/quota.md @@ -156,7 +156,8 @@ to the `/quota` endpoint. $ curl -X GET http://<master-ip>:<port>/quota The response message body includes a JSON representation of the current quota -status, for example: +status for role(s) which principal is authorized to query quota status (if +authorization is enabled). For example: { "infos": [ @@ -185,6 +186,9 @@ The operator will receive one of the following HTTP response codes: * `200 OK`: Success. * `401 Unauthorized`: Unauthenticated request. +__NOTE:__ If the principal is not authorized to query quota status for certain + role(s), the result will not include corresponding quota information. + # How does it work? There are several stages in the lifetime of a quota issued by operator. First http://git-wip-us.apache.org/repos/asf/mesos/blob/71e5099c/docs/upgrades.md ---------------------------------------------------------------------- diff --git a/docs/upgrades.md b/docs/upgrades.md index 5927436..f3ca3d4 100644 --- a/docs/upgrades.md +++ b/docs/upgrades.md @@ -52,6 +52,9 @@ We categorize the changes as follows: </ul> </td> <td style="word-wrap: break-word; overflow-wrap: break-word;"><!--Flags--> + <ul style="padding-left:10px;"> + <li>CD <a href="#0-29-x-quota-authorization">Quota Authorization</a></li> + </ul> </td> <td style="word-wrap: break-word; overflow-wrap: break-word;"><!--Framework API--> </td> @@ -162,7 +165,14 @@ We categorize the changes as follows: <a name="0-29-x-credentials"></a> * Mesos 0.29 deprecates the use of plain text credential files in favor of JSON-formatted credential files. -* When a persistent volume is destroyed, Mesos will now remove any data that was stored on the volume from the filesystem of the appropriate agent. In prior versions of Mesos, destroying a volume would not delete data (this was a known missing feature that has now been implemented). +<a name="0-29-x-quota-authorization"></a> +* Mesos 0.29 deprecates `SET_QUOTA_WITH_ROLE` and `DESTROY_QUOTA_WITH_PRINCIPAL` actions with `UPDATE_QUOTA_WITH_ROLE`, as well as the `SetQuota` and `RemoveQuota` ACLs with `UpdateQuota` ACL, to control which principal(s) is authorized to set, remove and (in future releases) update quota for role(s). A new `GET_QUOTA_WITH_ROLE` action and `get_quotas` ACL are introduced to control which principal(s) can query quota status for given role(s). This affects `--acls` flag for local authorizer in the following way: + * It is not allowed to specify `update_quotas` and any of `set_quotas` or `remove_quotas` at the same time. Local authorizor will error out in such case; + * If `set_quotas` or `remove_quotas` were set previously, operator should upgrade binary first, after which the deprecated ACLs are still reinforced; + * After upgrade is verified, operator should replace deprecated values for `set_quotas` and `remove_quotas` with compatible values for `update_quotas`; + * If desired, operator can use `get_quotas` after upgrade to control which principal(s) is allowed to query quota status for given role(s). + +* When a persistent volume is destroyed, Mesos will now remove any data that was stored on the volume from the filesystem of the appropriate slave. In prior versions of Mesos, destroying a volume would not delete data (this was a known missing feature that has now been implemented). * Mesos 0.29 changes the HTTP status code of the following endpoints from `200 OK` to `202 Accepted`: * `/reserve`