You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mesos.apache.org by me...@apache.org on 2015/12/15 06:27:44 UTC
mesos git commit: Improved authorization documentation.
Repository: mesos
Updated Branches:
refs/heads/master 688d3a097 -> 2943cda00
Improved authorization documentation.
Removed reference to deprecated endpoint, avoided line wrapping in JSON
examples, and made various other fixes.
Review: https://reviews.apache.org/r/40829/
Project: http://git-wip-us.apache.org/repos/asf/mesos/repo
Commit: http://git-wip-us.apache.org/repos/asf/mesos/commit/2943cda0
Tree: http://git-wip-us.apache.org/repos/asf/mesos/tree/2943cda0
Diff: http://git-wip-us.apache.org/repos/asf/mesos/diff/2943cda0
Branch: refs/heads/master
Commit: 2943cda0002bb527d4d7f2cadae93cf43a8e1dca
Parents: 688d3a0
Author: Neil Conway <ne...@gmail.com>
Authored: Mon Dec 14 21:27:19 2015 -0800
Committer: Adam B <ad...@mesosphere.io>
Committed: Mon Dec 14 21:27:19 2015 -0800
----------------------------------------------------------------------
docs/authorization.md | 257 +++++++++++++++++++++++----------------------
1 file changed, 134 insertions(+), 123 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/mesos/blob/2943cda0/docs/authorization.md
----------------------------------------------------------------------
diff --git a/docs/authorization.md b/docs/authorization.md
index f5ed75f..1fc0e3f 100644
--- a/docs/authorization.md
+++ b/docs/authorization.md
@@ -6,20 +6,20 @@ layout: documentation
Mesos 0.20.0 adds support for framework authorization. Authorization allows
- 1. Frameworks to (re-)register with authorized `roles`.
- 2. Frameworks to launch tasks/executors as authorized `users`.
- 3. Authorized `principals` to shutdown framework(s) through "/shutdown" HTTP endpoint.
+ 1. Frameworks to (re-)register with authorized _roles_.
+ 2. Frameworks to launch tasks/executors as authorized _users_.
+ 3. Authorized _principals_ to shutdown frameworks through the "/teardown" HTTP endpoint.
## 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.
+Authorization is implemented via Access Control Lists (ACLs). For each of the 3 cases described above, ACLs can be used 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. "register_frameworks": Register Frameworks
+1. "register_frameworks": Register frameworks
2. "run_tasks": Run tasks/executors
3. "shutdown_frameworks": Shutdown frameworks
@@ -31,149 +31,160 @@ The currently supported `Subjects` are:
The currently supported `Objects` are:
-1. "roles": Resource [roles](roles.md) that framework can register with (used by "register_frameworks" action)
-2. "users": Unix user to launch the task/executor as (used by "run_tasks" action)
-3. "framework_principals": Framework principals that can be shutdown by HTTP POST (used by "shutdown_frameworks" action).
+1. "roles": Resource [roles](roles.md) that framework can register with (used by "register_frameworks" actions)
+2. "users": Unix user to launch the task/executor as (used by "run_tasks" actions)
+3. "framework_principals": Framework principals that can be shutdown by HTTP POST (used by "shutdown_frameworks" actions).
-> NOTE: Both `Subjects` and `Objects` can take a list of strings or special values (`ANY` or `NONE`).
+> NOTE: Both `Subjects` and `Objects` can be either an array of strings or one of the special values `ANY` or `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 (re-)registers with the master, the "register_frameworks" ACLs are checked to see if the framework (`FrameworkInfo.principal`) is authorized to receive offers for the given resource role (`FrameworkInfo.role`). If not authorized, the framework is not allowed to (re-)register and gets an `Error` message back (which aborts the scheduler driver).
+For example, when a framework (re-)registers with the master, "register_frameworks" ACLs are checked to see if the framework (`FrameworkInfo.principal`) is authorized to receive offers for the given resource role (`FrameworkInfo.role`). If not authorized, the framework is not allowed to (re-)register and gets an `Error` message back (which aborts the scheduler driver).
-Similarly, when a framework launches a task(s), "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.
-
-In the same vein, when a user/principal attempts to shutdown a framework through the "/teardown" HTTP endpoint on the master, "shutdown_frameworks" ACLs are checked to see if the `principal` is authorized to shutdown the given framework. If not authorized, the shutdown is rejected and the user receives an `Unauthorized` HTTP response.
+Similarly, 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.
+In the same vein, when a user/principal attempts to shutdown a framework using the "/teardown" HTTP endpoint on the master, "shutdown_frameworks" ACLs are checked to see if the principal is authorized to shutdown the given framework. If not authorized, the shutdown is rejected and the user receives an `Unauthorized` HTTP response.
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.
+1. ACLs are matched in the order that they are specified. 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 is "true" i.e., a non-matching request is authorized.
+2. If no ACLs match a request, whether the request is authorized or not is determined by the `ACLs.permissive` field. This is "true" by default -- i.e., non-matching requests are authorized.
## Examples
1. Frameworks `foo` and `bar` can run tasks as user `alice`.
- {
- "run_tasks": [
- {
- "principals": { "values": ["foo", "bar"] },
- "users": { "values": ["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"] }
- }
- ]
- }
+ {
+ "run_tasks": [
+ {
+ "principals": { "type": "ANY" },
+ "users": { "values": ["guest"] }
+ }
+ ]
+ }
3. No framework can run tasks as `root`.
- {
- "run_tasks": [
- {
- "principals": { "type": "NONE" },
- "users": { "values": ["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 register with `analytics` and `ads` roles.
-
- {
- "register_frameworks": [
- {
- "principals": { "values": ["foo"] },
- "roles": { "values": ["analytics", "ads"] }
- }
- ]
- }
-
-
-6. Only framework `foo` and no one else can register with `analytics` role.
-
- {
- "register_frameworks": [
- {
- "principals": { "values": ["foo"] },
- "roles": { "values": ["analytics"] }
- },
- {
- "principals": { "type": "NONE" },
- "roles": { "values": ["analytics"] }
- }
- ]
- }
-
-7. Framework `foo` can only register with `analytics` role but no other roles. Also, no other framework can register with any roles.
-
- {
- "permissive" : false,
-
- "register_frameworks": [
- {
- "principals": { "values": ["foo"] },
- "roles": { "values": ["analytics"] }
- }
- ]
- }
-
-
-8. Only `ops` principal can shutdown any frameworks through "/teardown" HTTP endpoint.
-
- {
- "permissive" : false,
-
- "shutdown_frameworks": [
- {
- "principals": { "values": ["ops"] },
- "framework_principals": { "type": "ANY" }
- }
- ]
- }
-
-
-## 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.
-
-
-**For the complete list of master options: ./mesos-master.sh --help**
+ {
+ "run_tasks": [
+ {
+ "principals": { "values": ["foo"] },
+ "users": { "values": ["guest"] }
+ },
+ {
+ "principals": { "values": ["foo"] },
+ "users": { "type": "NONE" }
+ }
+ ]
+ }
+
+5. Framework `foo` can register with the `analytics` and `ads` roles.
+
+ {
+ "register_frameworks": [
+ {
+ "principals": {
+ "values": ["foo"]
+ },
+ "roles": {
+ "values": ["analytics", "ads"]
+ }
+ }
+ ]
+ }
+
+6. Only framework `foo` and no one else can register with the `analytics` role.
+
+ {
+ "register_frameworks": [
+ {
+ "principals": {
+ "values": ["foo"]
+ },
+ "roles": {
+ "values": ["analytics"]
+ }
+ },
+ {
+ "principals": {
+ "type": "NONE"
+ },
+ "roles": {
+ "values": ["analytics"]
+ }
+ }
+ ]
+ }
+
+7. Framework `foo` can only register with the `analytics` role but no other roles. Also, no other framework can register with any roles or run tasks.
+
+ {
+ "permissive": false,
+ "register_frameworks": [
+ {
+ "principals": {
+ "values": ["foo"]
+ },
+ "roles": {
+ "values": ["analytics"]
+ }
+ }
+ ]
+ }
+
+8. The `ops` principal can shutdown any framework using the "/teardown" HTTP endpoint. No other framework can register with any roles or run tasks.
+
+ {
+ "permissive": false,
+ "shutdown_frameworks": [
+ {
+ "principals": {
+ "values": ["ops"]
+ },
+ "framework_principals": {
+ "type": "ANY"
+ }
+ }
+ ]
+ }
+
+
+## Configuring authorization
+
+Authorization is configured by specifying the `--acls` flag when starting 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.
+
+For more information on master command-line flags, see the
+[configuration](configuration.md) page.