You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mesos.apache.org by ji...@apache.org on 2016/02/12 21:55:13 UTC
[2/2] mesos git commit: Improved docs for volume/reservation HTTP
endpoints.
Improved docs for volume/reservation HTTP endpoints.
Review: https://reviews.apache.org/r/43118/
Project: http://git-wip-us.apache.org/repos/asf/mesos/repo
Commit: http://git-wip-us.apache.org/repos/asf/mesos/commit/df503d3f
Tree: http://git-wip-us.apache.org/repos/asf/mesos/tree/df503d3f
Diff: http://git-wip-us.apache.org/repos/asf/mesos/diff/df503d3f
Branch: refs/heads/master
Commit: df503d3f600b390a2511f5e95a1db10214be4425
Parents: c3c2c22
Author: Neil Conway <ne...@gmail.com>
Authored: Fri Feb 12 12:50:54 2016 -0800
Committer: Jie Yu <yu...@gmail.com>
Committed: Fri Feb 12 12:50:54 2016 -0800
----------------------------------------------------------------------
docs/endpoints/master/create-volumes.md | 5 +++-
docs/endpoints/master/destroy-volumes.md | 5 +++-
docs/endpoints/master/reserve.md | 5 +++-
docs/endpoints/master/unreserve.md | 5 +++-
docs/persistent-volume.md | 35 ++++++++++++++++++-----
docs/reservation.md | 40 +++++++++++++++++++++------
src/master/http.cpp | 20 +++++++++++---
7 files changed, 92 insertions(+), 23 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/mesos/blob/df503d3f/docs/endpoints/master/create-volumes.md
----------------------------------------------------------------------
diff --git a/docs/endpoints/master/create-volumes.md b/docs/endpoints/master/create-volumes.md
index f167452..1e8fd20 100644
--- a/docs/endpoints/master/create-volumes.md
+++ b/docs/endpoints/master/create-volumes.md
@@ -7,6 +7,9 @@
Create persistent volumes on reserved resources.
### DESCRIPTION ###
-Returns 200 OK if volume creation was successful.
+Returns 200 OK if the request was accepted. This does not
+imply that the volume was created successfully: volume
+creation is done asynchronously and may fail.
+
Please provide "slaveId" and "volumes" values designating
the volumes to be created.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/mesos/blob/df503d3f/docs/endpoints/master/destroy-volumes.md
----------------------------------------------------------------------
diff --git a/docs/endpoints/master/destroy-volumes.md b/docs/endpoints/master/destroy-volumes.md
index a9a12ad..7209a7c 100644
--- a/docs/endpoints/master/destroy-volumes.md
+++ b/docs/endpoints/master/destroy-volumes.md
@@ -7,6 +7,9 @@
Destroy persistent volumes.
### DESCRIPTION ###
-Returns 200 OK if volume deletion was successful.
+Returns 200 OK if the request was accepted. This does not
+imply that the volume was destroyed successfully: volume
+destruction is done asynchronously and may fail.
+
Please provide "slaveId" and "volumes" values designating
the volumes to be destroyed.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/mesos/blob/df503d3f/docs/endpoints/master/reserve.md
----------------------------------------------------------------------
diff --git a/docs/endpoints/master/reserve.md b/docs/endpoints/master/reserve.md
index 6d4dee4..a71eb8e 100644
--- a/docs/endpoints/master/reserve.md
+++ b/docs/endpoints/master/reserve.md
@@ -7,6 +7,9 @@
Reserve resources dynamically on a specific slave.
### DESCRIPTION ###
-Returns 200 OK if resource reservation was successful.
+Returns 200 OK if the request was accepted. This does not
+imply that the requested resources have been reserved successfully:
+resource reservation is done asynchronously and may fail.
+
Please provide "slaveId" and "resources" values designating
the resources to be reserved.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/mesos/blob/df503d3f/docs/endpoints/master/unreserve.md
----------------------------------------------------------------------
diff --git a/docs/endpoints/master/unreserve.md b/docs/endpoints/master/unreserve.md
index 81c72d3..5de7734 100644
--- a/docs/endpoints/master/unreserve.md
+++ b/docs/endpoints/master/unreserve.md
@@ -7,6 +7,9 @@
Unreserve resources dynamically on a specific slave.
### DESCRIPTION ###
-Returns 200 OK if resource unreservation was successful.
+Returns 200 OK if the request was accepted. This does not
+imply that the requested resources have been unreserved successfully:
+resource unreservation is done asynchronously and may fail.
+
Please provide "slaveId" and "resources" values designating
the resources to be unreserved.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/mesos/blob/df503d3f/docs/persistent-volume.md
----------------------------------------------------------------------
diff --git a/docs/persistent-volume.md b/docs/persistent-volume.md
index 9657c3f..4d7821f 100644
--- a/docs/persistent-volume.md
+++ b/docs/persistent-volume.md
@@ -286,14 +286,24 @@ curl -i \
The user receives one of the following HTTP responses:
-* `200 OK`: Success (the persistent volumes have been created).
+* `200 OK`: Request accepted (see below).
* `400 BadRequest`: Invalid arguments (e.g., missing parameters).
* `401 Unauthorized`: Unauthenticated request.
* `403 Forbidden`: Unauthorized request.
* `409 Conflict`: Insufficient resources to create the volumes.
-Note that a single `/create-volumes` request can create multiple persistent
-volumes, but all of the volumes must be on the same slave.
+A single `/create-volumes` request can create multiple persistent volumes, but
+all of the volumes must be on the same slave.
+
+Note that when `200 OK` is returned by this endpoint, it does __not__ mean that
+the persistent volumes have been created successfully. Instead, this return code
+indicates that the create operation has been validated successfully by the
+master. The request is then forwarded asynchronously to the Mesos slave where
+the reserved resources are located. That asynchronous message may not be
+delivered or creating the volumes at the slave might fail, in which case no
+volumes will be created. To determine if a create operation has succeeded, the
+user can examine the state of the appropriate Mesos slave (e.g., via the slave's
+`/state` HTTP endpoint).
#### `/destroy-volumes`
@@ -328,14 +338,24 @@ curl -i \
The user receives one of the following HTTP responses:
-* `200 OK`: Success (the volumes have been destroyed).
+* `200 OK`: Request accepted (see below).
* `400 BadRequest`: Invalid arguments (e.g., missing parameters).
* `401 Unauthorized`: Unauthenticated request.
* `403 Forbidden`: Unauthorized request.
* `409 Conflict`: Insufficient resources to destroy the volumes.
-Note that a single `/destroy-volumes` request can destroy multiple persistent
-volumes, but all of the volumes must be on the same slave.
+A single `/destroy-volumes` request can destroy multiple persistent volumes, but
+all of the volumes must be on the same slave.
+
+Note that when `200 OK` is returned by this endpoint, it does __not__ mean that
+the persistent volumes have been destroyed successfully. Instead, this return
+code indicates that the destroy operation has been validated successfully by the
+master. The request is then forwarded asynchronously to the Mesos slave where
+the persistent volumes are located. That asynchronous message may not be
+delivered or destroying the volumes at the slave might fail, in which case no
+volumes will be destroyed. To determine if a destroy operation has succeeded,
+the user can examine the state of the appropriate Mesos slave (e.g., via the
+slave's `/state` HTTP endpoint).
### Programming with Persistent Volumes
@@ -355,7 +375,8 @@ volumes:
* When using HTTP endpoints to reserve resources or create persistent volumes,
_some_ failures can be detected by examining the HTTP response code returned
to the client. However, it is still possible for a `200` response code to be
- returned to the client but for the associated operation to fail.
+ returned to the client but for the associated operation to fail---see
+ discussion above.
* When using the scheduler API, detecting that a dynamic reservation has failed
is a little tricky: reservations do not have unique identifiers, and the Mesos
http://git-wip-us.apache.org/repos/asf/mesos/blob/df503d3f/docs/reservation.md
----------------------------------------------------------------------
diff --git a/docs/reservation.md b/docs/reservation.md
index d3ae445..41321d4 100644
--- a/docs/reservation.md
+++ b/docs/reservation.md
@@ -13,7 +13,7 @@ and authorized __frameworks__ to dynamically reserve resources in the cluster.
In both types of reservations, resources are reserved for a [__role__](roles.md).
-## Static Reservation (since 0.14.0)
+## Static Reservation
An operator can configure a slave with resources reserved for a role.
The reserved resources are specified via the `--resources` flag.
@@ -37,13 +37,13 @@ __NOTE:__ This feature is supported for backwards compatibility.
reservations dynamically via the master HTTP endpoints.
-## Dynamic Reservation (since 0.23.0)
+## Dynamic Reservation
As mentioned in [Static Reservation](#static-reservation-since-0140), specifying
the reserved resources via the `--resources` flag makes the reservation static.
That is, statically reserved resources cannot be reserved for another role nor
-be unreserved. Dynamic Reservation enables operators and authorized frameworks
-to reserve and unreserve resources post slave-startup.
+be unreserved. Dynamic reservation enables operators and authorized frameworks
+to reserve and unreserve resources after slave-startup.
We require a `principal` from the operator or framework in order to
authenticate/authorize the operations. Permissions are specified via the
@@ -289,12 +289,21 @@ HTTP POST request to the `/reserve` HTTP endpoint like so:
The user receives one of the following HTTP responses:
-* `200 OK`: Success (the requested resources have been reserved).
+* `200 OK`: Request accepted (see below).
* `400 BadRequest`: Invalid arguments (e.g., missing parameters).
* `401 Unauthorized`: Unauthenticated request.
* `403 Forbidden`: Unauthorized request.
* `409 Conflict`: Insufficient resources to satisfy the reserve operation.
+Note that when `200 OK` is returned by this endpoint, it does __not__ mean that
+the requested resources have been reserved. Instead, this return code indicates
+that the reservation request has been validated successfully by the master. The
+reservation request is then forwarded asynchronously to the Mesos slave where
+the resources are located. That asynchronous message may not be delivered, in
+which case no resources will be reserved. To determine if a reserve operation
+has succeeded, the user can examine the state of the appropriate Mesos slave
+(e.g., via the slave's `/state` HTTP endpoint).
+
#### `/unreserve` (since 0.25.0)
Suppose we want to unreserve the resources that we dynamically reserved above.
@@ -310,7 +319,7 @@ We can send an HTTP POST request to the `/unreserve` HTTP endpoint like so:
"scalar": { "value": 8 },
"role": "ads",
"reservation": {
- "principal": <operator_principal>
+ "principal": <reserver_principal>
}
},
{
@@ -319,16 +328,31 @@ We can send an HTTP POST request to the `/unreserve` HTTP endpoint like so:
"scalar": { "value": 4096 },
"role": "ads",
"reservation": {
- "principal": <operator_principal>
+ "principal": <reserver_principal>
}
}
]' \
-X POST http://<ip>:<port>/master/unreserve
+Note that `reserver_principal` is the principal that was used to make the
+reservation, while `operator_principal` is the principal that is attempting to
+perform the unreserve operation---in some cases, these principals might be the
+same. The `operator_principal` must be [authorized](authorization.md) to
+unreserve reservations made by `reserver_principal`.
+
The user receives one of the following HTTP responses:
-* `200 OK`: Success (the requested resources have been unreserved).
+* `200 OK`: Request accepted (see below).
* `400 BadRequest`: Invalid arguments (e.g., missing parameters).
* `401 Unauthorized`: Unauthenticated request.
* `403 Forbidden`: Unauthorized request.
* `409 Conflict`: Insufficient resources to satisfy the unreserve operation.
+
+Note that when `200 OK` is returned by this endpoint, it does __not__ mean that
+the requested resources have been unreserved. Instead, this return code
+indicates that the unreserve request has been validated successfully by the
+master. The request is then forwarded asynchronously to the Mesos slave where
+the resources are located. That asynchronous message may not be delivered, in
+which case no resources will be unreserved. To determine if an unreserve
+operation has succeeded, the user can examine the state of the appropriate Mesos
+slave (e.g., via the slave's `/state` HTTP endpoint).
http://git-wip-us.apache.org/repos/asf/mesos/blob/df503d3f/src/master/http.cpp
----------------------------------------------------------------------
diff --git a/src/master/http.cpp b/src/master/http.cpp
index 3d7a624..f92212b 100644
--- a/src/master/http.cpp
+++ b/src/master/http.cpp
@@ -699,7 +699,10 @@ string Master::Http::CREATE_VOLUMES_HELP()
TLDR(
"Create persistent volumes on reserved resources."),
DESCRIPTION(
- "Returns 200 OK if volume creation was successful.",
+ "Returns 200 OK if the request was accepted. This does not",
+ "imply that the volume was created successfully: volume",
+ "creation is done asynchronously and may fail.",
+ "",
"Please provide \"slaveId\" and \"volumes\" values designating",
"the volumes to be created."));
}
@@ -803,7 +806,10 @@ string Master::Http::DESTROY_VOLUMES_HELP()
TLDR(
"Destroy persistent volumes."),
DESCRIPTION(
- "Returns 200 OK if volume deletion was successful.",
+ "Returns 200 OK if the request was accepted. This does not",
+ "imply that the volume was destroyed successfully: volume",
+ "destruction is done asynchronously and may fail.",
+ "",
"Please provide \"slaveId\" and \"volumes\" values designating",
"the volumes to be destroyed."));
}
@@ -1132,7 +1138,10 @@ string Master::Http::RESERVE_HELP()
TLDR(
"Reserve resources dynamically on a specific slave."),
DESCRIPTION(
- "Returns 200 OK if resource reservation was successful.",
+ "Returns 200 OK if the request was accepted. This does not",
+ "imply that the requested resources have been reserved successfully:",
+ "resource reservation is done asynchronously and may fail.",
+ "",
"Please provide \"slaveId\" and \"resources\" values designating",
"the resources to be reserved."));
}
@@ -2400,7 +2409,10 @@ string Master::Http::UNRESERVE_HELP()
TLDR(
"Unreserve resources dynamically on a specific slave."),
DESCRIPTION(
- "Returns 200 OK if resource unreservation was successful.",
+ "Returns 200 OK if the request was accepted. This does not",
+ "imply that the requested resources have been unreserved successfully:",
+ "resource unreservation is done asynchronously and may fail.",
+ "",
"Please provide \"slaveId\" and \"resources\" values designating",
"the resources to be unreserved."));
}