<commit_before>---
post_title: Local Persistent Volumes
menu_order: 10
---

**Note:** Local persistent volume functionality is considered experimental: use this feature at your own risk. We might add, change, or delete any functionality described in this document.

When you specify a local volume or volumes, tasks and their associated data are "pinned" to the node they are first launched on and will be relaunched on that node if they terminate. The resources the application requires are also reserved. Marathon will implicitly reserve an appropriate amount of disk space (as declared in the volume via `persistent.size`) in addition to the sandbox `disk` size you specify as part of your application definition.

## Benefits of using local persistent volumes

- All resources needed to run tasks of your stateful service are dynamically reserved, thus ensuring the ability to relaunch the task on the same node using the same volume when needed.
- You don't need constraints to pin a task to a particular agent where its data resides
- You can still use constraints to specify distribution logic
- Marathon lets you locate and destroy an unused persistent volume if you don't need it anymore

# Create an application with local persistent volumes

## Prerequisites

See the [DC/OS system requirements](/docs/1.7/administration/installing/custom/system-requirements/).

## Configuration options

Configure a persistent volume with the following options:

```json
{
  "containerPath": "data",
  "mode": "RW",
  "persistent": {
    "size": 10
  }
}
```

- `containerPath`: The path where your application will read and write data. This must be a single-level path relative to the container; it cannot contain a forward slash (`/`). (`"data"`, but not `"/data"`, `"/var/data"` or `"var/data"`). If your application requires absolute nested paths, [use this configuration](#nested-paths).
- `mode`: The access mode of the volume. Currently, `"RW"` is the only possible value and will let your application read from and write to the volume.
- `persistent.size`: The size of the persistent volume in MiBs.

You also need to set the `residency` node in order to tell Marathon to setup a stateful application. Currently, the only valid option for this is:

```json
"residency": {
  "taskLostBehavior": "WAIT_FOREVER"
}
```

<a name="nested-paths"></a>
### Specifing an absolute nested container path

The value of `containerPath` must be relative to allow you to dynamically add a local persistent volume to a running container and to ensure consistency across operating systems. However, your application may require an absolute or absolute nested container path.

If your application does require an absolute or absolute nested `containerPath`, configure two volumes. The first volume has the absolute container path you need and does not have the `persistent` parameter. The `hostPath` parameter will match the relative `containerPath` value for the second volume.

```json
{
  "containerPath": "/var/lib/data",
  "hostPath": "mydata",
  "mode": "RW"
}
```

The second volume is a persistent volume with a `containerPath` that matches the `hostPath` of the first volume.<commit_msg>Addressed Jie's comments<commit_after>---
post_title: Local Persistent Volumes
menu_order: 10
---

**Note:** Local persistent volume functionality is considered experimental: use this feature at your own risk. We might add, change, or delete any functionality described in this document.

When you specify a local volume or volumes, tasks and their associated data are "pinned" to the node they are first launched on and will be relaunched on that node if they terminate. The resources the application requires are also reserved. Marathon will implicitly reserve an appropriate amount of disk space (as declared in the volume via `persistent.size`) in addition to the sandbox `disk` size you specify as part of your application definition.

## Benefits of using local persistent volumes

- All resources needed to run tasks of your stateful service are dynamically reserved, thus ensuring the ability to relaunch the task on the same node using the same volume when needed.
- You don't need constraints to pin a task to a particular agent where its data resides
- You can still use constraints to specify distribution logic
- Marathon lets you locate and destroy an unused persistent volume if you don't need it anymore

# Create an application with local persistent volumes

## Prerequisites

See the [DC/OS system requirements](/docs/1.7/administration/installing/custom/system-requirements/).

## Configuration options

Configure a persistent volume with the following options:

```json
{
  "containerPath": "data",
  "mode": "RW",
  "persistent": {
    "size": 10
  }
}
```

- `containerPath`: The path where your application will read and write data. This must be a single-level path relative to the container; it cannot contain a forward slash (`/`). (`"data"`, but not `"/data"`, `"/var/data"` or `"var/data"`). If your application requires an absolute path, or a relative path with slashes, [use this configuration](#abs-paths).
- `mode`: The access mode of the volume. Currently, `"RW"` is the only possible value and will let your application read from and write to the volume.
- `persistent.size`: The size of the persistent volume in MiBs.

You also need to set the `residency` node in order to tell Marathon to setup a stateful application. Currently, the only valid option for this is:

```json
"residency": {
  "taskLostBehavior": "WAIT_FOREVER"
}
```

<a name="abs-paths"></a>
### Specifing an unsupported container path

The value of `containerPath` must be relative to allow you to dynamically add a local persistent volume to a running container and to ensure consistency across operating systems. However, your application may require an absolute or container path, or a relative one with slashes.

If your application does require an unsupported `containerPath`, configure two volumes. The first volume has the absolute container path you need and does not have the `persistent` parameter. The `hostPath` parameter will match the relative `containerPath` value for the second volume.

```json
{
  "containerPath": "/var/lib/data",
  "hostPath": "mydata",
  "mode": "RW"
}
```

The second volume is a persistent volume with a `containerPath` that matches the `hostPath` of the first volume.
{'fraction_non_alphanumeric': 0.07526208731028008, 'fraction_numerical': 0.0018776404318572994, 'mean_word_length': 4.641659311562224, 'pattern_counts': {'":': 18, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6423448', 'n_tokens_mistral': 1608, 'n_tokens_neox': 1532, 'n_words': 893}