You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mesos.apache.org by al...@apache.org on 2016/11/24 11:34:41 UTC
[2/3] mesos git commit: Fixed style issues in quota.md.
Fixed style issues in quota.md.
Correct caption hierarchy, update headings to conform to
title case, and ensure two blank lines between sections.
Review: https://reviews.apache.org/r/53613/
Project: http://git-wip-us.apache.org/repos/asf/mesos/repo
Commit: http://git-wip-us.apache.org/repos/asf/mesos/commit/770527dd
Tree: http://git-wip-us.apache.org/repos/asf/mesos/tree/770527dd
Diff: http://git-wip-us.apache.org/repos/asf/mesos/diff/770527dd
Branch: refs/heads/master
Commit: 770527ddd241712f3f59def8c73696779c7e34da
Parents: 5832726
Author: Alexander Rukletsov <ru...@gmail.com>
Authored: Thu Nov 24 12:32:27 2016 +0100
Committer: Alexander Rukletsov <al...@apache.org>
Committed: Thu Nov 24 12:32:27 2016 +0100
----------------------------------------------------------------------
docs/quota.md | 135 ++++++++++++++++++++++++++++++-----------------------
1 file changed, 76 insertions(+), 59 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/mesos/blob/770527dd/docs/quota.md
----------------------------------------------------------------------
diff --git a/docs/quota.md b/docs/quota.md
index 5a2fea1..0abb9eb 100644
--- a/docs/quota.md
+++ b/docs/quota.md
@@ -36,7 +36,8 @@ example, if a role has been assigned a quota of 4 CPUs and also has 2 reserved
resources at a particular agent, the role has a minimum guarantee of 4 CPUs, not
6.
-# Terminology
+
+## Terminology
For the purpose of this document, an \u201cOperator\u201d is a person, tool, or script
that manages the Mesos cluster.
@@ -50,12 +51,15 @@ In computer science, a \u201cquota\u201d usually refers to one of the following:
In Mesos, a quota is a **guaranteed** resource allocation that a role may rely
on; in other words, a minimum share a role is entitled to receive.
-# Motivation and Limitations
+
+## Motivation and Limitations
Consider the following scenarios in a Mesos cluster to better understand which
use-cases are supported by quota, and which are not.
-## Scenario 1: Greedy Framework
+
+### Scenario 1: Greedy Framework
+
There are two frameworks in a cluster, each running in a separate role with
equal weights: framework fA in role rA and framework fB in role rB. There is a
single resource available in the cluster: 100 CPUs. fA consumes 10 CPUs and is
@@ -64,7 +68,9 @@ hogging the remaining 90 CPUs. Without quota, though fA\u2019s fair share is 50 CPU
it will not be able to make use of additional the 40 CPUs until some of fB\u2019s
tasks terminate.
-## Scenario 2: Resources for a new Framework
+
+### Scenario 2: Resources for a new Framework
+
A greedy framework fB in role rB is currently the only framework in the cluster
and it uses all available resources---100 CPUs. If a new framework fA in role rA
joins the cluster, it will not receive its fair share of the cluster resources
@@ -75,7 +81,8 @@ would be set after fB has started using all resources. Instead Scenario 2
requires either always keeping a pool of resources which are not offered or
introducing preemption for running tasks.
-# Operator HTTP Endpoint
+
+## Operator HTTP Endpoint
The master [/quota](endpoints/master/quota.md) HTTP endpoint enables operators
to configure quotas. The endpoint currently offers a REST-like interface and
@@ -89,11 +96,12 @@ Currently it is not possible to update previously configured quotas. This means
in order to update a quota for a given role, the operator has to remove the
existing quota and then set a new one.
-The endpoint can optionally use authentication and authorization. See the
+The endpoint can optionally use authentication and authorization. See
[authentication guide](authentication.md) for details.
+
<a name="setRequest"></a>
-## Set
+### Set
The operator can set a new quota by sending an HTTP POST request to the `/quota`
endpoint.
@@ -101,26 +109,26 @@ endpoint.
An example request to the quota endpoint could look like this (using the JSON
file below):
- $ curl -d @quota.json -X POST http://<master-ip>:<port>/quota
+ $ curl -d @quota.json -X POST http://<master-ip>:<port>/quota
For example to set a quota of 12 CPUs and 6144 MB of RAM for `role1` the operator
can use the following `quota.json`:
- {
- "role": "role1",
- "guarantee": [
- {
- "name": "cpus",
- "type": "SCALAR",
- "scalar": { "value": 12 }
- },
- {
- "name": "mem",
- "type": "SCALAR",
- "scalar": { "value": 6144 }
- }
- ]
- }
+ {
+ "role": "role1",
+ "guarantee": [
+ {
+ "name": "cpus",
+ "type": "SCALAR",
+ "scalar": { "value": 12 }
+ },
+ {
+ "name": "mem",
+ "type": "SCALAR",
+ "scalar": { "value": 6144 }
+ }
+ ]
+ }
A set request is only valid for roles for which no quota is currently set.
However if the master is configured without an explicit
@@ -129,11 +137,11 @@ However if the master is configured without an explicit
In order to bypass the [capacity heuristic](#capacityHeuristic) check the
operator should set an optional `force` field:
- {
- "force": true,
- "role": "role1",
- ...
- }
+ {
+ "force": true,
+ "role": "role1",
+ ...
+ }
The operator will receive one of the following HTTP response codes:
@@ -145,14 +153,15 @@ The operator will receive one of the following HTTP response codes:
* `409 Conflict`: The capacity heuristic check failed due to insufficient
resources.
+
<a name="removeRequest"></a>
-## Remove
+### Remove
The operator can remove a previously set quota by sending an HTTP DELETE request
to the `/quota/<role>` endpoint. For example the following command removes
a previously set quota for `role1`:
- $ curl -X DELETE http://<master-ip>:<port>/quota/role1
+ $ curl -X DELETE http://<master-ip>:<port>/quota/role1
The operator will receive one of the following HTTP response codes:
@@ -162,39 +171,40 @@ The operator will receive one of the following HTTP response codes:
* `401 Unauthorized`: Unauthenticated request.
* `403 Forbidden`: Unauthorized request.
+
<a name="statusRequest"></a>
-## Status
+### Status
The operator can query the configured quotas by sending a HTTP GET request
to the `/quota` endpoint.
- $ curl -X GET http://<master-ip>:<port>/quota
+ $ curl -X GET http://<master-ip>:<port>/quota
The response message body includes a JSON representation of the current quota
status for role(s) which principal is authorized to query quota status (if
authorization is enabled). For example:
- {
- "infos": [
- {
- "role": "role1",
- "guarantee": [
- {
- "name": "cpus",
- "role": "*",
- "type": "SCALAR",
- "scalar": { "value": 12 }
- },
- {
- "name": "mem",
- "role": "*",
- "type": "SCALAR",
- "scalar": { "value": 6144 }
- }
- ]
- }
- ]
- }
+ {
+ "infos": [
+ {
+ "role": "role1",
+ "guarantee": [
+ {
+ "name": "cpus",
+ "role": "*",
+ "type": "SCALAR",
+ "scalar": { "value": 12 }
+ },
+ {
+ "name": "mem",
+ "role": "*",
+ "type": "SCALAR",
+ "scalar": { "value": 6144 }
+ }
+ ]
+ }
+ ]
+ }
The operator will receive one of the following HTTP response codes:
@@ -204,7 +214,8 @@ The operator will receive one of the following HTTP response codes:
**NOTE:** If the principal is not authorized to query quota status for certain
role(s), the result will not include corresponding quota information.
-# How does it work?
+
+## How Does It Work?
There are several stages in the lifetime of a quota issued by operator. First
the [quota set request is handled by the master](#requestProcessing), after that
@@ -222,6 +233,7 @@ because resources will be laid away and not offered to other frameworks.
Also note, that quota is only applicable for scalar resources (e.g., it is not
possible to set quota for port resources).
+
<a name="requestProcessing"></a>
## Quota Request Processing
@@ -246,6 +258,7 @@ The quota remove request processing is simpler and triggers the following steps:
3. [Authorize](authentication.md) the HTTP request if authorization is enabled.
4. Reliably remove quota.
+
<a name="capacityHeuristic"></a>
### Capacity Heuristic Check
@@ -261,7 +274,7 @@ given the total cluster capacity. This heuristic tests whether the total quota,
including the new request, does not exceed the sum of total
non-statically-reserved cluster resources, i.e. the following inequality holds:
- total resources - statically reserved >= total quota + quota request
+ total resources - statically reserved >= total quota + quota request
Please be advised that even if there are enough resources at the moment of
this check, agents may terminate at any time, rendering the cluster incapable
@@ -272,6 +285,7 @@ flag can be useful when the operator would like to configure a quota that
exceeds the current cluster capacity, but they know that additional cluster
resources will be added shortly.
+
<a name="rescindOffers"></a>
### Rescinding Outstanding Offers
@@ -290,6 +304,7 @@ outstanding offers with the following rules:
role for which quota is being set. This enables (but does not guarantee, due
to fair sharing) each framework in the role to receive an offer.
+
<a name="allocatorEnforcement"></a>
## Enforcement by wDRF Allocator
@@ -314,6 +329,7 @@ algorithm determines framework priority inside this role.
The default wDRF allocator considers only non-revocable resources as applicable
towards quota.
+
<a name="failover"></a>
## Failover
@@ -331,12 +347,13 @@ suspension---ends when either:
the failover), or
* a timeout expires (by default 10 minutes).
-# Current Limitations
+
+## Current Limitations
* The quota set request does not allow specifying the granularity of the
- requested resources (e.g. 10 CPUs on a single node).
-* The quota set request does not allow to specify constraints (e.g. 2*5 cpus on
- disjoint nodes for an HA like setup).
+ requested resources (e.g., 10 CPUs on a single node).
+* The quota set request does not allow to specify constraints (e.g., 2*5 cpus
+ on disjoint nodes for an HA like setup).
* Quota is not allowed for the default role \u2018*\u2019 (see
[MESOS-3938](https://issues.apache.org/jira/browse/MESOS-3938)).
* Currently it is not possible to update previously configured quotas. See