You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mesos.apache.org by vi...@apache.org on 2014/06/28 00:07:41 UTC
git commit: Added documentation for authorization.
Repository: mesos
Updated Branches:
refs/heads/master 5bea0309e -> d04b07ad5
Added documentation for authorization.
Review: https://reviews.apache.org/r/23104
Project: http://git-wip-us.apache.org/repos/asf/mesos/repo
Commit: http://git-wip-us.apache.org/repos/asf/mesos/commit/d04b07ad
Tree: http://git-wip-us.apache.org/repos/asf/mesos/tree/d04b07ad
Diff: http://git-wip-us.apache.org/repos/asf/mesos/diff/d04b07ad
Branch: refs/heads/master
Commit: d04b07ad59e83d9ffc0c4cfe24a0cb7b21bc7c69
Parents: 5bea030
Author: Vinod Kone <vi...@gmail.com>
Authored: Wed Jun 25 17:46:48 2014 -0700
Committer: Vinod Kone <vi...@gmail.com>
Committed: Fri Jun 27 14:52:14 2014 -0700
----------------------------------------------------------------------
docs/authorization.md | 180 +++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 180 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/mesos/blob/d04b07ad/docs/authorization.md
----------------------------------------------------------------------
diff --git a/docs/authorization.md b/docs/authorization.md
new file mode 100644
index 0000000..fea743a
--- /dev/null
+++ b/docs/authorization.md
@@ -0,0 +1,180 @@
+---
+layout: documentation
+---
+
+# Authorization
+
+Mesos 0.20.0 adds support for framework authorization. Authorization allows
+
+ 1. Frameworks to only launch tasks/executors as authorized `users`.
+ 2. Frameworks to be able to receive offers for authorized `roles`.
+ 3. HTTP endpoints exposed by Mesos to be accessible to authorized `clients`.
+
+> NOTE: While ACLs support for HTTP is present, currently access to the HTTP endpoints are not authorized.
+
+## ACLs
+
+Authorization is implemented via Access Control Lists (ACLs). For each of the 3 cases described above there is a corresponding ACL(s) that can be set to restrict access. Operators can setup ACLs in JSON format. See [mesos.proto](https://github.com/apache/mesos/blob/master/include/mesos/mesos.proto) for details.
+
+Each ACL specifies a set of `Subjects` that can perform an `Action` on a set of `Objects`.
+
+The currently supported `Actions` are :
+
+1. "run_tasks" : Run tasks/executors
+2. "receive_offers" : Receive offers
+3. "http_get" : HTTP GET access
+4. "http_put" : HTTP_PUT access
+
+The currently supported `Subjects` are :
+
+1. "principals" : Framework principals (used by "run_tasks" and "receive_offers" actions)
+2. "usernames" : Username used in HTTP Basic/Digest authentication. (used by "http_get" and "http_put" actions)
+3. "ips" : IP Addresses of the clients (used by "http_get" and "http_put" actions)
+4. "hostnames" : Hostnames of the clients (used by "http_get" and "http_put" actions)
+
+The currently supported `Objects` are :
+
+1. "users" : Unix user to launch the task/executor as (used by "run_tasks" action)
+2. "roles" : Resource roles to receive offers from (used by "receive_offers" action)
+3. "urls" : HTTP URL endpoint exposed by the master (used by "http_get" and "http_put" actions)
+
+> NOTE: Both `Subjects` and `Objects` can take a list of strings or special values (`ANY` and `NONE`).
+
+
+## How does it work?
+
+The Mesos master checks the ACLs to verify whether a request is authorized or not. For example, when a framework launches a task, "run_tasks" ACLs are checked to see if the framework (`FrameworkInfo.principal`) is authorized to run the task/executor as the given user. If not authorized, the launch is rejected and the framework gets a TASK_LOST.
+
+Similarly, when a framework (re-)registers the Mesos master checks whether it is authorized to receive offers for given resource role (`FrameworkInfo.role`). If not authorized, the framework is not allowed to (re-)register and gets an Error message back.
+
+While not yet implemented, GET/PUT access to HTTP endpoints exposed by the Mesos master will be authorized in a similar way.
+
+There are couple of important things to note:
+
+1. ACLs are matched in the order that they are setup. In other words, the first matching ACL determines whether a request is authorized or not.
+
+2. If none of the specified ACLs match the given request, whether the request is authorized or not is defined by `ACLs.permissive` field. By default this "true" i.e., a non-matching request is authorized.
+
+
+## Examples
+
+1. Frameworks `foo` and `bar` can run tasks as user `alice`.
+
+ {
+ "run_tasks": [
+ {
+ "principals": { "values": ["foo", "bar"] },
+ "users": { "values": ["alice"] }
+ }
+ ],
+ }
+
+2. Any framework can run tasks as user `guest`.
+
+ {
+ "run_tasks": [
+ {
+ "principals": { "type": "ANY" },
+ "users": { "values": ["guest"] }
+ }
+ ],
+ }
+
+3. No framework can run tasks as `root`.
+
+ {
+ "run_tasks": [
+ {
+ "principals": { "type": "NONE" },
+ "users": { "values": ["root"] }
+ }
+ ],
+ }
+
+
+4. Framework `foo` can run tasks only as user `guest` and no other user.
+
+ {
+ "run_tasks": [
+ {
+ "principals": { "values": [ "foo" ] },
+ "users": { "values": ["guest"] }
+ },
+ {
+ "principals": { "values": [ "foo" ] },
+ "users": { "type": ["NONE"] }
+ }
+ ],
+ }
+
+
+
+
+5. Framework `foo` can be offered resources for `analytics` and `ads` roles.
+
+ {
+ "receive_offers": [
+ {
+ "principals": { "values": ["foo"] },
+ "roles": { "values": ["analytics", "ads"] }
+ }
+ ],
+ }
+
+
+6. Only framework `foo` and no one else can be offered resources for `analytics` role.
+
+ {
+ "receive_offers": [
+ {
+ "principals": { "values": ["foo"] },
+ "roles": { "values": ["analytics"] }
+ },
+ {
+ "principals": { "type": "NONE" },
+ "roles": { "values": ["analytics"] }
+ }
+ ],
+ }
+
+7. Framework `foo` can only receive offers for `analytics` role but no other roles. Also, no other framework can receive offers for any role.
+
+ {
+ "permissive" : "false",
+
+ "receive_offers": [
+ {
+ "principals": { "values": ["foo"] },
+ "roles": { "values": ["analytics"] }
+ }
+ ],
+ }
+
+
+## Enabling authorization.
+
+As part of this feature, a new flag was added to the master.
+
+* `acls` : The value could be a JSON formatted string of ACLs
+ or a file path containing the JSON formatted ACLs used
+ for authorization. Path could be of the form 'file:///path/to/file'
+ or '/path/to/file'.
+ See the ACLs protobuf in mesos.proto for the expected format.
+
+ Example:
+ {
+ "run_tasks": [
+ {
+ "principals": { "values": ["a", "b"] },
+ "users": { "values": ["root"] }
+ }
+ ],
+ "receive_offers": [
+ {
+ "principals": { "type": "ANY" },
+ "roles": { "values": ["foo"] }
+ }
+ ]
+ }
+
+**For the complete list of master options: ./mesos-master.sh --help**