Cloud-init supports the creation of simple partition tables and file systems
on devices.

Default disk definitions for AWS
--------------------------------
(Not implemented yet, but provided for future documentation)

 disk_setup:
    ephmeral0:
        type: 'mbr'
        layout: True
        overwrite: False

 fs_setup:
    - label: None,
      filesystem: ext3
      device: ephemeral0
      partition: auto

Default disk definitions for Windows Azure
------------------------------------------

device_aliases: {'ephemeral0': '/dev/sdb'}
disk_setup:
    ephemeral0:
         type: mbr
         layout: True
         overwrite: False

fs_setup:
    - label: ephemeral0
      filesystem: ext4
      device: ephemeral0
      partition: auto


Default disk definitions for SmartOS
------------------------------------

device_aliases: {'ephemeral0': '/dev/sdb'}
disk_setup:
    ephemeral0:
         type: mbr
         layout: False
         overwrite: False

fs_setup:
    - label: ephemeral0
      filesystem: ext3
      device: ephemeral0
      partition: auto

Cavaut for SmartOS: if ephemeral disk is not defined, then the disk will
    not be automatically added to the mounts.


The default definition is used to make sure that the ephemeral storage is
setup properly.

"disk_setup": disk partitioning
--------------------------------

The disk_setup directive instructs Cloud-init to partition a disk. The format is:

 disk_setup:
    ephmeral0:
        type: 'mbr'
        layout: 'auto'
    /dev/xvdh:
        type: 'mbr'
        layout:
            - 33
            - [33, 82]
            - 33
        overwrite: True

The format is a list of dicts of dicts. The first value is the name of the
device and the subsequent values define how to create and layout the partition.

The general format is:
    disk_setup:
        <DEVICE>:
            type: 'mbr'
            layout: <LAYOUT|BOOL>
            overwrite: <BOOL>

Where:
    <DEVICE>: The name of the device. 'ephemeralX' and 'swap' are special
                values which are specific to the cloud. For these devices
                Cloud-init will look up what the real devices is and then
                use it.

                For other devices, the kernel device name is used. At this
                time only simply kernel devices are supported, meaning
                that device mapper and other targets may not work.

                Note: At this time, there is no handling or setup of
                device mapper targets.

    type=<TYPE>: Currently the following are supported:
                    'mbr': default and setups a MS-DOS partition table

                Note: At this time only 'mbr' partition tables are allowed.
                    It is anticipated in the future that we'll have GPT as
                    option in the future, or even "RAID" to create a mdadm
                    RAID.

    layout={...}: The device layout. This is a list of values, with the
                percentage of disk that partition will take.
                Valid options are:
                    [<SIZE>, [<SIZE>, <PART_TYPE]]

                Where <SIZE> is the _percentage_ of the disk to use, while
                <PART_TYPE> is the numerical value of the partition type.

                The following setups two partitions, with the first
                partition having a swap label, taking 1/3 of the disk space
                and the remainder being used as the second partition.
                    /dev/xvdh':
                        type: 'mbr'
                        layout:
                            - [33,82]
                            - 66
                        overwrite: True

                When layout is "true" it means single partition the entire
                device.

                When layout is "false" it means don't partition or ignore
                existing partitioning.

                If layout is set to "true" and overwrite is set to "false",
                it will skip partitioning the device without a failure.

    overwrite=<BOOL>: This describes whether to ride with saftey's on and
                everything holstered.

                'false' is the default, which means that:
                    1. The device will be checked for a partition table
                    2. The device will be checked for a file system
                    3. If either a partition of file system is found, then
                        the operation will be _skipped_.

                'true' is cowboy mode. There are no checks and things are
                    done blindly. USE with caution, you can do things you
                    really, really don't want to do.


fs_setup: Setup the file system
-------------------------------

fs_setup describes the how the file systems are supposed to look.

 fs_setup:
    - label: ephemeral0
      filesystem: 'ext3'
      device: 'ephemeral0'
      partition: 'auto'
    - label:  mylabl2
      filesystem: 'ext4'
      device: '/dev/xvda1'
    - special:
      cmd: mkfs -t %(FILESYSTEM)s -L %(LABEL)s %(DEVICE)s
      filesystem: 'btrfs'
      device: '/dev/xvdh'

The general format is:
    fs_setup:
        - label: <LABEL>
          filesystem: <FS_TYPE>
          device: <DEVICE>
          partition: <PART_VALUE>
          overwrite: <OVERWRITE>

Where:
    <LABEL>: The file system label to be used. If set to None, no label is
        used.

    <FS_TYPE>: The file system type. It is assumed that the there
        will be a "mkfs.<FS_TYPE>" that behaves likes "mkfs". On a standard
        Ubuntu Cloud Image, this means that you have the option of ext{2,3,4},
        and vfat by default.

    <DEVICE>: The device name. Special names of 'ephemeralX' or 'swap'
        are allowed and the actual device is acquired from the cloud datasource.
        When using 'ephemeralX' (i.e. ephemeral0), make sure to leave the
        label as 'ephemeralX' otherwise there may be issues with the mounting
        of the ephemeral storage layer.

    <PART_VALUE>: The valid options are:
        "auto": auto is a special in the sense that you are telling cloud-init
            not to care whether there is a partition or not. Auto will put the
            first partition that does not contain a file system already. In
            the absence of a partition table, it will put it directly on the
            disk.

        "none": Put the partition directly on the disk.

        <NUM>: where NUM is the actual partition number.

    <OVERWRITE>: Defines whether or not to overwrite any existing
        filesystem.

        "true": Indiscriminately destroy any pre-existing file system. Use at
            your own peril.

        "false": If an existing file system exists, skip the creation.

Behavior Caveat: The default behavior is to _check_ if the file system exists.
    If a file system matches the specification, then the operation is a no-op.