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 IAASes 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 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.

Enabling persistence volume mapping capability

Follow the steps below to enable persistence volume mapping capability in WSO2 Private PaaS:

Step 1 - Adding the persistence volume in the Cartridge definition

The persistence volume is an optional configuration that is specified by the user, if the user wants additional volumes to store content. Add a configuration similar to the following in the Sample Cartridge Definition.

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

Step 2 - Specifying the persistence volumes in the subscription

In addition to defining the information on the persistence volume in the Cartridge definition as done in Step 1, it is also required to specify the information on the volumes at the time of subscribing as follows:

Using the CLI

Use the command below to define the details of the persistence volume that should be attached to a cartridge instance during the subscription via the CLI:

subscribe-cartridge <CARTRIDGE-TYPE> <CARTRIDGE-ALIAS> -dp <DEPLOYMENT-POLICY> -ap <AUTO-SCALING-POLICY> -pv <PERSISTENCE-VOLUME> -v <VOLUME-SIZE> -t <REMOVE-ON-TERMINATION>

For more information on how to subscribe to a cartridge with persistence mappings using the CLI, see subscribe-cartridge.

Using the UI

If you are subscribing using the Private PaaS UI, tick Require Persistence Storage and provide the required details as follows:

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"
            }
        ]
     }

Currently the size parameter is a mandatory requirement at the time of subscription. But ideally the size specified in the Cartridge definition should be considered as the default, if the size is not specified at the time of subscription.

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

If you subscribe with persistence mappings, Private PaaS will:

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

The formatting and creating a file system happens at the first time only. Next time when the volume is being attached to another instance after first instance is terminated, it is no longer needed to create a file system since file system is already there.

How to verify if the volumes 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