You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mesos.apache.org by mp...@apache.org on 2015/11/25 03:06:57 UTC

[3/5] mesos git commit: Improved docs for dynamic reservation HTTP endpoints.

Improved docs for dynamic reservation HTTP endpoints.

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


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

Branch: refs/heads/master
Commit: d847a36d27f1fd85f650dcb9961fc54ce6d20848
Parents: 48bc61a
Author: Neil Conway <ne...@gmail.com>
Authored: Tue Nov 24 13:33:20 2015 -0800
Committer: Michael Park <mp...@apache.org>
Committed: Tue Nov 24 17:43:48 2015 -0800

----------------------------------------------------------------------
 docs/home.md              |   2 +-
 docs/persistent-volume.md |  47 ++++++++------
 docs/reservation.md       | 141 +++++++++++++++++++++++------------------
 3 files changed, 106 insertions(+), 84 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/mesos/blob/d847a36d/docs/home.md
----------------------------------------------------------------------
diff --git a/docs/home.md b/docs/home.md
index d8f4da6..6ef8a0e 100644
--- a/docs/home.md
+++ b/docs/home.md
@@ -38,7 +38,7 @@ layout: documentation
 * [Networking for Mesos-managed Containers](/documentation/latest/networking-for-mesos-managed-containers/)
 * [Oversubscription](/documentation/latest/oversubscription/) for how to configure Mesos to take advantage of unused resources to launch "best-effort" tasks.
 * [Persistent Volume](/documentation/latest/persistent-volume/) for how to allow tasks to access persistent storage resources.
-* [Reservation](/documentation/latest/reservation/) for how to configure Mesos to allow slaves to reserve resources.
+* [Reservation](/documentation/latest/reservation/) for how operators and frameworks can reserve resources for use by a role.
 
 ## Running Mesos Frameworks
 

http://git-wip-us.apache.org/repos/asf/mesos/blob/d847a36d/docs/persistent-volume.md
----------------------------------------------------------------------
diff --git a/docs/persistent-volume.md b/docs/persistent-volume.md
index 0951ccb..0c9e0e9 100644
--- a/docs/persistent-volume.md
+++ b/docs/persistent-volume.md
@@ -17,10 +17,10 @@ that is mounted at a well-known location outside the task's sandbox).
 
 Persistent volumes can only be created from __reserved__ disk resources, whether
 it be statically reserved or dynamically reserved. A dynamically reserved
-persistent volume also cannot be unreserved without having explicitly destroyed
-the volume. These rules exist to limit the accidental mistakes such as:
-a persistent volume containing sensitive data being offered to other frameworks
-in the cluster.
+persistent volume also cannot be unreserved without first explicitly destroying
+the volume. These rules exist to limit accidental mistakes, such as a persistent
+volume containing sensitive data being offered to other frameworks in the
+cluster.
 
 Please refer to the [Reservation](reservation.md) documentation for details
 regarding reservation mechanisms available in Mesos.
@@ -39,11 +39,12 @@ specified via the existing ACL mechanism. (___Coming Soon___)
 In the following sections, we will walk through examples of each of the
 interfaces described above.
 
+### Framework Scheduler API
 
-## `Offer::Operation::Create`
+#### `Offer::Operation::Create`
 
-A framework is able to create volumes through the resource offer cycle.
-Suppose we receive a resource offer with 2048 MB of dynamically reserved disk.
+A framework can create volumes through the resource offer cycle.  Suppose we
+receive a resource offer with 2048 MB of dynamically reserved disk.
 
 ```
 {
@@ -66,11 +67,11 @@ Suppose we receive a resource offer with 2048 MB of dynamically reserved disk.
 ```
 
 We can create a persistent volume from the 2048 MB of disk resources by sending
-the following `Offer::Operation` message via the `acceptOffers` API.
-`Offer::Operation::Create` has a `volumes` field which we specify with the
-persistent volume information. We need to specify the following:
+an `Offer::Operation` message via the `acceptOffers` API.
+`Offer::Operation::Create` has a `volumes` field which specifies the persistent
+volume information. We need to specify the following:
 
-1. ID of the persistent volume which needs to be unique per role on each slave.
+1. The ID for the persistent volume; this must be unique per role on each slave.
 1. The non-nested relative path within the container to mount the volume.
 1. The permissions for the volume. Currently, `"RW"` is the only possible value.
 
