Home | Setup Guide | Deployment Guide | Advanced Features

PHP Developer WebRole Framework | Advanced Command-Line Parameters | X-Drives

Advanced Features: X-Drives


INTRODUCTION

This tool provides support for creating and mounting Windows Azure X-Drives, which provides a durable NTFS drive for your Cloud Applications. Download the following for a thorough overview of this service: Windows Azure Drive Whitepaper

The support for this feature is provide by a DLL within the Tool's resource directory, \res\tool\WebRole.dll. It is packaged along with the WebRole sources.

When the package is deployed, at the initial start, WebRole.dll is addressed by the Cloud (or Dev Fabric) to initiate any preliminary tasks before the web application is started. This includes mounting X-Drives. To define mounting X-Drives requires configuring ServiceConfiguration.cscfg and ServiceDefinition.csdef files, both also within \res\tool\ directory. By default, these files have not been configured mounting X-Drives.

If you want X-Drives support, then there are three required configurations to be performed within ServiceConfiguration.cscfg and ServiceDefinition.csdef files.

DEFINING LOCALSTORAGE FOR X-DRIVES

In a new or existing cloud service, make sure you have a LocalStorage definition in ServiceDefinition.csdef. This local storage will be used by the Windows Azure Drive API to cache virtual hard disks on the virtual machine that is running, enabling faster access times. Below is an example configuration of ServiceDefinition.csdef.

For X-Drives, you only provide one reference to LocalStorage in order to define the read cache for all subsequently mounted drives associated with the role instance.

<ServiceDefinition >
    <WebRole name="WebRole">
 
        <ConfigurationSettings>
        </ConfigurationSettings>
        
        <LocalResources>
            <LocalStorage name="MyXDrivesLocalCache"
                          cleanOnRoleRecycle="false"
                          sizeInMB="1000" />
        </LocalResources>
    </WebRole>
</ServiceDefinition>


DEFINING X-DRIVES

For defining configurations of X-Drives, ServiceDefinition.csdef file includes two new configuration setting definitions.
  • XDrives - A listing of all mounted X-Drives to be associated with this role instance.
  • XDrivesLocalCache - Name of the LocalStorage that will be providing read cache for these mounted X-Drives.

<ServiceDefinition >
    <WebRole name="WebRole">
        <ConfigurationSettings>
 
            <!-- Windows Azure X-Drive Configuration Settings -->
            <Setting name="XDrives" />
            <Setting name="XDrivesLocalCache" />
                        
        </ConfigurationSettings>

        <LocalResources>
        </LocalResources>
    </WebRole>
</ServiceDefinition>


As an example, ServiceConfiguration.cscfg file is assigned values as shown below.

    <!-- Windows Azure X-Drive Configuration Settings -->
    <Setting name="XDrives" value="
    [xdrive_label=xDriveA,blob_container=MyDrives,page_blob_vhd=myDriveA];
    [xdrive_label=xDriveB,blob_container=MyDrives,page_blob_vhd=myDriveB,xdrive_sizeMB=40,mount_cache_sizeMB=10,create=Yes];
    [xdrive_label=xDriveC,blob_container=MyDrives,page_blob_vhd=myDriveC,mount_cache_sizeMB=20,access_mode=readonly];
    "
    />
    
    <Setting name="XDrivesLocalCache" value="MyXDrivesLocalCache" />


Setting: XDrivesLocalCache

When defining configurations for X-Drives, a LocalStorage must be defined within ServiceDefinition.csdef, and this LocalStorage name must be provided as a value to setting XDrivesLocalCache.

When WebRole.dll starts, it use the name of this LocalStorage to initialize the read cache for any subsequently mounted X-Drives associated with the role instance.

Setting: XDrives

Referring to above ServiceConfiguration.cscfg, three X-Drives are defined for mounting to this role instance. Their configurations are defined as follows:
  • xDriveA - X-Drive with Page Blob path of MyDrives/xDriveA, and Mount with no read cache.
  • xDriveB - X-Drive with Page Blob path of MyDrives/xDriveB, Drive size 40 MB, and Mount with Read Cache size 10 MB, and Create if Not Exists.
  • xDriveC - X-Drive with Page Blob path of MyDrives/xDriveC, Mount with Read Cache size 20 MB, and force to be ReadOnly.

Notice that the value is semi-colon delimited string, and each value is a X-Drive configuration request.

"[X-Drive Config];[X-Drive Config];[X-Drive Config];..."

Each X-Drive configuration request is a bracked set of comma delimited configuration settings, and each setting is a key value pair.

[key=value,key=value,key=value,...]

X-DRIVE CONFIGURATION LEGEND

This a legend of all the available keys and their expected values that can be used to define an X-Drive configuration request.

