Repository: mesos Updated Branches: refs/heads/master 8ca2934ef -> f50277163
Added persistent volume user guide. Review: https://reviews.apache.org/r/35981 Project: http://git-wip-us.apache.org/repos/asf/mesos/repo Commit: http://git-wip-us.apache.org/repos/asf/mesos/commit/f5027716 Tree: http://git-wip-us.apache.org/repos/asf/mesos/tree/f5027716 Diff: http://git-wip-us.apache.org/repos/asf/mesos/diff/f5027716 Branch: refs/heads/master Commit: f50277163d38df50554e909b9f0e479facee6675 Parents: 8ca2934 Author: Michael Park <[email protected]> Authored: Tue Jul 7 10:26:56 2015 -0700 Committer: Jie Yu <[email protected]> Committed: Tue Jul 7 10:55:28 2015 -0700 ---------------------------------------------------------------------- docs/persistent-volume.md | 231 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 231 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/mesos/blob/f5027716/docs/persistent-volume.md ---------------------------------------------------------------------- diff --git a/docs/persistent-volume.md b/docs/persistent-volume.md new file mode 100644 index 0000000..e3dfe6d --- /dev/null +++ b/docs/persistent-volume.md @@ -0,0 +1,231 @@ +--- +layout: documentation +--- + +# Persistent Volume + +Mesos provides a mechanism to create a persistent volume from disk resources. +This enables stateful services such as HDFS and Cassandra to store their data +within Mesos rather than having to resort to network-mounted EBS volumes that +needs to be placed in a well-known location. + +Persistent volumes can only be created from __reserved__ disk resources, whether +it be statically reserved or dynamically reserved. A dynamically reserved +persistent volume also cannot be unreserved without having explicitly destroyed +the volume. These rules exist to limit the accidental mistakes such as: +a persistent volume containing sensitive data being offered to other frameworks +in the cluster. + +Please refer to the +[Reservation](reservation.md) documentation for details regarding reservation +mechanisms available in Mesos. + +Persistent volumes can be created by __operators__ and authorized +__frameworks__. We require a `principal` from the operator or framework in order +to authenticate/authorize the operations. [Authorization](authorization.md) is +specified via the existing ACL mechanism. (___Coming Soon___) + +* `Offer::Operation::Create` and `Offer::Operation::Destroy` messages are + available for __frameworks__ to send back via the `acceptOffers` API as a + response to a resource offer. +* `/create` and `/destroy` HTTP endpoints are available for __operators__ + to manage persistent volumes through the master. (___Coming Soon___). + +In the following sections, we will walk through examples of each of the +interfaces described above. + + +## `Offer::Operation::Create` + +A framework is able to create volumes through the resource offer cycle. +Suppose we receive a resource offer with 2048 MB of dynamically reserved disk. + +``` +{ + "id" : <offer_id>, + "framework_id" : <framework_id>, + "slave_id" : <slave_id>, + "hostname" : <hostname>, + "resources" : [ + { + "name" : "disk", + "type" : "SCALAR", + "scalar" : { "value" : 2048 }, + "role" : <framework_role>, + "reservation" : { + "principal" : <framework_principal> + } + } + ] +} +``` + +We can create a persistent volume from the 2048 MB of disk resources by sending +the following `Offer::Operation` message via the `acceptOffers` API. +`Offer::Operation::Create` has a `volumes` field which we specify with the +persistent volume information. We need to specify the following: + +1. ID of the persistent volume which needs to be unique per role on each slave. +1. The non-nested relative path within the container to mount the volume. +1. The permissions for the volume. Currently, `"RW"` is the only possible value. + +``` +{ + "type" : Offer::Operation::CREATE, + "create": { + "volumes" : [ + { + "name" : "disk", + "type" : "SCALAR", + "scalar" : { "value" : 2048 }, + "role" : <framework_role>, + "reservation" : { + "principal" : <framework_principal> + }, + "disk": { + "persistence": { + "id" : <persistent_volume_id> + }, + "volume" : { + "container_path" : <container_path>, + "mode" : <mode> + } + } + } + ] + } +} +``` + +The subsequent resource offer will __contain__ the following persistent volume: + +``` +{ + "id" : <offer_id>, + "framework_id" : <framework_id>, + "slave_id" : <slave_id>, + "hostname" : <hostname>, + "resources" : [ + { + "name" : "disk", + "type" : "SCALAR", + "scalar" : { "value" : 2048 }, + "role" : <framework_role>, + "reservation" : { + "principal" : <framework_principal> + }, + "disk": { + "persistence": { + "id" : <persistent_volume_id> + }, + "volume" : { + "container_path" : <container_path>, + "mode" : <mode> + } + } + } + ] +} +``` + + +## `Offer::Operation::Destroy` + +A framework is able to destroy persistent volumes through the resource offer +cycle. In [Offer::Operation::Create](#offeroperationcreate), we created a +persistent volume from 2048 MB of disk resources. Mesos will not garbage-collect +this volume until we explicitly destroy it. Suppose we would like to destroy the +volume we created. First, we receive a resource offer (copy/pasted from above): + +``` +{ + "id" : <offer_id>, + "framework_id" : <framework_id>, + "slave_id" : <slave_id>, + "hostname" : <hostname>, + "resources" : [ + { + "name" : "disk", + "type" : "SCALAR", + "scalar" : { "value" : 2048 }, + "role" : <framework_role>, + "reservation" : { + "principal" : <framework_principal> + }, + "disk": { + "persistence": { + "id" : <persistent_volume_id> + }, + "volume" : { + "container_path" : <container_path>, + "mode" : <mode> + } + } + } + ] +} +``` + +We destroy the persistent volume by sending the `Offer::Operation` message via +the `acceptOffers` API. `Offer::Operation::Destroy` has a `volumes` field which +we specify the persistent volumes to be destroyed. + +``` +{ + "type" : Offer::Operation::DESTROY, + "destroy" : { + "volumes" : [ + { + "name" : "disk", + "type" : "SCALAR", + "scalar" : { "value" : 2048 }, + "role" : <framework_role>, + "reservation" : { + "principal" : <framework_principal> + }, + "disk": { + "persistence": { + "id" : <persistent_volume_id> + }, + "volume" : { + "container_path" : <container_path>, + "mode" : <mode> + } + } + } + ] + } +} +``` + +The persistent volume will be destroyed, but the disk resources will still be +reserved. As such, the subsequent resource offer will __contain__ the following +reserved disk resources: + +``` +{ + "id" : <offer_id>, + "framework_id" : <framework_id>, + "slave_id" : <slave_id>, + "hostname" : <hostname>, + "resources" : [ + { + "name" : "disk", + "type" : "SCALAR", + "scalar" : { "value" : 2048 }, + "role" : <framework_role>, + "reservation" : { + "principal" : <framework_principal> + } + } + ] +} +``` + +Note that in 0.23, even after you destroy the persistent volume, its content +will still be on the disk. The garbage collection for persistent volumes is +coming soon: [MESOS-2048](https://issues.apache.org/jira/browse/MESOS-2408). + + +### `/create` (_Coming Soon_) +### `/destroy` (_Coming Soon_)
