Repository: mesos Updated Branches: refs/heads/master 6d28a8474 -> 9ced78bf5
Added documentation about roles. Also removed a redundant (and arguably slightly wrong) assertion about the status of static reservations. Review: https://reviews.apache.org/r/39886 Project: http://git-wip-us.apache.org/repos/asf/mesos/repo Commit: http://git-wip-us.apache.org/repos/asf/mesos/commit/9ced78bf Tree: http://git-wip-us.apache.org/repos/asf/mesos/tree/9ced78bf Diff: http://git-wip-us.apache.org/repos/asf/mesos/diff/9ced78bf Branch: refs/heads/master Commit: 9ced78bf51ecb119554ec955ab5023f6842f5100 Parents: 6d28a84 Author: Neil Conway <[email protected]> Authored: Fri Nov 6 10:14:15 2015 -0800 Committer: Adam B <[email protected]> Committed: Fri Nov 6 10:16:49 2015 -0800 ---------------------------------------------------------------------- docs/attributes-resources.md | 2 + docs/authorization.md | 18 ++++----- docs/home.md | 1 + docs/reservation.md | 5 +-- docs/roles.md | 81 +++++++++++++++++++++++++++++++++++++++ 5 files changed, 94 insertions(+), 13 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/mesos/blob/9ced78bf/docs/attributes-resources.md ---------------------------------------------------------------------- diff --git a/docs/attributes-resources.md b/docs/attributes-resources.md index f712d09..5dfc7fc 100644 --- a/docs/attributes-resources.md +++ b/docs/attributes-resources.md @@ -46,6 +46,8 @@ The Mesos system can manage 3 different *types* of resources: scalars, ranges, a resourceRole : text | "*" +Note that `resourceRole` must be one of the [roles](roles.md) that was defined when the Mesos master was started. + ## Predefined Uses & Conventions The Mesos master has a few resources that it pre-defines in how it handles them. At the current time, this list consist of: http://git-wip-us.apache.org/repos/asf/mesos/blob/9ced78bf/docs/authorization.md ---------------------------------------------------------------------- diff --git a/docs/authorization.md b/docs/authorization.md index 2a5e747..16a1866 100644 --- a/docs/authorization.md +++ b/docs/authorization.md @@ -17,23 +17,23 @@ Authorization is implemented via Access Control Lists (ACLs). For each of the 3 Each ACL specifies a set of `Subjects` that can perform an `Action` on a set of `Objects`. -The currently supported `Actions` are : +The currently supported `Actions` are: -1. "register_frameworks" : Register Frameworks -2. "run_tasks" : Run tasks/executors -3. "shutdown_frameworks" : Shutdown frameworks +1. "register_frameworks": Register Frameworks +2. "run_tasks": Run tasks/executors +3. "shutdown_frameworks": Shutdown frameworks -The currently supported `Subjects` are : +The currently supported `Subjects` are: 1. "principals" - Framework principals (used by "register_frameworks" and "run_tasks" actions) - Usernames (used by "shutdown_frameworks" action) -The currently supported `Objects` are : +The currently supported `Objects` are: -1. "roles" : Resource roles 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" 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). > NOTE: Both `Subjects` and `Objects` can take a list of strings or special > values (`ANY` or `NONE`). http://git-wip-us.apache.org/repos/asf/mesos/blob/9ced78bf/docs/home.md ---------------------------------------------------------------------- diff --git a/docs/home.md b/docs/home.md index af88625..7aa785e 100644 --- a/docs/home.md +++ b/docs/home.md @@ -16,6 +16,7 @@ layout: documentation * [Mesos Containerizer](/documentation/latest/containerizer/) default containerizer, supports both Linux and POSIX systems. * [Docker Containerizer](/documentation/latest/docker-containerizer/) for launching a Docker image as a Task, or as an Executor. * [External Containerizer](/documentation/latest/external-containerizer/) for custom containerization implementations. +* [Roles](/documentation/latest/roles/) * [Framework Authentication](/documentation/latest/authentication/) * [Framework Authorization](/documentation/latest/authorization/) * [Framework Rate Limiting](/documentation/latest/framework-rate-limiting/) http://git-wip-us.apache.org/repos/asf/mesos/blob/9ced78bf/docs/reservation.md ---------------------------------------------------------------------- diff --git a/docs/reservation.md b/docs/reservation.md index 69bde76..81f21c3 100644 --- a/docs/reservation.md +++ b/docs/reservation.md @@ -10,10 +10,7 @@ which enabled operators to specify the reserved resources on slave startup. This was extended with __dynamic reservation__ in 0.23.0 which enabled operators and authorized __frameworks__ to dynamically reserve resources in the cluster. -No breaking changes were introduced with dynamic reservation, which means the -existing static reservation mechanism continues to be fully supported. - -In both types of reservations, resources are reserved for a __role__. +In both types of reservations, resources are reserved for a [__role__](roles.md). ## Static Reservation (since 0.14.0) http://git-wip-us.apache.org/repos/asf/mesos/blob/9ced78bf/docs/roles.md ---------------------------------------------------------------------- diff --git a/docs/roles.md b/docs/roles.md new file mode 100644 index 0000000..459d707 --- /dev/null +++ b/docs/roles.md @@ -0,0 +1,81 @@ +--- +layout: documentation +--- + +# Roles + +In Mesos, __roles__ can be used to specify that certain +[resources](attributes-resources.md) are reserved for the use of one or more +frameworks. Roles can be used to enable a variety of restrictions on how +resources are offered to frameworks. Some use-cases for roles include: + +* arranging for all the resources on a particular agent to only be offered to a + particular framework. +* dividing a cluster between two organizations: resources assigned for use by + organization _A_ will only be offered to that frameworks that have registered + using organization _A_'s role. +* ensuring that [persistent volumes](persistent-volume.md) created by one + framework are not offered to frameworks registered with a different role. +* expressing that one group of frameworks should be considered "higher priority" + (and offered more resources) than another group of frameworks. + +## Defining roles + +The set of legal roles is configured statically, when the Mesos master is +started. The `--roles` command-line argument specifies a comma-separated list of +role names. To change the set of roles, the Mesos master must be restarted. + +Note that you should take care to ensure that all Mesos masters are configured +to use the same set of roles. + +## Associating frameworks with roles + +A framework can optionally specify the role it would like to use when it +registers with the master. + +As a developer, you can specify the role your framework will use via the `role` +field of the `FrameworkInfo` message. + +As a user, you can typically specify which role a framework will use when you +start the framework. How to do this depends on the user interface of the +framework you're using; for example, Marathon takes a `--mesos_role` +command-line flag. + +As an administrator, you can use ACLs to specify which framework principals can +register as which roles. For more information, see the +[authorization](authorization.md) documentation. + +## Associating resources with roles + +A resource is assigned to a role using a _reservation_. Resources can either be +reserved _statically_ (when the agent that hosts the resource is started) or +_dynamically_: frameworks and operators can specify that a certain resource +should subsequently be reserved for use by a given role. For more information, +see the [reservation](reservation.md) documentation. + +## The default role + +The role named `*` is special. Resources that are assigned to the `*` role are +considered "unreserved"; similarly, when a framework registers without providing +a role, it is assigned to the `*` role. By default, all the resources at an +agent node are initially assigned to the `*` role (this can be changed via the +`--default_role` command-line flag when starting the agent). + +The `*` role behaves differently from non-default roles. For example, dynamic +reservations can be used to reassign resources from the `*` role to a specific +role, but not from one specific role to another specific role (without first +unreserving the resource, e.g., using the `/unreserve` operator HTTP +endpoint). Similarly, persistent volumes cannot be created on unreserved +resources. + +## Roles and resource allocation + +By default, the Mesos master uses Dominant Resource Fairness (DRF) to allocate +resources. In particular, this implementation of DRF first identifies which +_role_ is furthest below its fair share of the role's dominant resource. Each of +the frameworks in that role are then offered additional resources in turn. + +The resource allocation process can be customized by assigning _weights_ to +roles: a role with a weight of 2 will be allocated twice the fair share of a +role with a weight of 1. Weights are optional, and can be specified via the +`--weights` command-line flag when starting the Mesos master.
