[3/4] mesos git commit: Added doc for weights.

[me...@apache.org]

Added doc for weights.

Review: https://reviews.apache.org/r/42719/


Project: http://git-wip-us.apache.org/repos/asf/mesos/repo
Commit: http://git-wip-us.apache.org/repos/asf/mesos/commit/51977740
Tree: http://git-wip-us.apache.org/repos/asf/mesos/tree/51977740
Diff: http://git-wip-us.apache.org/repos/asf/mesos/diff/51977740

Branch: refs/heads/master
Commit: 51977740150b50dc514dcb40d69d7881534c073b
Parents: 6817219
Author: Yongqiao Wang <yq...@cn.ibm.com>
Authored: Tue Mar 8 15:19:02 2016 -0800
Committer: Adam B <ad...@mesosphere.io>
Committed: Tue Mar 8 23:18:41 2016 -0800

----------------------------------------------------------------------
 docs/home.md    |  1 +
 docs/weights.md | 60 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 61 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/mesos/blob/51977740/docs/home.md
----------------------------------------------------------------------
diff --git a/docs/home.md b/docs/home.md
index 4327d46..fd7794f 100644
--- a/docs/home.md
+++ b/docs/home.md
@@ -22,6 +22,7 @@ layout: documentation
   * [Docker Containerizer](docker-containerizer.md) for launching a Docker image as a Task, or as an Executor.
   * [External Containerizer](external-containerizer.md) for custom containerization implementations (deprecated).
 * [Roles](roles.md)
+* [Weights](weights.md)
 * [Framework Authentication](authentication.md)
 * [Framework Authorization](authorization.md)
 * [Framework Rate Limiting](framework-rate-limiting.md)

http://git-wip-us.apache.org/repos/asf/mesos/blob/51977740/docs/weights.md
----------------------------------------------------------------------
diff --git a/docs/weights.md b/docs/weights.md
new file mode 100644
index 0000000..dec2ddd
--- /dev/null
+++ b/docs/weights.md
@@ -0,0 +1,60 @@
+---
+layout: documentation
+---
+
+# Weights
+
+In Mesos, __weights__ are used to indicate forms of priority
+among [roles](roles.md).
+
+In Mesos 0.28 and earlier, weights can only be configured by specifying
+the `--weights` command-line flag when starting the Mesos master. If a
+role does not have a weight specified in the `--weights` flag, then the default
+value (1.0) will be used. Weights cannot be changed without updating the flag
+and restarting all Mesos masters.
+
+In Mesos 0.29, a new endpoint `/weights` is introduced so an operator can
+update weights at runtime. The `--weights` command-line flag is deprecated.
+
+# Operator HTTP Endpoint
+
+The master `/weights` HTTP endpoint enables operators to update weights. The
+endpoint currently offers a REST-like interface and only supports an update
+request with PUT.
+
+The endpoint can optionally use authentication and authorization. See the
+[authentication guide](authentication.md) for details.
+
+An example request to the `/weights` endpoint could look like this (using the
+JSON definitions below):
+
+    $ curl -d jsonMessageBody -X PUT http://<master-ip>:<port>/weights
+
+For example, to set a weight of `2.0` for `role1` and set a weight of `3.5`
+for `role2`, the operator can use the following `jsonMessageBody`:
+
+        [
+          {
+            "weight": 2.0,
+            "role": "role1"
+          },
+          {
+            "weight": 3.5,
+            "role": "role2"
+          }
+        ]
+
+An update request is always valid when master is configured with implicit
+roles. However if the master is configured with an explicit [role whitelist](roles.md)
+the request is only valid when all specified roles exist in the `whitelist`.
+
+Weights are now persisted in the registry on cluster bootstrap and after any updates.
+Once the weights are persisted in the registry, any Mesos master that subsequently starts
+with `--weights` still specified will warn and use the registry value instead.
+
+The operator will receive one of the following HTTP response codes:
+
+* `200 OK`: Success (the update request was successful).
+* `400 BadRequest`: Invalid arguments (e.g. invalid JSON, non-positive weights).
+* `401 Unauthorized`: Unauthenticated request.
+* `403 Forbidden`: Unauthorized request.