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.