From 260ff0aecb4a9763d10a69923dd05a567540b268 Mon Sep 17 00:00:00 2001 From: James DeFelice Date: Fri, 8 Apr 2016 00:20:41 +0000 Subject: [PATCH 1/3] recovered from #3607 --- docs/_layouts/docs.html | 5 ++ docs/docs/external-volumes.md | 137 ++++++++++++++++++++++++++++++++++ 2 files changed, 142 insertions(+) create mode 100644 docs/docs/external-volumes.md diff --git a/docs/_layouts/docs.html b/docs/_layouts/docs.html index bab37a7dc90..476d3232437 100644 --- a/docs/_layouts/docs.html +++ b/docs/_layouts/docs.html @@ -154,6 +154,11 @@
Reference
Stateful Applications Using Local Persistent Volumes +
  • + + Stateful Applications Using External Persistent Volumes + +
  • Task Environment Variables diff --git a/docs/docs/external-volumes.md b/docs/docs/external-volumes.md new file mode 100644 index 00000000000..592369abe63 --- /dev/null +++ b/docs/docs/external-volumes.md @@ -0,0 +1,137 @@ +--- +title: Stateful Applications Using External Persistent Volumes +--- + +# Stateful Applications Using External Persistent Volumes + + + +Marathon applications normally lose their state when they terminate and are relaunched. In some contexts, for instance, if your application uses MySQL, you’ll want your application to preserve its state. You can use an external storage service, such as Amazon's Elastic Block Store (EBS), to create a persistent volume that follows your application instance. + +Using an external storage service allows your apps to be more fault-tolerant. If a host fails, Marathon reschedules your app on another host, along with its associated data, without user intervention. + +# Specifying an External Volume + +If you are running Marathon on DCOS, add the following to the `genconf/config.yml` file you use during DCOS installation. [Learn more](https://docs.mesosphere.com/concepts/installing/installing-enterprise-edition/configuration-parameters/). + +- `rexray_config_method: file` + +- `rexray_config_filename: /path/to/rexray.yaml` + +## Scaling your App + +Apps that use external volumes should only be scaled to a single instance. + +If you scale your app down to 0 instances, the volume is unattached from the agent where it was mounted, but it is not deleted. If you scale your app up again, the data that had been associated with it will still be available. + +## Create an Application with External Volumes + +### Using a Mesos Container + +You specify an external volume in the app definition of your Marathon app. [Learn more about Marathon application definitions](application-basics.html). + +```json +{ + "id": "hello", + "instances": 1, + "cpus": 0.1, + "mem": 32, + "cmd": "/usr/bin/tail -f /dev/null", + "container": { + "type": "MESOS", + "volumes": [ + { + "containerPath": "/tmp/test-rexray-volume", + "external": { + "size": 100, + "name": "my-test-vol", + "provider": "dvdi", + "options": { "dvdi/driver": "rexray" } + }, + "mode": "RW" + } + ] + }, + "upgradeStrategy": { + "minimumHealthCapacity": 0, + "maximumOverCapacity": 0 + } +} +``` + +In the app definition above: + +- `containerPath` specifies where the volume is mounted inside the container. See [the REX-Ray documentation on data directories](https://rexray.readthedocs.org/en/v0.3.2/user-guide/config/#data-directories) for more information. + +- The `external.driver["dvdi/driver"]` option specifies which Docker volume driver to use for storage. If you are running Marathon on DCOS, this value should likely be `rexray`. [Learn more about REX-Ray](https://rexray.readthedocs.org/en/v0.3.2/user-guide/schedulers/). + +- You can specify additional options with `container.volumes[x].external.options[optionName]`. The dvdi provider for Mesos containers uses `dvdcli`, which offers the options [documented here[(https://github.com/emccode/dvdcli#extra-options). The availability of any given option depends on your volume driver, however. + +- `name` is the name by which your volume driver looks up your volume. When your task is staged on an agent, the volume driver queries the storage service for a volume with this name. If one does not exist, it's created. Otherwise, the existing volume is re-used. **Note:** Implicit volume creation only works when using volumes with a Mesos container and requires that you set `volumes[x].external.size`. + +- Create multiple volumes by adding additional items in the `container.volumes` array. + +- Volume parameters cannot be changed after you create the application. + +- **Note:** Marathon will not launch apps with external volumes if `upgradeStrategy.minimusHealthCapacity` is less than 0.5, or if `upgradeStrategy.maximumOverCapacity` does not equal 0. + +### Using a Docker Container + +Below is a sample app definition that uses a Docker container and specifies an external volume: + +```json +{ + "id": "/test-docker", + "instances": 1, + "cpus": 0.1, + "mem": 32, + "cmd": "/usr/bin/tail -f /dev/null", + "container": { + "type": "DOCKER", + "docker": { + "image": "alpine:3.1", + "network": "HOST", + "forcePullImage": true + }, + "volumes": [ + { + "containerPath": "/data/test-rexray-volume", + "external": { + "name": "my-test-vol", + "provider": "dvdi", + "options": { "dvdi/driver": "rexray" } + }, + "mode": "RW" + } + ] + }, + "upgradeStrategy": { + "minimumHealthCapacity": 0, + "maximumOverCapacity": 0 + } +} +``` + +For more information, refer to the [REX-Ray documentation](https://rexray.readthedocs.org/en/v0.3.2/user-guide/schedulers/#docker-containerizer-with-marathon). + +## Potential Pitfalls + +- You can only assign one task per volume. Your storage provider may other particular limitations. + +- The volumes you create are not automatically cleaned up. If you you delete your cluster, go to your storage provider and delete the volumes you no longer need. If you using EBS, find them by searching by the `container.volumes.external.name` that you set in your Marathon app definition. This name corresponds to an EBS volume `Name` tag. + +- Volumes are not isolated from other clusters. Choose a unique volume name to avoid conflicts. + +- Docker apps do not support external volumes on DCOS installations running Docker older than 1.8. Currently, this means that DCOS Community Edition users cannot create Docker apps with external volumes. + +- If you are using Amazon's EBS, it is possible that clusters can be created in different availability zones (AZs). This means that if you create a cluster with an external volume in one AZ and destroy it, a new cluster may not have access to that external volume because it could be in a different AZ. + +- Launch time may increase for applications that create volumes implicitly. The amount of the increase depends on several factors +(including, but not limited to) the size and type of the volume. Your storage provider's method of handling volumes can also influence launch time for implicitly created volumes. + +- If tasks using external volumes are not working, or not working the way you expect, consult the agent or system logs to troubleshoot. If you are using REX-Ray on DCOS, you can also consult the system journal. + +For more information, see the [Apache Mesos documentation on persistent volumes](http://mesos.apache.org/documentation/latest/persistent-volume/). From c548994473215dfe5e82fcb595cbd12ff0efa3f2 Mon Sep 17 00:00:00 2001 From: Suzanne Scala Date: Fri, 8 Apr 2016 11:20:05 -0700 Subject: [PATCH 2/3] Update external-volumes.md --- docs/docs/external-volumes.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/docs/external-volumes.md b/docs/docs/external-volumes.md index 592369abe63..a8057079800 100644 --- a/docs/docs/external-volumes.md +++ b/docs/docs/external-volumes.md @@ -6,7 +6,7 @@ title: Stateful Applications Using External Persistent Volumes Marathon applications normally lose their state when they terminate and are relaunched. In some contexts, for instance, if your application uses MySQL, you’ll want your application to preserve its state. You can use an external storage service, such as Amazon's Elastic Block Store (EBS), to create a persistent volume that follows your application instance. @@ -15,7 +15,7 @@ Using an external storage service allows your apps to be more fault-tolerant. If # Specifying an External Volume -If you are running Marathon on DCOS, add the following to the `genconf/config.yml` file you use during DCOS installation. [Learn more](https://docs.mesosphere.com/concepts/installing/installing-enterprise-edition/configuration-parameters/). +If you are running Marathon on DCOS, add the following to the `genconf/config.yml` file you use during DCOS installation. [Learn more](https://docs.mesosphere.com/concepts/installing/installing-enterprise-edition/configuration-parameters/). If you'd like to test this functionality without DCOS, [start here](https://blog.emccode.com/2016/02/11/give-mesos-and-external-volumes-a-spin-with-playa-mesos/). - `rexray_config_method: file` @@ -25,7 +25,7 @@ If you are running Marathon on DCOS, add the following to the `genconf/config.ym Apps that use external volumes should only be scaled to a single instance. -If you scale your app down to 0 instances, the volume is unattached from the agent where it was mounted, but it is not deleted. If you scale your app up again, the data that had been associated with it will still be available. +If you scale your app down to 0 instances, the volume is detached from the agent where it was mounted, but it is not deleted. If you scale your app up again, the data that had been associated with it will still be available. ## Create an Application with External Volumes @@ -66,11 +66,11 @@ In the app definition above: - `containerPath` specifies where the volume is mounted inside the container. See [the REX-Ray documentation on data directories](https://rexray.readthedocs.org/en/v0.3.2/user-guide/config/#data-directories) for more information. -- The `external.driver["dvdi/driver"]` option specifies which Docker volume driver to use for storage. If you are running Marathon on DCOS, this value should likely be `rexray`. [Learn more about REX-Ray](https://rexray.readthedocs.org/en/v0.3.2/user-guide/schedulers/). +- `name` is the name by which your volume driver looks up your volume. When your task is staged on an agent, the volume driver queries the storage service for a volume with this name. If one does not exist, it's created. Otherwise, the existing volume is re-used. **Note:** Implicit volume creation only works when using volumes with a Mesos container and requires that you set `volumes[x].external.size`. -- You can specify additional options with `container.volumes[x].external.options[optionName]`. The dvdi provider for Mesos containers uses `dvdcli`, which offers the options [documented here[(https://github.com/emccode/dvdcli#extra-options). The availability of any given option depends on your volume driver, however. +- The `external.driver["dvdi/driver"]` option specifies which Docker volume driver to use for storage. If you are running Marathon on DCOS, this value should likely be `rexray`. [Learn more about REX-Ray](https://rexray.readthedocs.org/en/v0.3.2/user-guide/schedulers/). -- `name` is the name by which your volume driver looks up your volume. When your task is staged on an agent, the volume driver queries the storage service for a volume with this name. If one does not exist, it's created. Otherwise, the existing volume is re-used. **Note:** Implicit volume creation only works when using volumes with a Mesos container and requires that you set `volumes[x].external.size`. +- You can specify additional options with `container.volumes[x].external.options[optionName]`. The dvdi provider for Mesos containers uses `dvdcli`, which offers the options [documented here](https://github.com/emccode/dvdcli#extra-options). The availability of any given option depends on your volume driver, however. - Create multiple volumes by adding additional items in the `container.volumes` array. @@ -119,11 +119,11 @@ For more information, refer to the [REX-Ray documentation](https://rexray.readth ## Potential Pitfalls -- You can only assign one task per volume. Your storage provider may other particular limitations. +- You can only assign one task per volume. Your storage provider may have other particular limitations. -- The volumes you create are not automatically cleaned up. If you you delete your cluster, go to your storage provider and delete the volumes you no longer need. If you using EBS, find them by searching by the `container.volumes.external.name` that you set in your Marathon app definition. This name corresponds to an EBS volume `Name` tag. +- The volumes you create are not automatically cleaned up. If you delete your cluster, go to your storage provider and delete the volumes you no longer need. If you're using EBS, find them by searching by the `container.volumes.external.name` that you set in your Marathon app definition. This name corresponds to an EBS volume `Name` tag. -- Volumes are not isolated from other clusters. Choose a unique volume name to avoid conflicts. +- Volumes are namespaced by their storage provider. If you're using EBS, volumes created on the same AWS account share a namespace. Choose unique volume names to avoid conflicts. - Docker apps do not support external volumes on DCOS installations running Docker older than 1.8. Currently, this means that DCOS Community Edition users cannot create Docker apps with external volumes. From 599adf2c4230109217c96f4fa17958f395dc731f Mon Sep 17 00:00:00 2001 From: sascala Date: Mon, 11 Apr 2016 11:37:41 -0700 Subject: [PATCH 3/3] Final edits --- docs/docs/external-volumes.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/external-volumes.md b/docs/docs/external-volumes.md index a8057079800..d8f3b53a5f0 100644 --- a/docs/docs/external-volumes.md +++ b/docs/docs/external-volumes.md @@ -23,7 +23,7 @@ If you are running Marathon on DCOS, add the following to the `genconf/config.ym ## Scaling your App -Apps that use external volumes should only be scaled to a single instance. +Apps that use external volumes should only be scaled to a single instance because a volume can only attach to a single task at a time. This will likely change in a future release. If you scale your app down to 0 instances, the volume is detached from the agent where it was mounted, but it is not deleted. If you scale your app up again, the data that had been associated with it will still be available. @@ -132,6 +132,6 @@ For more information, refer to the [REX-Ray documentation](https://rexray.readth - Launch time may increase for applications that create volumes implicitly. The amount of the increase depends on several factors (including, but not limited to) the size and type of the volume. Your storage provider's method of handling volumes can also influence launch time for implicitly created volumes. -- If tasks using external volumes are not working, or not working the way you expect, consult the agent or system logs to troubleshoot. If you are using REX-Ray on DCOS, you can also consult the system journal. +- If tasks using external volumes are not working, or not working the way you expect, consult the agent or system logs to troubleshoot. If you are using REX-Ray on DCOS, you can also consult the systemd journal. For more information, see the [Apache Mesos documentation on persistent volumes](http://mesos.apache.org/documentation/latest/persistent-volume/).