Persistence Volume Mapping

Adding persistence volume is very much similar to adding a virtual hard drive to your machine instance. In Amazon EC2, an EBS storage device can be added as a persistence volume to the instance. For more information, see Attaching an Amazon EBS Volume to an Instance. Persistence volume capability comes handy when you want to store your content in a separate place and make the data available even after the instance is terminated or deleted. MySQL, MongoDB are examples where you may need this capability.

In most IaaSs such as EC2, one persistence volume can be attached to only one instance. Therefore if your deployment policy has maxInstance count more than 1, you might encounter problems when WSO2 Private PaaS tries to attach the volume to the second instance. Currently persistence volume mapping has been fully tested only in EC2 for WSO2 Private PaaS.

Adding the persistence volume in the cartridge definition

The persistence volume is an optional configuration that can be specified by the user, if the user wants additional volumes to store content. Add a configuration similar to the following in the cartridge definition.

 "persistence": {
        "isRequired": "true",
        "volume" : [
            {
            "device": "/dev/sdc",
            "mappingPath": "/home/ubuntu/sdc",
            "size": "10",
            "removeOnTermination": "false"
            }
         ]
     }

Mapping multiple persistence volumes

WSO2 Private PaaS provides the capability to specify multiple persistence volumes in the cartridge definition file as follows, in case you require more than one additional volume.

 "persistence": {
        "isRequired": "true",
        "volume" : [
            {
            "device": "/dev/sdc",
            "mappingPath": "/home/ubuntu/sdc",
            "size": "10",
            "removeOnTermination": "false"
            },
            {
            "device": "/dev/sdf",
            "mappingPath": "/home/ubuntu/sdf",
            "size": "20",
            "removeOnTermination": "false"
            }
        ]
     }

You should not specify the same mappingPath to multiple volumes. If done so, that mappingPath will be mapped to the volume defined last and it is unpredictable whether the other volumes will be mapped to a directory.

What happens behind the scene

When working with single tenant cartridges, persistence mapping will be enabled when the application is deployed and automatic subscription takes place. However, when working with multi-tenant cartridges, persistence mapping will be enabled during the tenant signup process.

Overall when persistence mapping is enabled WSO2 Private PaaS will:

Create the volumes.
Format and create a writable file system (ext3) .
Mount volumes to the directory specified as mappingPath.

The process of formatting and creating a file system takes place only once when persistence mapping is enabled for the very first time. When the volume is being attached to another instance, after the first instance is terminated, it will not need to create a file system since the file system already exists.

Verifying volume creation

Follow the instructions below to verify if the volumes have been created:

Log in to the instance created via ssh.

Execute the command: df -h
You will see an output as follows:

df -h
Filesystem      Size  Used Avail Use% Mounted on
/dev/xvdc        10G  7.1G   97G  3% /home/ubuntu/sdc
/dev/sda1       4000G  40G   320G  10% /home