You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mesos.apache.org by ji...@apache.org on 2016/02/26 20:43:21 UTC
[6/6] mesos git commit: Updated docs for reservation, volumes,
and authZ.
Updated docs for reservation, volumes, and authZ.
This updates the authorization documentation to include the new `roles`
object for the `CreateVolume` and `ReserveResources` ACLs. The docs for
persistent volumes and dynamic reservations are also updated to reflect
the new authorization behavior. A note has been added to `upgrades.md`
detailing the impact of these changes on upgrades.
Review: https://reviews.apache.org/r/43800/
Project: http://git-wip-us.apache.org/repos/asf/mesos/repo
Commit: http://git-wip-us.apache.org/repos/asf/mesos/commit/89501205
Tree: http://git-wip-us.apache.org/repos/asf/mesos/tree/89501205
Diff: http://git-wip-us.apache.org/repos/asf/mesos/diff/89501205
Branch: refs/heads/master
Commit: 895012058d306715b7e44890f65801496bd7e86b
Parents: b234d36
Author: Greg Mann <gr...@mesosphere.io>
Authored: Fri Feb 26 11:43:01 2016 -0800
Committer: Jie Yu <yu...@gmail.com>
Committed: Fri Feb 26 11:43:01 2016 -0800
----------------------------------------------------------------------
docs/authorization.md | 81 ++++++++++++++++++++++++++++++++----------
docs/persistent-volume.md | 13 ++++---
docs/reservation.md | 20 +++++------
docs/upgrades.md | 4 +++
4 files changed, 85 insertions(+), 33 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/mesos/blob/89501205/docs/authorization.md
----------------------------------------------------------------------
diff --git a/docs/authorization.md b/docs/authorization.md
index bbb4f2a..feb0ddd 100644
--- a/docs/authorization.md
+++ b/docs/authorization.md
@@ -36,18 +36,16 @@ The currently supported `Subjects` are:
1. "principals"
- Framework principals (used by "register_frameworks", "run_tasks", "reserve", "unreserve", "create_volumes", and "destroy_volumes" actions)
- - Usernames (used by "teardown_frameworks", "set_quotas", "remove_quotas", "reserve", "unreserve", "create_volumes", and "destroy_volumes" actions)
+ - Operator usernames (used by "teardown_frameworks", "set_quotas", "remove_quotas", "reserve", "unreserve", "create_volumes", and "destroy_volumes" actions)
The currently supported `Objects` are:
-1. "roles": Resource [roles](roles.md) that framework can register with (used by "register_frameworks" and "set_quotas" actions)
-2. "users": Unix user to launch the task/executor as (used by "run_tasks" actions)
+1. "roles": Resource [roles](roles.md) that frameworks can register with, [reserve resources](reservation.md) for, or create [persistent volumes](persistent-volume.md) for (used by "register_frameworks", "set_quotas", "reserve_resources", and "create_volumes" actions).
+2. "users": Unix user to launch the task/executor as (used by "run_tasks" actions).
3. "framework_principals": Framework principals that can be torn down by HTTP POST (used by "teardown_frameworks" actions).
-4. "resources": Resources that can be reserved. Currently the only types considered by the default authorizer are `ANY` and `NONE` (used by "reserves" action).
-5. "reserver_principals": Framework principals whose reserved resources can be unreserved (used by "unreserves" action).
-6. "volume_types": Types of volumes that can be created by a given principal. Currently the only types considered by the default authorizer are `ANY` and `NONE` (used by "create_volumes" action).
-7. "creator_principals": Principals whose persistent volumes can be destroyed (used by "destroy_volumes" action).
-8. "quota_principals": Principals that set the quota to be removed (used by "remove_quotas" action)
+4. "reserver_principals": Framework principals whose reserved resources can be unreserved (used by "unreserves" action).
+5. "creator_principals": Principals whose persistent volumes can be destroyed (used by "destroy_volumes" action).
+6. "quota_principals": Principals that set the quota to be removed (used by "remove_quotas" action).
> NOTE: Both `Subjects` and `Objects` can be either an array of strings or one of the special values `ANY` or `NONE`.
@@ -214,7 +212,7 @@ In a real-world organization, principals and roles might be used to represent va
]
}
-9. The principal `foo` can reserve any resources, and no other principal can reserve resources.
+9. The principal `foo` can reserve resources for any role, and no other principal can reserve resources.
{
"permissive": false,
@@ -223,14 +221,14 @@ In a real-world organization, principals and roles might be used to represent va
"principals": {
"values": ["foo"]
},
- "resources": {
+ "roles": {
"type": "ANY"
}
}
]
}
-10. The principal `foo` cannot reserve any resources, and any other principal (or framework without a principal) can reserve resources.
+10. The principal `foo` cannot reserve resources, and any other principal (or framework without a principal) can reserve resources for any role.
{
"reserve_resources": [
@@ -238,14 +236,30 @@ In a real-world organization, principals and roles might be used to represent va
"principals": {
"values": ["foo"]
},
- "resources": {
+ "roles": {
"type": "NONE"
}
}
]
}
-11. 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.
+11. The principal `foo` can reserve resources only for roles `prod` and `dev`, and no other principal (or framework without a principal) can reserve resources for any role.
+
+ {
+ "permissive": false,
+ "reserve_resources": [
+ {
+ "principals": {
+ "values": ["foo"]
+ },
+ "roles": {
+ "values": ["prod", "dev"]
+ }
+ }
+ ]
+ }
+
+12. 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.
{
"permissive": false,
@@ -269,7 +283,7 @@ In a real-world organization, principals and roles might be used to represent va
]
}
-12. The principal `foo` can create persistent volumes, and no other principal can create persistent volumes.
+13. The principal `foo` can create persistent volumes for any role, and no other principal can create persistent volumes.
{
"permissive": false,
@@ -278,14 +292,45 @@ In a real-world organization, principals and roles might be used to represent va
"principals": {
"values": ["foo"]
},
- "volume_types": {
+ "roles": {
"type": "ANY"
}
}
]
}
-13. 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.
+14. The principal `foo` cannot create persistent volumes for any role, and any other principal can create persistent volumes for any role.
+
+ {
+ "create_volumes": [
+ {
+ "principals": {
+ "values": ["foo"]
+ },
+ "roles": {
+ "type": "NONE"
+ }
+ }
+ ]
+ }
+
+15. The principal `foo` can create persistent volumes only for roles `prod` and `dev`, and no other principal can create persistent volumes for any role.
+
+ {
+ "permissive": false,
+ "create_volumes": [
+ {
+ "principals": {
+ "values": ["foo"]
+ },
+ "roles": {
+ "values": ["prod", "dev"]
+ }
+ }
+ ]
+ }
+
+16. 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.
{
"permissive": false,
@@ -309,7 +354,7 @@ In a real-world organization, principals and roles might be used to represent va
]
}
-14. 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.
+17. 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.
{
"permissive": false,
@@ -333,7 +378,7 @@ In a real-world organization, principals and roles might be used to represent va
]
}
-15. 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.
+18. 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.
{
"permissive": false,
http://git-wip-us.apache.org/repos/asf/mesos/blob/89501205/docs/persistent-volume.md
----------------------------------------------------------------------
diff --git a/docs/persistent-volume.md b/docs/persistent-volume.md
index 2a794a5..f772405 100644
--- a/docs/persistent-volume.md
+++ b/docs/persistent-volume.md
@@ -29,11 +29,14 @@ Persistent volumes can also be created on isolated and auxiliary disks by
reserving [multiple disk resources](multiple-disk.md).
Persistent volumes can be created by __operators__ and authorized
-__frameworks__. We require a `principal` from the operator or framework in order
-to authenticate/authorize the operations. Permissions are specified via the
-existing ACL mechanism. To use authorization with reserve, unreserve, create,
-and destroy operations, the Mesos master must be configured with the desired
-ACLs. For more information, see the
+__frameworks__. By default, frameworks and operators can create volumes for any
+role and destroy any persistent volumes. [Authorization](authorization.md)
+allows this behavior to be limited so that volumes can only be created for
+particular roles and only particular volumes can be destroyed. For these
+operations to be authorized, the framework or operator should provide a
+`principal` to identify itself. To use authorization with reserve, unreserve,
+create, and destroy operations, the Mesos master must be configured with the
+appropriate ACLs. For more information, see the
[authorization documentation](authorization.md).
* `Offer::Operation::Create` and `Offer::Operation::Destroy` messages are
http://git-wip-us.apache.org/repos/asf/mesos/blob/89501205/docs/reservation.md
----------------------------------------------------------------------
diff --git a/docs/reservation.md b/docs/reservation.md
index b98ebe6..cbf0a08 100644
--- a/docs/reservation.md
+++ b/docs/reservation.md
@@ -45,20 +45,20 @@ That is, statically reserved resources cannot be reserved for another role nor
be unreserved. Dynamic reservation enables operators and authorized frameworks
to reserve and unreserve resources after slave-startup.
-We require a `principal` from the operator or framework in order to
-authenticate/authorize the operations. Permissions are specified via the
-existing ACL mechanism. To use authorization with reserve/unreserve operations,
-the Mesos master must be configured with the desired ACLs. For more information,
-see the [authorization documentation](authorization.md).
+By default, frameworks and operators can reserve resources for any role, and can
+unreserve any dynamically reserved resources. [Authorization](authorization.md)
+allows this behavior to be limited so that only particular roles can be reserved
+for, and only particular resources can be unreserved. For these operations to be
+authorized, the framework or operator should provide a `principal` to identify
+itself. To use authorization with reserve/unreserve operations, the Mesos master
+must be configured with the appropriate ACLs. For more information, see the
+[authorization documentation](authorization.md).
* `Offer::Operation::Reserve` and `Offer::Operation::Unreserve` messages are
available for __frameworks__ to send back via the `acceptOffers` API as a
- response to a resource offer. Each framework may only reserve resources for
- its own role.
+ response to a resource offer.
* `/reserve` and `/unreserve` HTTP endpoints allow __operators__ to manage
- dynamic reservations through the master. Operators may currently reserve
- resources for any role, although this
- [will change](https://issues.apache.org/jira/browse/MESOS-4591).
+ dynamic reservations through the master.
In the following sections, we will walk through examples of each of the
interfaces described above.
http://git-wip-us.apache.org/repos/asf/mesos/blob/89501205/docs/upgrades.md
----------------------------------------------------------------------
diff --git a/docs/upgrades.md b/docs/upgrades.md
index 4f30d72..21faea8 100644
--- a/docs/upgrades.md
+++ b/docs/upgrades.md
@@ -6,6 +6,10 @@ layout: documentation
This document serves as a guide for users who wish to upgrade an existing Mesos cluster. Some versions require particular upgrade techniques when upgrading a running cluster. Some upgrades will have incompatible changes.
+## Upgrading from 0.27.x to 0.28.x ##
+
+* Mesos 0.28 changes the definitions of two ACLs used for authorization. The objects of the `ReserveResources` and `CreateVolume` ACLs have been changed to `roles`. In both cases, principals can now be authorized to perform these operations for particular roles. This means that by default, a framework or operator can reserve resources/create volumes for any role. To restrict this behavior, [ACLs can be added](authorization.md) to the master which authorize principals to reserve resources/create volumes for specified roles only. Previously, frameworks could only reserve resources for their own role; this behavior can be preserved by configuring the `ReserveResources` ACLs such that the framework's principal is only authorized to reserve for the framework's role. **NOTE** This renders existing `ReserveResources` and `CreateVolume` ACL definitions obsolete; if you are authorizing these operations, your ACL definitions should be updated.
+
## Upgrading from 0.26.x to 0.27.x ##
* Mesos 0.27 introduces the concept of _implicit roles_. In previous releases, configuring roles required specifying a static whitelist of valid role names on master startup (via the `--roles` flag). In Mesos 0.27, if `--roles` is omitted, _any_ role name can be used; controlling which principals are allowed to register as which roles should be done using [ACLs](authorization.md). The role whitelist functionality is still supported but is deprecated.