Initial cut at disk partition support.

1 files changed, 178 insertions, 0 deletions

diff --git a/doc/examples/cloud-config-disk-setup.txt b/doc/examples/cloud-config-disk-setup.txt
new file mode 100644
index 00000000..518936d1
--- /dev/null
+++ b/doc/examples/cloud-config-disk-setup.txt
@@ -0,0 +1,178 @@
+Cloud-init supports the creation of simple partition tables and filesystems
+on devices.
+
+default disk definitions
+------------------------
+
+ disk_setup:
+    ephmeral0:
+        type: 'mbr'
+        layout: True
+        overwrite: False
+ fs_setup:
+    ephemeral0:
+        filesystem: 'ext3'
+        device: 'ephemeral0'
+        partition: 'auto'
+
+The default definition is used to make sure that the ephemeral storage is
+setup properly.
+
+"disk_setup": disk parititioning
+--------------------------------
+
+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 subsiquent 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:
+    ephemeral0:
+        filesystem: 'ext3'
+        device: 'ephemeral0'
+        partition: 'auto'
+    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>:
+            filesystem: <FS_TYPE>
+            device: <DEVICE>
+            partition: <PART_VALUE>
+            overwrite: <OVERWRITE>
+
+Where:
+    <LABEL>: The file system label to be 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.
+
+        "force": Recreate the file system, even it already exists
+
+
+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.
+
+    For 'ephemeralX' or 'swap' labeled filesystems, the operation will be a
+    no-op if a file system of the same type is present, regardless of the label.
+    This is to accommodate Clouds like EC2 that present a blank file system with
+    out a label.