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 <[email protected]> Authored: Sat May 5 00:07:49 2018 +0000 Committer: jenkins <[email protected]> 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>