@@ -102,7 +103,8 @@ persistent volume information. We need to specify the following:
 }
 ```
 
-The subsequent resource offer will __contain__ the following persistent volume:
+If this succeeds, a subsequent resource offer will contain the following
+persistent volume:
 
 ```
 {
@@ -134,12 +136,12 @@ The subsequent resource offer will __contain__ the following persistent volume:
 ```
 
 
-## `Offer::Operation::Destroy`
+#### `Offer::Operation::Destroy`
 
-A framework is able to destroy persistent volumes through the resource offer
-cycle. In [Offer::Operation::Create](#offeroperationcreate), we created a
-persistent volume from 2048 MB of disk resources. Mesos will not garbage-collect
-this volume until we explicitly destroy it. Suppose we would like to destroy the
+A framework can destroy persistent volumes through the resource offer cycle. In
+[Offer::Operation::Create](#offeroperationcreate), we created a persistent
+volume from 2048 MB of disk resources. Mesos will not garbage-collect this
+volume until we explicitly destroy it. Suppose we would like to destroy the
 volume we created. First, we receive a resource offer (copy/pasted from above):
 
 ```
@@ -173,7 +175,7 @@ volume we created. First, we receive a resource offer (copy/pasted from above):
 
 We destroy the persistent volume by sending the `Offer::Operation` message via
 the `acceptOffers` API. `Offer::Operation::Destroy` has a `volumes` field which
-we specify the persistent volumes to be destroyed.
+specifies the persistent volumes to be destroyed.
 
 ```
 {
@@ -203,9 +205,9 @@ we specify the persistent volumes to be destroyed.
 }
 ```
 
-The persistent volume will be destroyed, but the disk resources will still be
-reserved. As such, the subsequent resource offer will __contain__ the following
-reserved disk resources:
+If this request succeeds, the persistent volume will be destroyed but the disk
+resources will still be reserved. As such, a subsequent resource offer will
+contain the following reserved disk resources:
 
 ```
 {
@@ -227,6 +229,9 @@ reserved disk resources:
 }
 ```
 
+Those reserved resources can then be used as normal: e.g., they can be used to
+create another persistent volume or can be unreserved.
+
 Note that in 0.23, even after you destroy the persistent volume, its content
 will still be on the disk. The garbage collection for persistent volumes is
 coming soon: [MESOS-2048](https://issues.apache.org/jira/browse/MESOS-2408).

http://git-wip-us.apache.org/repos/asf/mesos/blob/d847a36d/docs/reservation.md
----------------------------------------------------------------------
diff --git a/docs/reservation.md b/docs/reservation.md
index 81f21c3..e297921 100644
--- a/docs/reservation.md
+++ b/docs/reservation.md
@@ -53,16 +53,25 @@ specified via the existing ACL mechanism. (_Coming Soon_)
   available for __frameworks__ to send back via the `acceptOffers` API as a
   response to a resource offer.
 * `/reserve` and `/unreserve` HTTP endpoints are available for __operators__
-  to manage dynamic reservations through the master. (_Coming Soon_).
+  to manage dynamic reservations through the master.
 
 In the following sections, we will walk through examples of each of the
 interfaces described above.
 
+Note that if two dynamic reservations are made for resources at a single slave,
+the reservations will be combined by adding together the resources reserved by
+each request. Similarly, "partial" unreserve operations are allowed: an
+unreserve operation can release only some of the resources at a slave that have
+been reserved for a given role. In this case, the unreserved resources will be
+subtracted from the previous reservation, and any remaining resources will still
+be reserved.
 
-### `Offer::Operation::Reserve`
+### Framework Scheduler API
 
-A framework is able to reserve resources through the resource offer cycle.
-Suppose we receive a resource offer with 12 CPUs and 6144 MB of RAM unreserved.
+#### `Offer::Operation::Reserve`
+
+A framework can reserve resources through the resource offer cycle.  Suppose we
+receive a resource offer with 12 CPUs and 6144 MB of RAM unreserved.
 
         {
           "id": <offer_id>,
@@ -116,7 +125,8 @@ the `role` and `principal` fields with the framework's role and principal.
           }
         }
 
-The subsequent resource offer will __contain__ the following reserved resources:
+If the reservation is successful, a subsequent resource offer will contain the
+following reserved resources:
 
         {
           "id": <offer_id>,
@@ -146,13 +156,14 @@ The subsequent resource offer will __contain__ the following reserved resources:
         }
 
 
-### `Offer::Operation::Unreserve`
+#### `Offer::Operation::Unreserve`
 
-A framework is able to unreserve resources through the resource offer cycle.
+A framework can unreserve resources through the resource offer cycle.
 In [Offer::Operation::Reserve](#offeroperationreserve), we reserved 8 CPUs
-and 4096 MB of RAM for our `role`. The master will continue to offer these
-resources to our `role`. Suppose we would like to unreserve these resources.
-First, we receive a resource offer (copy/pasted from above):
+and 4096 MB of RAM on a particular slave for our `role`. The master will
+continue to only offer these resources to our `role`. Suppose we would like to
+unreserve these resources. First, we receive a resource offer (copy/pasted
+from above):
 
         {
           "id": <offer_id>,
@@ -181,9 +192,9 @@ First, we receive a resource offer (copy/pasted from above):
           ]
         }
 
-We unreserve the 8 CPUs and 4096 MB of RAM by sending the following
+We can unreserve the 8 CPUs and 4096 MB of RAM by sending the following
 `Offer::Operation` message. `Offer::Operation::Unreserve` has a `resources` field
-which we specify with the resources to be unreserved.
+which we can use to specify the resources to be unreserved.
 
         {
           "type": Offer::Operation::UNRESERVE,
@@ -213,49 +224,55 @@ which we specify with the resources to be unreserved.
 
 The unreserved resources may now be offered to other frameworks.
 
+### Operator HTTP Endpoints
 
-### `/reserve` (since 0.25.0)
+As described above, dynamic reservations can be made by a framework scheduler,
+typically in response to a resource offer. However, dynamic reservations can
+also be created and deleted by sending HTTP requests to the `/reserve` and
+`/unreserve` endpoints, respectively. This capability is intended for use by
+operators and administrative tools.
 
+#### `/reserve` (since 0.25.0)
 
-Suppose we want to reserve 8 CPUs and 4096 MB of RAM for the `ads` role on
-a slave with id=`<slave_id>`. We send an HTTP POST request to the `/reserve`
-HTTP endpoint like so:
+Suppose we want to reserve 8 CPUs and 4096 MB of RAM for the `ads` role on a
+slave with id=`<slave_id>` (note that it is up to the user to find the ID of the
+slave that hosts the desired resources; the request will fail if sufficient
+unreserved resources cannot be found on the slave). We send an HTTP POST request
+to the `/reserve` HTTP endpoint like so:
 
         $ curl -i \
           -u <operator_principal>:<password> \
           -d slaveId=<slave_id> \
-          -d resources='[ \
-            { \
-              "name": "cpus", \
-              "type": "SCALAR", \
-              "scalar": { "value": 8 }, \
-              "role": "ads", \
-              "reservation": { \
-                "principal": <operator_principal> \
-              } \
-            }, \
-            { \
-              "name": "mem", \
-              "type": "SCALAR", \
-              "scalar": { "value": 4096 }, \
-              "role": "ads", \
-              "reservation": { \
-                "principal": <operator_principal> \
-              } \
-            } \
+          -d resources='[
+            {
+              "name": "cpus",
+              "type": "SCALAR",
+              "scalar": { "value": 8 },
+              "role": "ads",
+              "reservation": {
+                "principal": <operator_principal>
+              }
+            },
+            {
+              "name": "mem",
+              "type": "SCALAR",
+              "scalar": { "value": 4096 },
+              "role": "ads",
+              "reservation": {
+                "principal": <operator_principal>
+              }
+            }
           ]' \
           -X POST http://<ip>:<port>/master/reserve
 
 The user receives one of the following HTTP responses:
 
-* `200 OK`: Success
-* `400 BadRequest`: Invalid arguments (e.g. missing parameters).
+* `200 OK`: Success (the requested resources have been reserved).
+* `400 BadRequest`: Invalid arguments (e.g., missing parameters).
 * `401 Unauthorized`: Unauthorized request.
 * `409 Conflict`: Insufficient resources to satisfy the reserve operation.
 
-
-### `/unreserve` (since 0.25.0)
-
+#### `/unreserve` (since 0.25.0)
 
 Suppose we want to unreserve the resources that we dynamically reserved above.
 We can send an HTTP POST request to the `/unreserve` HTTP endpoint like so:
@@ -263,31 +280,31 @@ We can send an HTTP POST request to the `/unreserve` HTTP endpoint like so:
         $ curl -i \
           -u <operator_principal>:<password> \
           -d slaveId=<slave_id> \
-          -d resources='[ \
-            { \
-              "name": "cpus", \
-              "type": "SCALAR", \
-              "scalar": { "value": 8 }, \
-              "role": "ads", \
-              "reservation": { \
-                "principal": <operator_principal> \
-              } \
-            }, \
-            { \
-              "name": "mem", \
-              "type": "SCALAR", \
-              "scalar": { "value": 4096 }, \
-              "role": "ads", \
-              "reservation": { \
-                "principal": <operator_principal> \
-              } \
-            } \
+          -d resources='[
+            {
+              "name": "cpus",
+              "type": "SCALAR",
+              "scalar": { "value": 8 },
+              "role": "ads",
+              "reservation": {
+                "principal": <operator_principal>
+              }
+            },
+            {
+              "name": "mem",
+              "type": "SCALAR",
+              "scalar": { "value": 4096 },
+              "role": "ads",
+              "reservation": {
+                "principal": <operator_principal>
+              }
+            }
           ]' \
           -X POST http://<ip>:<port>/master/unreserve
 
 The user receives one of the following HTTP responses:
 
-* `200 OK`: Success
-* `400 BadRequest`: Invalid arguments (e.g. missing parameters).
+* `200 OK`: Success (the requested resources have been unreserved).
+* `400 BadRequest`: Invalid arguments (e.g., missing parameters).
 * `401 Unauthorized`: Unauthorized request.
-* `409 Conflict`: Insufficient resources to satisfy unreserve operation.
+* `409 Conflict`: Insufficient resources to satisfy the unreserve operation.