xdrive_label
Required: Friendly Label to Identify X-Drive configuration with X-Drive's letter assigned after mounting.
blob_container
Required: Blob Container name: 3 through 63 lower-case characters long
pageblobvhd
Required: Page Blob name: 1 to 1024 any combination of characters long
xdrive_sizeMB
Required if Creating X-Drive: X-Drive Size: Integer from 16 to 1000000
mountcachesizeMB
Optional: Mount Read Cache Size: Integer from 0 to xdrive_sizeMB, Default 0
create
Optional: Create X-Drive if it does not exist: Yes|No, Default No
access_mode
Optional: Forces X-Drive to mount a specific access mode versus getting available access mode. Values: none|write|readonly. Default: none
X-Drive Configuration Examples
To illustrate how this tool services X-Drives, it will be presented by an assortment of X-Drive configurations.

xdrive_label=MyDriveB,blob_container=mydrives,page_blob_vhd=MyDriveB.vhd
X-Drive expects to mount upon an existing page blob path mydrives/MyDriveB, and it will succeed mounting if it exists.

By not providing mountcachesizeMB value, thereby set mount for unbuffered access to the drive.

If this page blob exists and is not mounted by another role instance, then the X-Drive will have write access, else read-only.

xdrive_label=MyDriveB,blob_container=mydrives,page_blob_vhd=MyDriveB.vhd,xdrive_sizeMB=10,create=Yes
X-Drive expects to mount upon a page blob path mydrives/MyDriveB, and if it does not exist then it will be created before mounting.

When requesting to create an page blob to be associated with X-Drive, key xdrive_sizeMB is required.

The size of the X-Drive to create is 10 MBs. The minimum size permitted is 16 MB.

If this page blob exists and is not mounted by another role instance, then the X-Drive will have write access, else read-only.

If this page blob does not exist, then the X-Drive will create this page blob and have write access.

xdrive_label=MyDriveB,blob_container=mydrives,page_blob_vhd=MyDriveB.vhd,mount_cache_sizeMB=10,readonly=Yes
X-Drive expects to mount upon an existing page blob path mydrives/MyDriveB, and it will succeed mounting if it exists.

If this page blob exists, then the X-Drive will have read-only access, regardless if it is mounted by another role instance or not.

The size of the read cache for this mounted X-Drive is 10 MBs.

Using Mounted X-Drives in PHP Coding
At the beginning of deployment of a WebRole that is configured to X-Drives, the WebRole.dll reads ServiceConfiguration.cscfg, and attempts mounting X-Drives based upon configuration requests.

All successfully mounted X-Drive are entered into an enviroment variable named X_DRIVES.

Upon start up of PHP web application, environment variable is available as follows:

$sXDrives=@getenv("X_DRIVES");
Enviroment variable named X_DRIVES contents would contain semi-colon delimited values, each value representing a successful mounting result.

Mount;Mount;...
Each Mount result would be a bracked with comma delimited values:

xdrive_label=drive_letter,drive_access_mode
xdrive_label
This is the friendly label that was provide to an X-Drive configuration within setting XDrives.
drive_letter
This is the assigned drive letter after mounting to xdrivelabel's page blob VHD path: blobcontainer/pageblobvhd
driveaccessmode
This is the available access mode that could be achieved for a successful mounting. Value are either:
w - writable
r - readonly
Example X-Drive Mounting and X_DRIVES Results
For example, ServiceConfiguration.cscfg for setting XDrives is as follows, two XDrives configurations labeled MyDriveB and MyDriveC:

xdrive_label=MyDriveB,blob_container=mydrives,page_blob_vhd=MyDriveB.vhd,xdrive_sizeMB=40,create=Yes; xdrive_label=MyDriveC,blob_container=mydrives,page_blob_vhd=MyDriveC.vhd,xdrive_sizeMB=40,mount_cache_sizeMB=20,create=Yes;
First X-Drives Mounting Attempt by Service Name "Foo"
For the second deployment, assume service name "Fool", within a shared LocalStorage named by setting XDrivesLocalCache, and mounting for both X-Drive configurations are successful, then the value for the enviroment variable X_DRIVES would be for example set as follows:

MyDriveB=a,w;MyDriveC=b,w
Explanation of what has occurred is that neither of requested page blob VHD paths existed (mydrives/MyDriveB.vhd and mydrives/MyDriveC.vhd), then both of these X-Drive configurations successfully created page blob VHD paths and mounted with writable access.

MyDriveB
Drive Letter: a
Access Mode: Writable (w)
MyDriveC
Drive Letter: b
Access Mode: Writable (w)
Second X-Drives Mounting Attempt by Service Name "Bar"
For the second deployment, assume service name "Bar", within the same shared LocalStorage named by setting XDrivesLocalCache and using the same XDrives configuration, and mounting for both X-Drive configurations are successful, then the value for the enviroment variable X_DRIVES would be for example set as follows:

MyDriveB=f,r;MyDriveC=g,r
Explanation of what has occurred is that both of the requested page blob VHD paths existed (mydrives/MyDriveB.vhd and mydrives/MyDriveC.vhd) and were both mounted in writable modes, then both of these X-Drive configurations successfully created snapshots of page blob VHD paths and mounted with readonly access.

MyDriveB
Drive Letter: f
Access Mode: Readonly (r)
MyDriveC
Drive Letter: g
Access Mode: Readonly (r)

Last edited Apr 5, 2010 at 11:47 PM by jeff00seattle, version 3

Comments

No comments yet.