add support for partitioning and creating filesystems

If the disks that are attached on boot do not have a filesystem
on them, then this module is useful to set that up.

LP: #1218506

1 files changed, 210 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..db2c52a7
--- /dev/null
+++ b/doc/examples/cloud-config-disk-setup.txt
@@ -0,0 +1,210 @@
+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
+------------------------------------------
+(Not implemented yet due to conflict with WALinuxAgent in Ubuntu)
+
+disk_setup:
+    /dev/sdb:
+         type: mbr
+         layout: True
+         overwrite: False
+
+fs_setup:
+    - label: ephemeral0
+      filesystem: ext3
+      device: ephemeral0
+      partition: any
+
+
+Default disk definitions for SmartOS
+------------------------------------
+
+ephemeral_disk: /dev/vdb
+disk_setup:
+    /dev/vdb:
+         type: mbr
+         layout: True
+         overwrite: False
+
+fs_setup:
+    - label: ephemeral0
+      filesystem: ext3
+      device: /dev/vdb
+      partition: 1
+
+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.