You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mesos.apache.org by gi...@apache.org on 2017/12/08 01:23:12 UTC
mesos-site git commit: Updated the website built from mesos SHA:
02758c4.
Repository: mesos-site
Updated Branches:
refs/heads/asf-site 744934608 -> afed5858f
Updated the website built from mesos SHA: 02758c4.
Project: http://git-wip-us.apache.org/repos/asf/mesos-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/mesos-site/commit/afed5858
Tree: http://git-wip-us.apache.org/repos/asf/mesos-site/tree/afed5858
Diff: http://git-wip-us.apache.org/repos/asf/mesos-site/diff/afed5858
Branch: refs/heads/asf-site
Commit: afed5858fd0efffffac4d7d6f8b0154e8b39482c
Parents: 7449346
Author: jenkins <bu...@apache.org>
Authored: Fri Dec 8 01:23:10 2017 +0000
Committer: jenkins <bu...@apache.org>
Committed: Fri Dec 8 01:23:10 2017 +0000
----------------------------------------------------------------------
.../documentation/latest/reservation/index.html | 327 ++++++++++++++++++-
.../documentation/latest/upgrades/index.html | 8 +
content/documentation/reservation/index.html | 327 ++++++++++++++++++-
content/documentation/upgrades/index.html | 8 +
4 files changed, 640 insertions(+), 30 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/mesos-site/blob/afed5858/content/documentation/latest/reservation/index.html
----------------------------------------------------------------------
diff --git a/content/documentation/latest/reservation/index.html b/content/documentation/latest/reservation/index.html
index e35d49f..23fb32e 100644
--- a/content/documentation/latest/reservation/index.html
+++ b/content/documentation/latest/reservation/index.html
@@ -193,7 +193,7 @@ running task or if a <a href="/documentation/latest/./persistent-volume/">persis
using the reserved resources. In the latter case, the volume should be destroyed
before unreserving the resources.</p>
-<h3>Labeled Reservations</h3>
+<h2>Reservation Labels</h2>
<p>Dynamic reservations can optionally include a list of <em>labels</em>, which are
arbitrary key-value pairs. Labels can be used to associate arbitrary metadata
@@ -203,11 +203,39 @@ given slave. Note that two reservations with different labels will not be
combined together into a single reservation, even if the reservations are at the
same slave and use the same role.</p>
+<h2>Reservation Refinement</h2>
+
+<p>Hierarhical roles such as <code>eng/backend</code> enable the delegation of resources
+down a hierarchy, and reservation refinement is the mechanism with which
+<strong>reservations</strong> are delegated down the hierarchy. For example, a reservation
+(static or dynamic) for <code>eng</code> can be <strong>refined</strong> to <code>eng/backend</code>. When such
+a reservation is unreserved, they are returned to the previous owner. In this
+case it would be returned to <code>eng</code>. Reservation refinements can also “skip”
+levels. For example, <code>eng</code> can be <strong>refined</strong> directly to <code>eng/backend/db</code>.
+Again, unreserving such a reservation is returned to its previous owner <code>eng</code>.</p>
+
+<p><strong>NOTE:</strong> Frameworks need to enable the <code>RESERVATION_REFINEMENT</code> capability
+in order to be offered, and to create refined reservations</p>
+
+<h2>Listing Reservations</h2>
+
+<p>Information about the reserved resources at each slave in the cluster can be
+found by querying the <a href="/documentation/latest/./endpoints/master/slaves/">/slaves</a> master endpoint
+(under the <code>reserved_resources_full</code> key).</p>
+
+<p>The same information can also be found in the <a href="/documentation/latest/./endpoints/slave/state/">/state</a>
+endpoint on the agent (under the <code>reserved_resources_full</code> key). The agent
+endpoint is useful to confirm if a reservation has been propagated to the
+agent (which can fail in the event of network partition or master/agent
+restarts).</p>
+
+<h2>Examples</h2>
+
<h3>Framework Scheduler API</h3>
<p><a name="offer-operation-reserve"></a></p>
-<h4><code>Offer::Operation::Reserve</code></h4>
+<h4><code>Offer::Operation::Reserve</code> (<strong>without</strong> <code>RESERVATION_REFINEMENT</code>)</h4>
<p>A framework can reserve resources through the resource offer cycle. The
reservation role must match the offer’s allocation role. Suppose we
@@ -315,7 +343,7 @@ following reserved resources:</p>
}
</code></pre>
-<h4><code>Offer::Operation::Unreserve</code></h4>
+<h4><code>Offer::Operation::Unreserve</code> (<strong>without</strong> <code>RESERVATION_REFINEMENT</code>)</h4>
<p>A framework can unreserve resources through the resource offer cycle.
In <a href="#offer-operation-reserve">Offer::Operation::Reserve</a>, we reserved 8 CPUs
@@ -390,6 +418,287 @@ which we can use to specify the resources to be unreserved.</p>
<p>The unreserved resources may now be offered to other frameworks.</p>
+<p><a name="offer-operation-reserve-reservation-refinement"></a></p>
+
+<h4><code>Offer::Operation::Reserve</code> (<strong>with</strong> <code>RESERVATION_REFNEMENT</code>)</h4>
+
+<p>A framework that wants to create a refined reservation needs to enable
+the <code>RESERVATION_REFINEMENT</code> capability. Doing so will allow the framework
+to use the <code>reservations</code> field in the <code>Resource</code> message in order to
+<strong>push</strong> a refined reservation.</p>
+
+<p>Since reserved resources are offered to any of the child roles under the role
+for which they are reserved for, they can get <strong>allocated</strong> to say,
+<code>"engineering/backend"</code> while being <strong>reserved</strong> for <code>"engineering"</code>.
+It can then be refined to be <strong>reserved</strong> for <code>"engineering/backend"</code>.</p>
+
+<p>Note that the refined reservation role must match the offer’s allocation role.</p>
+
+<p>Suppose we receive a resource offer with 12 CPUs and 6144 MB of RAM unreserved,
+allocated to role <code>"engineering/backend"</code>, reserved to <code>"engineering"</code>.</p>
+
+<pre><code> {
+ "allocation_info": { "role": "engineering/backend" },
+ "id": <offer_id>,
+ "framework_id": <framework_id>,
+ "slave_id": <slave_id>,
+ "hostname": <hostname>,
+ "resources": [
+ {
+ "allocation_info": { "role": "engineering/backend" },
+ "name": "cpus",
+ "type": "SCALAR",
+ "scalar": { "value": 12 },
+ "reservations": [
+ {
+ type: DYNAMIC,
+ role: "engineering",
+ principal: <principal>,
+ }
+ ]
+ },
+ {
+ "allocation_info": { "role": "engineering/backend" },
+ "name": "mem",
+ "type": "SCALAR",
+ "scalar": { "value": 6144 },
+ "reservations": [
+ {
+ type: DYNAMIC,
+ role: "engineering",
+ principal: <principal>,
+ }
+ ]
+ }
+ ]
+ }
+</code></pre>
+
+<p>Take note of the fact that <code>role</code> and <code>reservation</code> are not set, and that there
+is a new field called <code>reservations</code> which represents the reservation state.
+With <code>RESERVATION_REFINEMENT</code> enabled, the framework receives resources in this
+new format where solely the <code>reservations</code> field is used for the reservation
+state, rather than <code>role</code>/<code>reservation</code> pair from pre-<code>RESERVATION_REFINEMENT</code>.</p>
+
+<p>We can reserve 8 CPUs and 4096 MB of RAM to <code>"engineering/backend"</code> by sending
+the following <code>Offer::Operation</code> message. <code>Offer::Operation::Reserve</code> has
+a <code>resources</code> field which we specify with the resources to be reserved.
+We must <strong>push</strong> a new <code>ReservationInfo</code> message onto the back of
+the <code>reservations</code> field. We must explicitly set the reservation’s' <code>role</code> field
+to the offer’s allocation role. The optional value of the <code>principal</code> field
+depends on whether or not the framework provided a principal when it registered
+with the master. If a principal was provided, then the resources' <code>principal</code>
+field must be equal to the framework’s principal. If no principal was provided
+during registration, then the resources' <code>principal</code> field can take any value,
+or can be left unset. Note that the <code>principal</code> field determines
+the “reserver principal” when <a href="/documentation/latest/./authorization/">authorization</a> is enabled, even
+if authentication is disabled.</p>
+
+<pre><code> {
+ "type": Offer::Operation::RESERVE,
+ "reserve": {
+ "resources": [
+ {
+ "allocation_info": { "role": "engineering/backend" },
+ "name": "cpus",
+ "type": "SCALAR",
+ "scalar": { "value": 8 },
+ "reservations": [
+ {
+ type: DYNAMIC,
+ role: "engineering",
+ principal: <principal>,
+ },
+ {
+ type: DYNAMIC,
+ role: "engineering/backend",
+ principal: <framework_principal>,
+ }
+ ]
+ },
+ {
+ "allocation_info": { "role": "engineering/backend" },
+ "name": "mem",
+ "type": "SCALAR",
+ "scalar": { "value": 4096 },
+ "reservations": [
+ {
+ type: DYNAMIC,
+ role: "engineering",
+ principal: <principal>,
+ },
+ {
+ type: DYNAMIC,
+ role: "engineering/backend",
+ principal: <framework_principal>,
+ }
+ ]
+ }
+ ]
+ }
+ }
+</code></pre>
+
+<p>If the reservation is successful, a subsequent resource offer will contain the
+following reserved resources:</p>
+
+<pre><code> {
+ "allocation_info": { "role": "engineering/backend" },
+ "id": <offer_id>,
+ "framework_id": <framework_id>,
+ "slave_id": <slave_id>,
+ "hostname": <hostname>,
+ "resources": [
+ {
+ "allocation_info": { "role": "engineering/backend" },
+ "name": "cpus",
+ "type": "SCALAR",
+ "scalar": { "value": 8 },
+ "reservations": [
+ {
+ type: DYNAMIC,
+ role: "engineering",
+ principal: <principal>,
+ },
+ {
+ type: DYNAMIC,
+ role: "engineering/backend",
+ principal: <framework_principal>,
+ }
+ ]
+ },
+ {
+ "allocation_info": { "role": "engineering/backend" },
+ "name": "mem",
+ "type": "SCALAR",
+ "scalar": { "value": 4096 },
+ "reservations": [
+ {
+ type: DYNAMIC,
+ role: "engineering",
+ principal: <principal>,
+ },
+ {
+ type: DYNAMIC,
+ role: "engineering/backend",
+ principal: <framework_principal>,
+ }
+ ]
+ },
+ ]
+ }
+</code></pre>
+
+<h4><code>Offer::Operation::Unreserve</code> (<strong>with</strong> <code>RESERVATION_REFINEMENT</code>)</h4>
+
+<p>A framework can unreserve resources through the resource offer cycle.
+In <a href="#offer-operation-reserve-reservation-refinement">Offer::Operation::Reserve</a>,
+we reserved 8 CPUs and 4096 MB of RAM on a particular slave for one of our
+subscribed roles (i.e. <code>"engineering/backend"</code>), previously reserved for
+<code>"engineering"</code>. When we unreserve these resources, they are returned to
+<code>"engineering"</code>, by the last <code>ReservationInfo</code> added to
+the <code>reservations</code> field being <strong>popped</strong>. First, we receive a resource offer
+(copy/pasted from above):</p>
+
+<pre><code> {
+ "allocation_info": { "role": "engineering/backend" },
+ "id": <offer_id>,
+ "framework_id": <framework_id>,
+ "slave_id": <slave_id>,
+ "hostname": <hostname>,
+ "resources": [
+ {
+ "allocation_info": { "role": "engineering/backend" },
+ "name": "cpus",
+ "type": "SCALAR",
+ "scalar": { "value": 8 },
+ "reservations": [
+ {
+ type: DYNAMIC,
+ role: "engineering",
+ principal: <principal>,
+ },
+ {
+ type: DYNAMIC,
+ role: "engineering/backend",
+ principal: <framework_principal>,
+ }
+ ]
+ },
+ {
+ "allocation_info": { "role": "engineering/backend" },
+ "name": "mem",
+ "type": "SCALAR",
+ "scalar": { "value": 4096 },
+ "reservations": [
+ {
+ type: DYNAMIC,
+ role: "engineering",
+ principal: <principal>,
+ },
+ {
+ type: DYNAMIC,
+ role: "engineering/backend",
+ principal: <framework_principal>,
+ }
+ ]
+ },
+ ]
+ }
+</code></pre>
+
+<p>We can unreserve the 8 CPUs and 4096 MB of RAM by sending the following
+<code>Offer::Operation</code> message. <code>Offer::Operation::Unreserve</code> has a <code>resources</code> field
+which we can use to specify the resources to be unreserved.</p>
+
+<pre><code> {
+ "type": Offer::Operation::UNRESERVE,
+ "unreserve": {
+ "resources": [
+ {
+ "allocation_info": { "role": "engineering/backend" },
+ "name": "cpus",
+ "type": "SCALAR",
+ "scalar": { "value": 8 },
+ "reservations": [
+ {
+ type: DYNAMIC,
+ role: "engineering",
+ principal: <principal>,
+ },
+ {
+ type: DYNAMIC,
+ role: "engineering/backend",
+ principal: <framework_principal>,
+ }
+ ]
+ },
+ {
+ "allocation_info": { "role": "engineering/backend" },
+ "name": "mem",
+ "type": "SCALAR",
+ "scalar": { "value": 4096 },
+ "reservations": [
+ {
+ type: DYNAMIC,
+ role: "engineering",
+ principal: <principal>,
+ },
+ {
+ type: DYNAMIC,
+ role: "engineering/backend",
+ principal: <framework_principal>,
+ }
+ ]
+ },
+ ]
+ }
+ }
+</code></pre>
+
+<p>The resources will now be reserved for <code>"engineering"</code> again, and may now be
+offered to <code>"engineering"</code> role itself, or other roles under <code>"engineering"</code>.</p>
+
<h3>Operator HTTP Endpoints</h3>
<p>As described above, dynamic reservations can be made by a framework scheduler,
@@ -520,18 +829,6 @@ 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
<a href="/documentation/latest/./endpoints/slave/state/">/state</a> HTTP endpoint).</p>
-<h3>Listing Reservations</h3>
-
-<p>Information about the reserved resources at each slave in the cluster can be
-found by querying the <a href="/documentation/latest/./endpoints/master/slaves/">/slaves</a> master endpoint
-(under the <code>reserved_resources_full</code> key).</p>
-
-<p>The same information can also be found in the <a href="/documentation/latest/./endpoints/slave/state/">/state</a>
-endpoint on the agent (under the <code>reserved_resources_full</code> key). The agent
-endpoint is useful to confirm if a reservation has been propagated to the
-agent (which can fail in the event of network partition or master/agent
-restarts).</p>
-
</div>
</div>
http://git-wip-us.apache.org/repos/asf/mesos-site/blob/afed5858/content/documentation/latest/upgrades/index.html
----------------------------------------------------------------------
diff --git a/content/documentation/latest/upgrades/index.html b/content/documentation/latest/upgrades/index.html
index 616c9ae..69e7328 100644
--- a/content/documentation/latest/upgrades/index.html
+++ b/content/documentation/latest/upgrades/index.html
@@ -217,6 +217,7 @@ R Removed feature/behavior
<ul style="padding-left:10px;">
<li>A <a href="#1-4-x-bounding-capabilities">Support for explicit setting bounding capabilities</a></li>
<li>D <a href="#1-4-x-linuxinfo-capabilities">LinuxInfo.effective_capabilities deprecates LinuxInfo.capabilities</a></li>
+ <li>C <a href="#1-4-x-mesos-library">`Resources` class in the internal Mesos C++ library only supports post-`RESERVATION_REFINEMENT` format</a></li>
</ul>
</td>
@@ -582,6 +583,13 @@ that caused a task to fail with a resource limitation reason.</li>
</ul>
+<p><a name="1-4-x-mesos-library"></a></p>
+
+<ul>
+<li>The <code>Resources</code> class in the internal Mesos C++ library changed its behavior to only support post-<code>RESERVATION_REFINEMENT</code> format. If a framework is using this internal utility, it is likely to break if the <code>RESERVATION_REFINEMENT</code> capability is not enabled.</li>
+</ul>
+
+
<h2>Upgrading from 1.2.x to 1.3.x</h2>
<p><a name="1-3-x-disallow-old-agents"></a></p>
http://git-wip-us.apache.org/repos/asf/mesos-site/blob/afed5858/content/documentation/reservation/index.html
----------------------------------------------------------------------
diff --git a/content/documentation/reservation/index.html b/content/documentation/reservation/index.html
index 540e810..ff6e784 100644
--- a/content/documentation/reservation/index.html
+++ b/content/documentation/reservation/index.html
@@ -193,7 +193,7 @@ running task or if a <a href="/documentation/latest/./persistent-volume/">persis
using the reserved resources. In the latter case, the volume should be destroyed
before unreserving the resources.</p>
-<h3>Labeled Reservations</h3>
+<h2>Reservation Labels</h2>
<p>Dynamic reservations can optionally include a list of <em>labels</em>, which are
arbitrary key-value pairs. Labels can be used to associate arbitrary metadata
@@ -203,11 +203,39 @@ given slave. Note that two reservations with different labels will not be
combined together into a single reservation, even if the reservations are at the
same slave and use the same role.</p>
+<h2>Reservation Refinement</h2>
+
+<p>Hierarhical roles such as <code>eng/backend</code> enable the delegation of resources
+down a hierarchy, and reservation refinement is the mechanism with which
+<strong>reservations</strong> are delegated down the hierarchy. For example, a reservation
+(static or dynamic) for <code>eng</code> can be <strong>refined</strong> to <code>eng/backend</code>. When such
+a reservation is unreserved, they are returned to the previous owner. In this
+case it would be returned to <code>eng</code>. Reservation refinements can also “skip”
+levels. For example, <code>eng</code> can be <strong>refined</strong> directly to <code>eng/backend/db</code>.
+Again, unreserving such a reservation is returned to its previous owner <code>eng</code>.</p>
+
+<p><strong>NOTE:</strong> Frameworks need to enable the <code>RESERVATION_REFINEMENT</code> capability
+in order to be offered, and to create refined reservations</p>
+
+<h2>Listing Reservations</h2>
+
+<p>Information about the reserved resources at each slave in the cluster can be
+found by querying the <a href="/documentation/latest/./endpoints/master/slaves/">/slaves</a> master endpoint
+(under the <code>reserved_resources_full</code> key).</p>
+
+<p>The same information can also be found in the <a href="/documentation/latest/./endpoints/slave/state/">/state</a>
+endpoint on the agent (under the <code>reserved_resources_full</code> key). The agent
+endpoint is useful to confirm if a reservation has been propagated to the
+agent (which can fail in the event of network partition or master/agent
+restarts).</p>
+
+<h2>Examples</h2>
+
<h3>Framework Scheduler API</h3>
<p><a name="offer-operation-reserve"></a></p>
-<h4><code>Offer::Operation::Reserve</code></h4>
+<h4><code>Offer::Operation::Reserve</code> (<strong>without</strong> <code>RESERVATION_REFINEMENT</code>)</h4>
<p>A framework can reserve resources through the resource offer cycle. The
reservation role must match the offer’s allocation role. Suppose we
@@ -315,7 +343,7 @@ following reserved resources:</p>
}
</code></pre>
-<h4><code>Offer::Operation::Unreserve</code></h4>
+<h4><code>Offer::Operation::Unreserve</code> (<strong>without</strong> <code>RESERVATION_REFINEMENT</code>)</h4>
<p>A framework can unreserve resources through the resource offer cycle.
In <a href="#offer-operation-reserve">Offer::Operation::Reserve</a>, we reserved 8 CPUs
@@ -390,6 +418,287 @@ which we can use to specify the resources to be unreserved.</p>
<p>The unreserved resources may now be offered to other frameworks.</p>
+<p><a name="offer-operation-reserve-reservation-refinement"></a></p>
+
+<h4><code>Offer::Operation::Reserve</code> (<strong>with</strong> <code>RESERVATION_REFNEMENT</code>)</h4>
+
+<p>A framework that wants to create a refined reservation needs to enable
+the <code>RESERVATION_REFINEMENT</code> capability. Doing so will allow the framework
+to use the <code>reservations</code> field in the <code>Resource</code> message in order to
+<strong>push</strong> a refined reservation.</p>
+
+<p>Since reserved resources are offered to any of the child roles under the role
+for which they are reserved for, they can get <strong>allocated</strong> to say,
+<code>"engineering/backend"</code> while being <strong>reserved</strong> for <code>"engineering"</code>.
+It can then be refined to be <strong>reserved</strong> for <code>"engineering/backend"</code>.</p>
+
+<p>Note that the refined reservation role must match the offer’s allocation role.</p>
+
+<p>Suppose we receive a resource offer with 12 CPUs and 6144 MB of RAM unreserved,
+allocated to role <code>"engineering/backend"</code>, reserved to <code>"engineering"</code>.</p>
+
+<pre><code> {
+ "allocation_info": { "role": "engineering/backend" },
+ "id": <offer_id>,
+ "framework_id": <framework_id>,
+ "slave_id": <slave_id>,
+ "hostname": <hostname>,
+ "resources": [
+ {
+ "allocation_info": { "role": "engineering/backend" },
+ "name": "cpus",
+ "type": "SCALAR",
+ "scalar": { "value": 12 },
+ "reservations": [
+ {
+ type: DYNAMIC,
+ role: "engineering",
+ principal: <principal>,
+ }
+ ]
+ },
+ {
+ "allocation_info": { "role": "engineering/backend" },
+ "name": "mem",
+ "type": "SCALAR",
+ "scalar": { "value": 6144 },
+ "reservations": [
+ {
+ type: DYNAMIC,
+ role: "engineering",
+ principal: <principal>,
+ }
+ ]
+ }
+ ]
+ }
+</code></pre>
+
+<p>Take note of the fact that <code>role</code> and <code>reservation</code> are not set, and that there
+is a new field called <code>reservations</code> which represents the reservation state.
+With <code>RESERVATION_REFINEMENT</code> enabled, the framework receives resources in this
+new format where solely the <code>reservations</code> field is used for the reservation
+state, rather than <code>role</code>/<code>reservation</code> pair from pre-<code>RESERVATION_REFINEMENT</code>.</p>
+
+<p>We can reserve 8 CPUs and 4096 MB of RAM to <code>"engineering/backend"</code> by sending
+the following <code>Offer::Operation</code> message. <code>Offer::Operation::Reserve</code> has
+a <code>resources</code> field which we specify with the resources to be reserved.
+We must <strong>push</strong> a new <code>ReservationInfo</code> message onto the back of
+the <code>reservations</code> field. We must explicitly set the reservation’s' <code>role</code> field
+to the offer’s allocation role. The optional value of the <code>principal</code> field
+depends on whether or not the framework provided a principal when it registered
+with the master. If a principal was provided, then the resources' <code>principal</code>
+field must be equal to the framework’s principal. If no principal was provided
+during registration, then the resources' <code>principal</code> field can take any value,
+or can be left unset. Note that the <code>principal</code> field determines
+the “reserver principal” when <a href="/documentation/latest/./authorization/">authorization</a> is enabled, even
+if authentication is disabled.</p>
+
+<pre><code> {
+ "type": Offer::Operation::RESERVE,
+ "reserve": {
+ "resources": [
+ {
+ "allocation_info": { "role": "engineering/backend" },
+ "name": "cpus",
+ "type": "SCALAR",
+ "scalar": { "value": 8 },
+ "reservations": [
+ {
+ type: DYNAMIC,
+ role: "engineering",
+ principal: <principal>,
+ },
+ {
+ type: DYNAMIC,
+ role: "engineering/backend",
+ principal: <framework_principal>,
+ }
+ ]
+ },
+ {
+ "allocation_info": { "role": "engineering/backend" },
+ "name": "mem",
+ "type": "SCALAR",
+ "scalar": { "value": 4096 },
+ "reservations": [
+ {
+ type: DYNAMIC,
+ role: "engineering",
+ principal: <principal>,
+ },
+ {
+ type: DYNAMIC,
+ role: "engineering/backend",
+ principal: <framework_principal>,
+ }
+ ]
+ }
+ ]
+ }
+ }
+</code></pre>
+
+<p>If the reservation is successful, a subsequent resource offer will contain the
+following reserved resources:</p>
+
+<pre><code> {
+ "allocation_info": { "role": "engineering/backend" },
+ "id": <offer_id>,
+ "framework_id": <framework_id>,
+ "slave_id": <slave_id>,
+ "hostname": <hostname>,
+ "resources": [
+ {
+ "allocation_info": { "role": "engineering/backend" },
+ "name": "cpus",
+ "type": "SCALAR",
+ "scalar": { "value": 8 },
+ "reservations": [
+ {
+ type: DYNAMIC,
+ role: "engineering",
+ principal: <principal>,
+ },
+ {
+ type: DYNAMIC,
+ role: "engineering/backend",
+ principal: <framework_principal>,
+ }
+ ]
+ },
+ {
+ "allocation_info": { "role": "engineering/backend" },
+ "name": "mem",
+ "type": "SCALAR",
+ "scalar": { "value": 4096 },
+ "reservations": [
+ {
+ type: DYNAMIC,
+ role: "engineering",
+ principal: <principal>,
+ },
+ {
+ type: DYNAMIC,
+ role: "engineering/backend",
+ principal: <framework_principal>,
+ }
+ ]
+ },
+ ]
+ }
+</code></pre>
+
+<h4><code>Offer::Operation::Unreserve</code> (<strong>with</strong> <code>RESERVATION_REFINEMENT</code>)</h4>
+
+<p>A framework can unreserve resources through the resource offer cycle.
+In <a href="#offer-operation-reserve-reservation-refinement">Offer::Operation::Reserve</a>,
+we reserved 8 CPUs and 4096 MB of RAM on a particular slave for one of our
+subscribed roles (i.e. <code>"engineering/backend"</code>), previously reserved for
+<code>"engineering"</code>. When we unreserve these resources, they are returned to
+<code>"engineering"</code>, by the last <code>ReservationInfo</code> added to
+the <code>reservations</code> field being <strong>popped</strong>. First, we receive a resource offer
+(copy/pasted from above):</p>
+
+<pre><code> {
+ "allocation_info": { "role": "engineering/backend" },
+ "id": <offer_id>,
+ "framework_id": <framework_id>,
+ "slave_id": <slave_id>,
+ "hostname": <hostname>,
+ "resources": [
+ {
+ "allocation_info": { "role": "engineering/backend" },
+ "name": "cpus",
+ "type": "SCALAR",
+ "scalar": { "value": 8 },
+ "reservations": [
+ {
+ type: DYNAMIC,
+ role: "engineering",
+ principal: <principal>,
+ },
+ {
+ type: DYNAMIC,
+ role: "engineering/backend",
+ principal: <framework_principal>,
+ }
+ ]
+ },
+ {
+ "allocation_info": { "role": "engineering/backend" },
+ "name": "mem",
+ "type": "SCALAR",
+ "scalar": { "value": 4096 },
+ "reservations": [
+ {
+ type: DYNAMIC,
+ role: "engineering",
+ principal: <principal>,
+ },
+ {
+ type: DYNAMIC,
+ role: "engineering/backend",
+ principal: <framework_principal>,
+ }
+ ]
+ },
+ ]
+ }
+</code></pre>
+
+<p>We can unreserve the 8 CPUs and 4096 MB of RAM by sending the following
+<code>Offer::Operation</code> message. <code>Offer::Operation::Unreserve</code> has a <code>resources</code> field
+which we can use to specify the resources to be unreserved.</p>
+
+<pre><code> {
+ "type": Offer::Operation::UNRESERVE,
+ "unreserve": {
+ "resources": [
+ {
+ "allocation_info": { "role": "engineering/backend" },
+ "name": "cpus",
+ "type": "SCALAR",
+ "scalar": { "value": 8 },
+ "reservations": [
+ {
+ type: DYNAMIC,
+ role: "engineering",
+ principal: <principal>,
+ },
+ {
+ type: DYNAMIC,
+ role: "engineering/backend",
+ principal: <framework_principal>,
+ }
+ ]
+ },
+ {
+ "allocation_info": { "role": "engineering/backend" },
+ "name": "mem",
+ "type": "SCALAR",
+ "scalar": { "value": 4096 },
+ "reservations": [
+ {
+ type: DYNAMIC,
+ role: "engineering",
+ principal: <principal>,
+ },
+ {
+ type: DYNAMIC,
+ role: "engineering/backend",
+ principal: <framework_principal>,
+ }
+ ]
+ },
+ ]
+ }
+ }
+</code></pre>
+
+<p>The resources will now be reserved for <code>"engineering"</code> again, and may now be
+offered to <code>"engineering"</code> role itself, or other roles under <code>"engineering"</code>.</p>
+
<h3>Operator HTTP Endpoints</h3>
<p>As described above, dynamic reservations can be made by a framework scheduler,
@@ -520,18 +829,6 @@ 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
<a href="/documentation/latest/./endpoints/slave/state/">/state</a> HTTP endpoint).</p>
-<h3>Listing Reservations</h3>
-
-<p>Information about the reserved resources at each slave in the cluster can be
-found by querying the <a href="/documentation/latest/./endpoints/master/slaves/">/slaves</a> master endpoint
-(under the <code>reserved_resources_full</code> key).</p>
-
-<p>The same information can also be found in the <a href="/documentation/latest/./endpoints/slave/state/">/state</a>
-endpoint on the agent (under the <code>reserved_resources_full</code> key). The agent
-endpoint is useful to confirm if a reservation has been propagated to the
-agent (which can fail in the event of network partition or master/agent
-restarts).</p>
-
</div>
</div>
http://git-wip-us.apache.org/repos/asf/mesos-site/blob/afed5858/content/documentation/upgrades/index.html
----------------------------------------------------------------------
diff --git a/content/documentation/upgrades/index.html b/content/documentation/upgrades/index.html
index dd286a2..a525e6e 100644
--- a/content/documentation/upgrades/index.html
+++ b/content/documentation/upgrades/index.html
@@ -217,6 +217,7 @@ R Removed feature/behavior
<ul style="padding-left:10px;">
<li>A <a href="#1-4-x-bounding-capabilities">Support for explicit setting bounding capabilities</a></li>
<li>D <a href="#1-4-x-linuxinfo-capabilities">LinuxInfo.effective_capabilities deprecates LinuxInfo.capabilities</a></li>
+ <li>C <a href="#1-4-x-mesos-library">`Resources` class in the internal Mesos C++ library only supports post-`RESERVATION_REFINEMENT` format</a></li>
</ul>
</td>
@@ -582,6 +583,13 @@ that caused a task to fail with a resource limitation reason.</li>
</ul>
+<p><a name="1-4-x-mesos-library"></a></p>
+
+<ul>
+<li>The <code>Resources</code> class in the internal Mesos C++ library changed its behavior to only support post-<code>RESERVATION_REFINEMENT</code> format. If a framework is using this internal utility, it is likely to break if the <code>RESERVATION_REFINEMENT</code> capability is not enabled.</li>
+</ul>
+
+
<h2>Upgrading from 1.2.x to 1.3.x</h2>
<p><a name="1-3-x-disallow-old-agents"></a></p>