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 2018/05/05 00:07:54 UTC
[2/2] mesos-site git commit: Updated the website built from mesos
SHA: 110a176.
Updated the website built from mesos SHA: 110a176.
Project: http://git-wip-us.apache.org/repos/asf/mesos-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/mesos-site/commit/25ac6715
Tree: http://git-wip-us.apache.org/repos/asf/mesos-site/tree/25ac6715
Diff: http://git-wip-us.apache.org/repos/asf/mesos-site/diff/25ac6715
Branch: refs/heads/asf-site
Commit: 25ac6715bc4707ad290ca07f8afa21aeb1045a2f
Parents: 30be8a7
Author: jenkins <bu...@apache.org>
Authored: Sat May 5 00:07:49 2018 +0000
Committer: jenkins <bu...@apache.org>
Committed: Sat May 5 00:07:49 2018 +0000
----------------------------------------------------------------------
content/blog/feed.xml | 2 +-
.../index.html | 2 +-
content/documentation/authorization/index.html | 8 +
.../latest/authorization/index.html | 8 +
.../latest/operator-http-api/index.html | 119 +-
.../latest/persistent-volume/index.html | 290 +-
.../documentation/operator-http-api/index.html | 119 +-
.../documentation/persistent-volume/index.html | 290 +-
content/sitemap.xml | 9162 +++++++++---------
9 files changed, 5379 insertions(+), 4621 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/mesos-site/blob/25ac6715/content/blog/feed.xml
----------------------------------------------------------------------
diff --git a/content/blog/feed.xml b/content/blog/feed.xml
index 407dc9e..b0755ed 100644
--- a/content/blog/feed.xml
+++ b/content/blog/feed.xml
@@ -292,7 +292,7 @@ To learn more about CSI work in Mesos, you can dig into the design document <
</ul>
-<p>If you are a user and would like to suggest some areas for performance improvement, please let us know by emailing <a href="&#x6d;&#x61;&#105;&#x6c;&#x74;&#111;&#x3a;&#100;&#x65;&#118;&#x40;&#x61;&#112;&#x61;&#99;&#104;&#x65;&#x2e;&#x6d;&#x65;&#115;&#111;&#x73;&#x2e;&#x6f;&#114;&#103;">&#x64;&#101;&#x76;&#64;&#x61;&#112;&#x61;&#99;&#x68;&#x65;&#x2e;&#x6d;&#101;&#x73;&#x6f;&#115;&#x2e;&#111;&#114;&#103;</a>.</p>
+<p>If you are a user and would like to suggest some areas for performance improvement, please let us know by emailing <a href="&#109;&#x61;&#105;&#108;&#116;&#111;&#x3a;&#100;&#101;&#118;&#64;&#97;&#112;&#x61;&#99;&#104;&#101;&#x2e;&#109;&#x65;&#115;&#111;&#115;&#46;&#x6f;&#114;&#103;">&#100;&#101;&#x76;&#64;&#97;&#112;&#97;&#x63;&#x68;&#101;&#46;&#x6d;&#101;&#x73;&#111;&#115;&#x2e;&#x6f;&#114;&#x67;</a>.</p>
</content>
</entry>
http://git-wip-us.apache.org/repos/asf/mesos-site/blob/25ac6715/content/blog/performance-working-group-progress-report/index.html
----------------------------------------------------------------------
diff --git a/content/blog/performance-working-group-progress-report/index.html b/content/blog/performance-working-group-progress-report/index.html
index 01b9bbc..90f42d4 100644
--- a/content/blog/performance-working-group-progress-report/index.html
+++ b/content/blog/performance-working-group-progress-report/index.html
@@ -238,7 +238,7 @@
</ul>
-<p>If you are a user and would like to suggest some areas for performance improvement, please let us know by emailing <a href="mailto:dev@apache.mesos.org">dev@apache.mesos.org</a>.</p>
+<p>If you are a user and would like to suggest some areas for performance improvement, please let us know by emailing <a href="mailto:dev@apache.mesos.org">dev@apache.mesos.org</a>.</p>
</div>
</div>
http://git-wip-us.apache.org/repos/asf/mesos-site/blob/25ac6715/content/documentation/authorization/index.html
----------------------------------------------------------------------
diff --git a/content/documentation/authorization/index.html b/content/documentation/authorization/index.html
index a99cf2c..5617be3 100644
--- a/content/documentation/authorization/index.html
+++ b/content/documentation/authorization/index.html
@@ -318,6 +318,14 @@ entries, each representing an authorizable action:</p>
</td>
</tr>
<tr>
+ <td><code>resize_volume</code></td>
+ <td>Framework principal or Operator username.</td>
+ <td>Resource role of the volume.</td>
+ <td>Growing or shrinking
+ <a href="/documentation/latest/./persistent-volume/">persistent volumes</a>.
+ </td>
+</tr>
+<tr>
<td><code>get_quotas</code></td>
<td>Operator username.</td>
<td>Resource role whose quota status will be queried.</td>
http://git-wip-us.apache.org/repos/asf/mesos-site/blob/25ac6715/content/documentation/latest/authorization/index.html
----------------------------------------------------------------------
diff --git a/content/documentation/latest/authorization/index.html b/content/documentation/latest/authorization/index.html
index 1e16ec8..ee7ec34 100644
--- a/content/documentation/latest/authorization/index.html
+++ b/content/documentation/latest/authorization/index.html
@@ -318,6 +318,14 @@ entries, each representing an authorizable action:</p>
</td>
</tr>
<tr>
+ <td><code>resize_volume</code></td>
+ <td>Framework principal or Operator username.</td>
+ <td>Resource role of the volume.</td>
+ <td>Growing or shrinking
+ <a href="/documentation/latest/./persistent-volume/">persistent volumes</a>.
+ </td>
+</tr>
+<tr>
<td><code>get_quotas</code></td>
<td>Operator username.</td>
<td>Resource role whose quota status will be queried.</td>
http://git-wip-us.apache.org/repos/asf/mesos-site/blob/25ac6715/content/documentation/latest/operator-http-api/index.html
----------------------------------------------------------------------
diff --git a/content/documentation/latest/operator-http-api/index.html b/content/documentation/latest/operator-http-api/index.html
index 83e2cb7..5534c58 100644
--- a/content/documentation/latest/operator-http-api/index.html
+++ b/content/documentation/latest/operator-http-api/index.html
@@ -1949,11 +1949,11 @@ HTTP/1.1 202 Accepted
<h3>CREATE_VOLUMES</h3>
-<p>This call create persistent volumes on reserved resources. The request is
-forwarded asynchronously to the Mesos agent where the reserved resources are
-located. That asynchronous message may not be delivered or creating the volumes
-at the agent might fail. This call takes <code>agent_id</code> and <code>volumes</code> details like
-the following.</p>
+<p>This call create <a href="/documentation/latest/./persistent-volume/">persistent volumes</a> on reserved
+resources. The request is forwarded asynchronously to the Mesos agent where the
+reserved resources are located. That asynchronous message may not be delivered
+or creating the volumes at the agent might fail. This call takes <code>agent_id</code>
+and <code>volumes</code> details like the following.</p>
<pre><code>CREATE_VOLUMES HTTP Request (JSON):
@@ -2000,8 +2000,8 @@ HTTP/1.1 202 Accepted
<h3>DESTROY_VOLUMES</h3>
-<p>This call destroys persistent volumes. The request is forwarded asynchronously to the
-Mesos agent where the reserved resources are located.</p>
+<p>This call destroys <a href="/documentation/latest/./persistent-volume/">persistent volumes</a>. The request is
+forwarded asynchronously to the Mesos agent where the volumes are located.</p>
<pre><code>DESTROY_VOLUMES HTTP Request (JSON):
@@ -2046,6 +2046,111 @@ DESTROY_VOLUMES HTTP Response:
HTTP/1.1 202 Accepted
</code></pre>
+<h3>GROW_VOLUME</h3>
+
+<p>This call grows the size of a <a href="/documentation/latest/./persistent-volume/">persistent volume</a>. The
+request is forwarded asynchronously to the Mesos agent where the volume is
+located.</p>
+
+<pre><code>GROW_VOLUME HTTP Request (JSON):
+
+POST /api/v1 HTTP/1.1
+
+Host: masterhost:5050
+Content-Type: application/json
+Accept: application/json
+
+{
+ "type": "GROW_VOLUME",
+ "grow_volume": {
+ "agent_id": {
+ "value": "919141a8-b434-4946-86b9-e1b65c8171f6-S0"
+ },
+ "volume": {
+ "disk": {
+ "persistence": {
+ "id": "id1",
+ "principal": "my-principal"
+ },
+ "volume": {
+ "container_path": "path1",
+ "mode": "RW"
+ }
+ },
+ "name": "disk",
+ "role": "role1",
+ "scalar": {
+ "value": 64.0
+ },
+ "type": "SCALAR"
+ },
+ "addition": {
+ "name": "disk",
+ "role": "role1",
+ "scalar": {
+ "value": 64.0
+ },
+ "type": "SCALAR"
+ }
+ }
+}
+
+
+GROW_VOLUME HTTP Response:
+
+HTTP/1.1 202 Accepted
+</code></pre>
+
+<h3>SHRINK_VOLUME</h3>
+
+<p>This call shrinks the size of a <a href="/documentation/latest/./persistent-volume/">persistent volume</a>.
+The request is forwarded asynchronously to the Mesos agent where the volume
+is located.</p>
+
+<pre><code>SHRINK_VOLUME HTTP Request (JSON):
+
+POST /api/v1 HTTP/1.1
+
+Host: masterhost:5050
+Content-Type: application/json
+Accept: application/json
+
+{
+ "type": "SHRINK_VOLUME",
+ "shrink_volume": {
+ "agent_id": {
+ "value": "919141a8-b434-4946-86b9-e1b65c8171f6-S0"
+ },
+ "volume": {
+ "disk": {
+ "persistence": {
+ "id": "id1",
+ "principal": "my-principal"
+ },
+ "volume": {
+ "container_path": "path1",
+ "mode": "RW"
+ }
+ },
+ "name": "disk",
+ "role": "role1",
+ "scalar": {
+ "value": 128.0
+ },
+ "type": "SCALAR"
+ },
+ "subtract": {
+ "value": 64.0
+ }
+ }
+}
+
+
+SHRINK_VOLUME HTTP Response:
+
+HTTP/1.1 202 Accepted
+</code></pre>
+
<h3>GET_MAINTENANCE_STATUS</h3>
<p>This call retrieves the cluster’s maintenance status.</p>
http://git-wip-us.apache.org/repos/asf/mesos-site/blob/25ac6715/content/documentation/latest/persistent-volume/index.html
----------------------------------------------------------------------
diff --git a/content/documentation/latest/persistent-volume/index.html b/content/documentation/latest/persistent-volume/index.html
index d48eb37..4bfe42d 100644
--- a/content/documentation/latest/persistent-volume/index.html
+++ b/content/documentation/latest/persistent-volume/index.html
@@ -158,9 +158,19 @@ appropriate ACLs. For more information, see the
<a href="/documentation/latest/./authorization/">authorization documentation</a>.</p>
<ul>
-<li><code>Offer::Operation::Create</code> and <code>Offer::Operation::Destroy</code> messages are
-available for <strong>frameworks</strong> to send back via the <code>acceptOffers</code> API as a
-response to a resource offer.</li>
+<li>The following messages are available for <strong>frameworks</strong> to send back via the
+<code>acceptOffers</code> API as a response to a resource offer:
+
+<ul>
+<li><code>Offer::Operation::Create</code></li>
+<li><code>Offer::Operation::Destroy</code></li>
+<li><code>Offer::Operation::GrowVolume</code></li>
+<li><code>Offer::Operation::ShrinkVolume</code></li>
+</ul>
+</li>
+<li>For each message in above list, a corresponding call in
+<a href="/documentation/latest/./operator-http-api/">HTTP Operator API</a> is available for operators or
+administrative tools;</li>
<li><code>/create-volumes</code> and <code>/destroy-volumes</code> HTTP endpoints allow
<strong>operators</strong> to manage persistent volumes through the master.</li>
</ul>
@@ -316,9 +326,9 @@ created. First, we receive a resource offer (copy/pasted from above):</p>
}
</code></pre>
-<p>We can destroy the persistent volume by sending a <code>Offer::Operation</code> message via
-the <code>acceptOffers</code> API. <code>Offer::Operation::Destroy</code> has a <code>volumes</code> field which
-specifies the persistent volumes to be destroyed.</p>
+<p>We can destroy the persistent volume by sending an <code>Offer::Operation</code> message
+via the <code>acceptOffers</code> API. <code>Offer::Operation::Destroy</code> has a <code>volumes</code> field
+which specifies the persistent volumes to be destroyed.</p>
<pre><code>{
"type" : Offer::Operation::DESTROY,
@@ -374,13 +384,268 @@ contain the following reserved disk resources:</p>
<p>Those reserved resources can then be used as normal: e.g., they can be used to
create another persistent volume or can be unreserved.</p>
-<h2>Operator HTTP Endpoints</h2>
+<p><a name="offer-operation-grow-volume"></a></p>
+
+<h3><code>Offer::Operation::GrowVolume</code></h3>
+
+<p>Sometimes, a framework or an operator may find that the size of an existing
+persistent volume may be too small (possibly due to increased usage). In
+<a href="#offer-operation-create">Offer::Operation::Create</a>, we created a persistent
+volume from 2048 MB of disk resources. Suppose we want to grow the size of
+the volume to 4096 MB, we first need resource offer(s) with at least 2048 MB of
+disk resources with the same reservation and disk information:</p>
+
+<pre><code>{
+ "id" : <offer_id>,
+ "framework_id" : <framework_id>,
+ "slave_id" : <slave_id>,
+ "hostname" : <hostname>,
+ "resources" : [
+ {
+ "name" : "disk",
+ "type" : "SCALAR",
+ "scalar" : { "value" : 2048 },
+ "role" : <offer's allocation role>,
+ "reservation" : {
+ "principal" : <framework_principal>
+ }
+ },
+ {
+ "name" : "disk",
+ "type" : "SCALAR",
+ "scalar" : { "value" : 2048 },
+ "role" : <offer's allocation role>,
+ "reservation" : {
+ "principal" : <framework_principal>
+ },
+ "disk": {
+ "persistence": {
+ "id" : <persistent_volume_id>
+ },
+ "volume" : {
+ "container_path" : <container_path>,
+ "mode" : <mode>
+ }
+ }
+ }
+ ]
+}
+</code></pre>
+
+<p>We can grow the persistent volume by sending an <code>Offer::Operation</code> message.
+<code>Offer::Operation::GrowVolume</code> has a <code>volume</code> field which specifies the
+persistent volume to grow, and an <code>addition</code> field which specifies he
+additional disk space resource.</p>
+
+<pre><code>{
+ "type" : Offer::Operation::GROW_VOLUME,
+ "grow_volume" : {
+ "volume" : {
+ "name" : "disk",
+ "type" : "SCALAR",
+ "scalar" : { "value" : 2048 },
+ "role" : <offer's allocation role>,
+ "reservation" : {
+ "principal" : <framework_principal>
+ },
+ "disk": {
+ "persistence": {
+ "id" : <persistent_volume_id>
+ },
+ "volume" : {
+ "container_path" : <container_path>,
+ "mode" : <mode>
+ }
+ }
+ },
+ "addition" : {
+ "name" : "disk",
+ "type" : "SCALAR",
+ "scalar" : { "value" : 2048 },
+ "role" : <offer's allocation role>,
+ "reservation" : {
+ "principal" : <framework_principal>
+ }
+ }
+ }
+}
+</code></pre>
+
+<p>If this request succeeds, the persistent volume will be grown to the new size,
+and all files and directories associated with the volume will not be touched.
+A subsequent resource offer will contain the grown volume:</p>
+
+<pre><code>{
+ "id" : <offer_id>,
+ "framework_id" : <framework_id>,
+ "slave_id" : <slave_id>,
+ "hostname" : <hostname>,
+ "resources" : [
+ {
+ "name" : "disk",
+ "type" : "SCALAR",
+ "scalar" : { "value" : 4096 },
+ "role" : <offer's allocation role>,
+ "reservation" : {
+ "principal" : <framework_principal>
+ },
+ "disk": {
+ "persistence": {
+ "id" : <persistent_volume_id>
+ },
+ "volume" : {
+ "container_path" : <container_path>,
+ "mode" : <mode>
+ }
+ }
+ }
+ ]
+}
+</code></pre>
+
+<p><a name="offer-operation-shrink-volume"></a></p>
+
+<h3><code>Offer::Operation::ShrinkVolume</code></h3>
+
+<p>Similarly, a framework or an operator may find that the size of an existing
+persistent volume may be too large (possibly due to over provisioning), and want
+to free up unneeded disk space resources.
+In <a href="#offer-operation-create">Offer::Operation::Create</a>, we created a persistent
+volume from 2048 MB of disk resources. Suppose we want to shrink the size of
+the volume to 1024 MB, we first need a resource offer with the volume to shrink:</p>
+
+<pre><code>{
+ "id" : <offer_id>,
+ "framework_id" : <framework_id>,
+ "slave_id" : <slave_id>,
+ "hostname" : <hostname>,
+ "resources" : [
+ {
+ "name" : "disk",
+ "type" : "SCALAR",
+ "scalar" : { "value" : 2048 },
+ "role" : <offer's allocation role>,
+ "reservation" : {
+ "principal" : <framework_principal>
+ },
+ "disk": {
+ "persistence": {
+ "id" : <persistent_volume_id>
+ },
+ "volume" : {
+ "container_path" : <container_path>,
+ "mode" : <mode>
+ }
+ }
+ }
+ ]
+}
+</code></pre>
+
+<p>We can shrink the persistent volume by sending an <code>Offer::Operation</code> message via
+the <code>acceptOffers</code> API. <code>Offer::Operation::ShrinkVolume</code> has a <code>volume</code> field
+which specifies the persistent volume to grow, and a <code>subtract</code> field which
+specifies the scalar value of disk space to subtract from the volume:</p>
+
+<pre><code>{
+ "type" : Offer::Operation::SHRINK_VOLUME,
+ "shrink_volume" : {
+ "volume" : {
+ "name" : "disk",
+ "type" : "SCALAR",
+ "scalar" : { "value" : 2048 },
+ "role" : <offer's allocation role>,
+ "reservation" : {
+ "principal" : <framework_principal>
+ },
+ "disk": {
+ "persistence": {
+ "id" : <persistent_volume_id>
+ },
+ "volume" : {
+ "container_path" : <container_path>,
+ "mode" : <mode>
+ }
+ }
+ },
+ "subtract" : {
+ "value" : 1024
+ }
+ }
+}
+</code></pre>
+
+<p>If this request succeeds, the persistent volume will be shrunk to the new size,
+and all files and directories associated with the volume will not be touched.
+A subsequent resource offer will contain the shrunk volume as well as freed up
+disk resources with the same reservation information:</p>
+
+<pre><code>{
+ "id" : <offer_id>,
+ "framework_id" : <framework_id>,
+ "slave_id" : <slave_id>,
+ "hostname" : <hostname>,
+ "resources" : [
+ {
+ "name" : "disk",
+ "type" : "SCALAR",
+ "scalar" : { "value" : 1024 },
+ "role" : <offer's allocation role>,
+ "reservation" : {
+ "principal" : <framework_principal>
+ }
+ },
+ {
+ "name" : "disk",
+ "type" : "SCALAR",
+ "scalar" : { "value" : 1024 },
+ "role" : <offer's allocation role>,
+ "reservation" : {
+ "principal" : <framework_principal>
+ },
+ "disk": {
+ "persistence": {
+ "id" : <persistent_volume_id>
+ },
+ "volume" : {
+ "container_path" : <container_path>,
+ "mode" : <mode>
+ }
+ }
+ }
+ ]
+}
+</code></pre>
+
+<p>Some restrictions about resizing a volume (applicable to both
+<a href="#offer-operation-grow-volume">Offer::Operation::GrowVolume</a> and
+<a href="#offer-operation-shrink-volume">Offer::Operation::ShrinkVolume</a>):
+* Only persistent volumes created on an agent’s local disk space with <code>ROOT</code> or
+ <code>PATH</code> type can be resized;
+* A persistent volume cannot be actively used by a task when being resized;
+* A persistent volume cannot be shared when being resized;
+* Volume resize operations cannot be included in an ACCEPT call with other
+ operations which make use of the resized volume.</p>
+
+<h2>Versioned HTTP Operator API</h2>
<p>As described above, persistent volumes can be created by a framework scheduler
-as part of the resource offer cycle. Persistent volumes can also be created and
-destroyed using the <a href="/documentation/latest/./endpoints/master/create-volumes/">/create-volumes</a> and
-<a href="/documentation/latest/./endpoints/master/destroy-volumes/">/destroy-volumes</a> endpoints, respectively.
-This capability is intended for use by operators and administrative tools.</p>
+as part of the resource offer cycle. Persistent volumes can also be managed
+using the <a href="/documentation/latest/./operator-http-api/">HTTP Operator API</a>.</p>
+
+<p>This capability is intended for use by operators and administrative tools.</p>
+
+<p>For each offer operation which interacts with persistent volume, there is an
+equivalent call in master’s <a href="/documentation/latest/./operator-http-api/">HTTP Operator API</a>.</p>
+
+<h2>Unversioned Operator HTTP Endpoints</h2>
+
+<p>Several HTTP endpoints like
+<a href="/documentation/latest/./endpoints/master/create-volumes/">/create-volumes</a> and
+<a href="/documentation/latest/./endpoints/master/destroy-volumes/">/destroy-volumes</a> can still be used to
+manage persisent volumes, but we generally encourage operators to use
+versioned <a href="/documentation/latest/./operator-http-api/">HTTP Operator API</a> instead, as new features
+like resize support may not be backported.</p>
<h3><code>/create-volumes</code></h3>
@@ -626,7 +891,8 @@ master endpoint to include detailed information about persistent volumes and
dynamic reservations. Mesos 1.0 changed the semantics of destroying a volume:
in previous releases, destroying a volume would remove the Mesos-level metadata
but would not remove the volume’s data from the agent’s filesystem. Mesos 1.1
-introduced support for <a href="/documentation/latest/./shared-resources/">shared persistent volumes</a>.</p>
+introduced support for <a href="/documentation/latest/./shared-resources/">shared persistent volumes</a>. Mesos
+1.6 introduced experimental support for resizing persistent volumes.</p>
</div>
</div>
http://git-wip-us.apache.org/repos/asf/mesos-site/blob/25ac6715/content/documentation/operator-http-api/index.html
----------------------------------------------------------------------
diff --git a/content/documentation/operator-http-api/index.html b/content/documentation/operator-http-api/index.html
index ad0c43f..abe0777 100644
--- a/content/documentation/operator-http-api/index.html
+++ b/content/documentation/operator-http-api/index.html
@@ -1949,11 +1949,11 @@ HTTP/1.1 202 Accepted
<h3>CREATE_VOLUMES</h3>
-<p>This call create persistent volumes on reserved resources. The request is
-forwarded asynchronously to the Mesos agent where the reserved resources are
-located. That asynchronous message may not be delivered or creating the volumes
-at the agent might fail. This call takes <code>agent_id</code> and <code>volumes</code> details like
-the following.</p>
+<p>This call create <a href="/documentation/latest/./persistent-volume/">persistent volumes</a> on reserved
+resources. The request is forwarded asynchronously to the Mesos agent where the
+reserved resources are located. That asynchronous message may not be delivered
+or creating the volumes at the agent might fail. This call takes <code>agent_id</code>
+and <code>volumes</code> details like the following.</p>
<pre><code>CREATE_VOLUMES HTTP Request (JSON):
@@ -2000,8 +2000,8 @@ HTTP/1.1 202 Accepted
<h3>DESTROY_VOLUMES</h3>
-<p>This call destroys persistent volumes. The request is forwarded asynchronously to the
-Mesos agent where the reserved resources are located.</p>
+<p>This call destroys <a href="/documentation/latest/./persistent-volume/">persistent volumes</a>. The request is
+forwarded asynchronously to the Mesos agent where the volumes are located.</p>
<pre><code>DESTROY_VOLUMES HTTP Request (JSON):
@@ -2046,6 +2046,111 @@ DESTROY_VOLUMES HTTP Response:
HTTP/1.1 202 Accepted
</code></pre>
+<h3>GROW_VOLUME</h3>
+
+<p>This call grows the size of a <a href="/documentation/latest/./persistent-volume/">persistent volume</a>. The
+request is forwarded asynchronously to the Mesos agent where the volume is
+located.</p>
+
+<pre><code>GROW_VOLUME HTTP Request (JSON):
+
+POST /api/v1 HTTP/1.1
+
+Host: masterhost:5050
+Content-Type: application/json
+Accept: application/json
+
+{
+ "type": "GROW_VOLUME",
+ "grow_volume": {
+ "agent_id": {
+ "value": "919141a8-b434-4946-86b9-e1b65c8171f6-S0"
+ },
+ "volume": {
+ "disk": {
+ "persistence": {
+ "id": "id1",
+ "principal": "my-principal"
+ },
+ "volume": {
+ "container_path": "path1",
+ "mode": "RW"
+ }
+ },
+ "name": "disk",
+ "role": "role1",
+ "scalar": {
+ "value": 64.0
+ },
+ "type": "SCALAR"
+ },
+ "addition": {
+ "name": "disk",
+ "role": "role1",
+ "scalar": {
+ "value": 64.0
+ },
+ "type": "SCALAR"
+ }
+ }
+}
+
+
+GROW_VOLUME HTTP Response:
+
+HTTP/1.1 202 Accepted
+</code></pre>
+
+<h3>SHRINK_VOLUME</h3>
+
+<p>This call shrinks the size of a <a href="/documentation/latest/./persistent-volume/">persistent volume</a>.
+The request is forwarded asynchronously to the Mesos agent where the volume
+is located.</p>
+
+<pre><code>SHRINK_VOLUME HTTP Request (JSON):
+
+POST /api/v1 HTTP/1.1
+
+Host: masterhost:5050
+Content-Type: application/json
+Accept: application/json
+
+{
+ "type": "SHRINK_VOLUME",
+ "shrink_volume": {
+ "agent_id": {
+ "value": "919141a8-b434-4946-86b9-e1b65c8171f6-S0"
+ },
+ "volume": {
+ "disk": {
+ "persistence": {
+ "id": "id1",
+ "principal": "my-principal"
+ },
+ "volume": {
+ "container_path": "path1",
+ "mode": "RW"
+ }
+ },
+ "name": "disk",
+ "role": "role1",
+ "scalar": {
+ "value": 128.0
+ },
+ "type": "SCALAR"
+ },
+ "subtract": {
+ "value": 64.0
+ }
+ }
+}
+
+
+SHRINK_VOLUME HTTP Response:
+
+HTTP/1.1 202 Accepted
+</code></pre>
+
<h3>GET_MAINTENANCE_STATUS</h3>
<p>This call retrieves the cluster’s maintenance status.</p>
http://git-wip-us.apache.org/repos/asf/mesos-site/blob/25ac6715/content/documentation/persistent-volume/index.html
----------------------------------------------------------------------
diff --git a/content/documentation/persistent-volume/index.html b/content/documentation/persistent-volume/index.html
index ce79b61..75b7ad9 100644
--- a/content/documentation/persistent-volume/index.html
+++ b/content/documentation/persistent-volume/index.html
@@ -158,9 +158,19 @@ appropriate ACLs. For more information, see the
<a href="/documentation/latest/./authorization/">authorization documentation</a>.</p>
<ul>
-<li><code>Offer::Operation::Create</code> and <code>Offer::Operation::Destroy</code> messages are
-available for <strong>frameworks</strong> to send back via the <code>acceptOffers</code> API as a
-response to a resource offer.</li>
+<li>The following messages are available for <strong>frameworks</strong> to send back via the
+<code>acceptOffers</code> API as a response to a resource offer:
+
+<ul>
+<li><code>Offer::Operation::Create</code></li>
+<li><code>Offer::Operation::Destroy</code></li>
+<li><code>Offer::Operation::GrowVolume</code></li>
+<li><code>Offer::Operation::ShrinkVolume</code></li>
+</ul>
+</li>
+<li>For each message in above list, a corresponding call in
+<a href="/documentation/latest/./operator-http-api/">HTTP Operator API</a> is available for operators or
+administrative tools;</li>
<li><code>/create-volumes</code> and <code>/destroy-volumes</code> HTTP endpoints allow
<strong>operators</strong> to manage persistent volumes through the master.</li>
</ul>
@@ -316,9 +326,9 @@ created. First, we receive a resource offer (copy/pasted from above):</p>
}
</code></pre>
-<p>We can destroy the persistent volume by sending a <code>Offer::Operation</code> message via
-the <code>acceptOffers</code> API. <code>Offer::Operation::Destroy</code> has a <code>volumes</code> field which
-specifies the persistent volumes to be destroyed.</p>
+<p>We can destroy the persistent volume by sending an <code>Offer::Operation</code> message
+via the <code>acceptOffers</code> API. <code>Offer::Operation::Destroy</code> has a <code>volumes</code> field
+which specifies the persistent volumes to be destroyed.</p>
<pre><code>{
"type" : Offer::Operation::DESTROY,
@@ -374,13 +384,268 @@ contain the following reserved disk resources:</p>
<p>Those reserved resources can then be used as normal: e.g., they can be used to
create another persistent volume or can be unreserved.</p>
-<h2>Operator HTTP Endpoints</h2>
+<p><a name="offer-operation-grow-volume"></a></p>
+
+<h3><code>Offer::Operation::GrowVolume</code></h3>
+
+<p>Sometimes, a framework or an operator may find that the size of an existing
+persistent volume may be too small (possibly due to increased usage). In
+<a href="#offer-operation-create">Offer::Operation::Create</a>, we created a persistent
+volume from 2048 MB of disk resources. Suppose we want to grow the size of
+the volume to 4096 MB, we first need resource offer(s) with at least 2048 MB of
+disk resources with the same reservation and disk information:</p>
+
+<pre><code>{
+ "id" : <offer_id>,
+ "framework_id" : <framework_id>,
+ "slave_id" : <slave_id>,
+ "hostname" : <hostname>,
+ "resources" : [
+ {
+ "name" : "disk",
+ "type" : "SCALAR",
+ "scalar" : { "value" : 2048 },
+ "role" : <offer's allocation role>,
+ "reservation" : {
+ "principal" : <framework_principal>
+ }
+ },
+ {
+ "name" : "disk",
+ "type" : "SCALAR",
+ "scalar" : { "value" : 2048 },
+ "role" : <offer's allocation role>,
+ "reservation" : {
+ "principal" : <framework_principal>
+ },
+ "disk": {
+ "persistence": {
+ "id" : <persistent_volume_id>
+ },
+ "volume" : {
+ "container_path" : <container_path>,
+ "mode" : <mode>
+ }
+ }
+ }
+ ]
+}
+</code></pre>
+
+<p>We can grow the persistent volume by sending an <code>Offer::Operation</code> message.
+<code>Offer::Operation::GrowVolume</code> has a <code>volume</code> field which specifies the
+persistent volume to grow, and an <code>addition</code> field which specifies he
+additional disk space resource.</p>
+
+<pre><code>{
+ "type" : Offer::Operation::GROW_VOLUME,
+ "grow_volume" : {
+ "volume" : {
+ "name" : "disk",
+ "type" : "SCALAR",
+ "scalar" : { "value" : 2048 },
+ "role" : <offer's allocation role>,
+ "reservation" : {
+ "principal" : <framework_principal>
+ },
+ "disk": {
+ "persistence": {
+ "id" : <persistent_volume_id>
+ },
+ "volume" : {
+ "container_path" : <container_path>,
+ "mode" : <mode>
+ }
+ }
+ },
+ "addition" : {
+ "name" : "disk",
+ "type" : "SCALAR",
+ "scalar" : { "value" : 2048 },
+ "role" : <offer's allocation role>,
+ "reservation" : {
+ "principal" : <framework_principal>
+ }
+ }
+ }
+}
+</code></pre>
+
+<p>If this request succeeds, the persistent volume will be grown to the new size,
+and all files and directories associated with the volume will not be touched.
+A subsequent resource offer will contain the grown volume:</p>
+
+<pre><code>{
+ "id" : <offer_id>,
+ "framework_id" : <framework_id>,
+ "slave_id" : <slave_id>,
+ "hostname" : <hostname>,
+ "resources" : [
+ {
+ "name" : "disk",
+ "type" : "SCALAR",
+ "scalar" : { "value" : 4096 },
+ "role" : <offer's allocation role>,
+ "reservation" : {
+ "principal" : <framework_principal>
+ },
+ "disk": {
+ "persistence": {
+ "id" : <persistent_volume_id>
+ },
+ "volume" : {
+ "container_path" : <container_path>,
+ "mode" : <mode>
+ }
+ }
+ }
+ ]
+}
+</code></pre>
+
+<p><a name="offer-operation-shrink-volume"></a></p>
+
+<h3><code>Offer::Operation::ShrinkVolume</code></h3>
+
+<p>Similarly, a framework or an operator may find that the size of an existing
+persistent volume may be too large (possibly due to over provisioning), and want
+to free up unneeded disk space resources.
+In <a href="#offer-operation-create">Offer::Operation::Create</a>, we created a persistent
+volume from 2048 MB of disk resources. Suppose we want to shrink the size of
+the volume to 1024 MB, we first need a resource offer with the volume to shrink:</p>
+
+<pre><code>{
+ "id" : <offer_id>,
+ "framework_id" : <framework_id>,
+ "slave_id" : <slave_id>,
+ "hostname" : <hostname>,
+ "resources" : [
+ {
+ "name" : "disk",
+ "type" : "SCALAR",
+ "scalar" : { "value" : 2048 },
+ "role" : <offer's allocation role>,
+ "reservation" : {
+ "principal" : <framework_principal>
+ },
+ "disk": {
+ "persistence": {
+ "id" : <persistent_volume_id>
+ },
+ "volume" : {
+ "container_path" : <container_path>,
+ "mode" : <mode>
+ }
+ }
+ }
+ ]
+}
+</code></pre>
+
+<p>We can shrink the persistent volume by sending an <code>Offer::Operation</code> message via
+the <code>acceptOffers</code> API. <code>Offer::Operation::ShrinkVolume</code> has a <code>volume</code> field
+which specifies the persistent volume to grow, and a <code>subtract</code> field which
+specifies the scalar value of disk space to subtract from the volume:</p>
+
+<pre><code>{
+ "type" : Offer::Operation::SHRINK_VOLUME,
+ "shrink_volume" : {
+ "volume" : {
+ "name" : "disk",
+ "type" : "SCALAR",
+ "scalar" : { "value" : 2048 },
+ "role" : <offer's allocation role>,
+ "reservation" : {
+ "principal" : <framework_principal>
+ },
+ "disk": {
+ "persistence": {
+ "id" : <persistent_volume_id>
+ },
+ "volume" : {
+ "container_path" : <container_path>,
+ "mode" : <mode>
+ }
+ }
+ },
+ "subtract" : {
+ "value" : 1024
+ }
+ }
+}
+</code></pre>
+
+<p>If this request succeeds, the persistent volume will be shrunk to the new size,
+and all files and directories associated with the volume will not be touched.
+A subsequent resource offer will contain the shrunk volume as well as freed up
+disk resources with the same reservation information:</p>
+
+<pre><code>{
+ "id" : <offer_id>,
+ "framework_id" : <framework_id>,
+ "slave_id" : <slave_id>,
+ "hostname" : <hostname>,
+ "resources" : [
+ {
+ "name" : "disk",
+ "type" : "SCALAR",
+ "scalar" : { "value" : 1024 },
+ "role" : <offer's allocation role>,
+ "reservation" : {
+ "principal" : <framework_principal>
+ }
+ },
+ {
+ "name" : "disk",
+ "type" : "SCALAR",
+ "scalar" : { "value" : 1024 },
+ "role" : <offer's allocation role>,
+ "reservation" : {
+ "principal" : <framework_principal>
+ },
+ "disk": {
+ "persistence": {
+ "id" : <persistent_volume_id>
+ },
+ "volume" : {
+ "container_path" : <container_path>,
+ "mode" : <mode>
+ }
+ }
+ }
+ ]
+}
+</code></pre>
+
+<p>Some restrictions about resizing a volume (applicable to both
+<a href="#offer-operation-grow-volume">Offer::Operation::GrowVolume</a> and
+<a href="#offer-operation-shrink-volume">Offer::Operation::ShrinkVolume</a>):
+* Only persistent volumes created on an agent’s local disk space with <code>ROOT</code> or
+ <code>PATH</code> type can be resized;
+* A persistent volume cannot be actively used by a task when being resized;
+* A persistent volume cannot be shared when being resized;
+* Volume resize operations cannot be included in an ACCEPT call with other
+ operations which make use of the resized volume.</p>
+
+<h2>Versioned HTTP Operator API</h2>
<p>As described above, persistent volumes can be created by a framework scheduler
-as part of the resource offer cycle. Persistent volumes can also be created and
-destroyed using the <a href="/documentation/latest/./endpoints/master/create-volumes/">/create-volumes</a> and
-<a href="/documentation/latest/./endpoints/master/destroy-volumes/">/destroy-volumes</a> endpoints, respectively.
-This capability is intended for use by operators and administrative tools.</p>
+as part of the resource offer cycle. Persistent volumes can also be managed
+using the <a href="/documentation/latest/./operator-http-api/">HTTP Operator API</a>.</p>
+
+<p>This capability is intended for use by operators and administrative tools.</p>
+
+<p>For each offer operation which interacts with persistent volume, there is an
+equivalent call in master’s <a href="/documentation/latest/./operator-http-api/">HTTP Operator API</a>.</p>
+
+<h2>Unversioned Operator HTTP Endpoints</h2>
+
+<p>Several HTTP endpoints like
+<a href="/documentation/latest/./endpoints/master/create-volumes/">/create-volumes</a> and
+<a href="/documentation/latest/./endpoints/master/destroy-volumes/">/destroy-volumes</a> can still be used to
+manage persisent volumes, but we generally encourage operators to use
+versioned <a href="/documentation/latest/./operator-http-api/">HTTP Operator API</a> instead, as new features
+like resize support may not be backported.</p>
<h3><code>/create-volumes</code></h3>
@@ -626,7 +891,8 @@ master endpoint to include detailed information about persistent volumes and
dynamic reservations. Mesos 1.0 changed the semantics of destroying a volume:
in previous releases, destroying a volume would remove the Mesos-level metadata
but would not remove the volume’s data from the agent’s filesystem. Mesos 1.1
-introduced support for <a href="/documentation/latest/./shared-resources/">shared persistent volumes</a>.</p>
+introduced support for <a href="/documentation/latest/./shared-resources/">shared persistent volumes</a>. Mesos
+1.6 introduced experimental support for resizing persistent volumes.</p>
</div>
</div>