From 1071b9940b4e114cd2eabf290b739f92fbab33de Mon Sep 17 00:00:00 2001 From: Wesley Wiedenmeier Date: Sun, 28 Aug 2016 17:56:17 -0500 Subject: Improve module documentation and doc cleanup. This adds lots of config module documentation in a standard format. It will greatly improve the content at readthedocs. Additionally: * Add a 'doc' env to tox.ini * Changed default highlight language for sphinx conf from python to yaml most examples in documentation are yaml configs * Updated datasource examples to highlight sh code properly --- cloudinit/config/cc_disk_setup.py | 92 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 91 insertions(+), 1 deletion(-) (limited to 'cloudinit/config/cc_disk_setup.py') diff --git a/cloudinit/config/cc_disk_setup.py b/cloudinit/config/cc_disk_setup.py index 39a23688..efa7a226 100644 --- a/cloudinit/config/cc_disk_setup.py +++ b/cloudinit/config/cc_disk_setup.py @@ -16,6 +16,96 @@ # # You should have received a copy of the GNU General Public License # along with this program. If not, see . + +""" +Disk Setup +---------- +**Summary:** configure partitions and filesystems + +This module is able to configure simple partition tables and filesystems. + +.. note:: + for more detail about configuration options for disk setup, see the disk + setup example + +For convenience, aliases can be specified for disks using the +``device_aliases`` config key, which takes a dictionary of alias: path +mappings. There are automatic aliases for ``swap`` and ``ephemeral``, where +``swap`` will always refer to the active swap partition and ``ephemeral`` +will refer to the block device of the ephemeral image. + +Disk partitioning is done using the ``disk_setup`` directive. This config +directive accepts a dictionary where each key is either a path to a block +device or an alias specified in ``device_aliases``, and each value is the +configuration options for the device. The ``table_type`` option specifies the +partition table type, either ``mbr`` or ``gpt``. The ``layout`` option +specifies how partitions on the device are to be arranged. If ``layout`` is set +to ``true``, a single partition using all the space on the device will be +created. If set to ``false``, no partitions will be created. Partitions can be +specified by providing a list to ``layout``, where each entry in the list is +either a size or a list containing a size and the numerical value for a +partition type. The size for partitions is specified in **percentage** of disk +space, not in bytes (e.g. a size of 33 would take up 1/3 of the disk space). +The ``overwrite`` option controls whether this module tries to be safe about +writing partition talbes or not. If ``overwrite: false`` is set, the device +will be checked for a partition table and for a file system and if either is +found, the operation will be skipped. If ``overwrite: true`` is set, no checks +will be performed. + +.. note:: + Using ``overwrite: true`` is dangerous and can lead to data loss, so double + check that the correct device has been specified if using this option. + +File system configuration is done using the ``fs_setup`` directive. This config +directive accepts a list of filesystem configs. The device to create the +filesystem on may be specified either as a path or as an alias in the format +``.`` where ```` denotes the partition number on the device. +The partition can also be specified by setting ``partition`` to the desired +partition number. The ``partition`` option may also be set to ``auto``, in +which this module will search for the existance of a filesystem matching the +``label``, ``type`` and ``device`` of the ``fs_setup`` entry and will skip +creating the filesystem if one is found. The ``partition`` option may also be +set to ``any``, in which case any file system that matches ``type`` and +``device`` will cause this module to skip filesystem creation for the +``fs_setup`` entry, regardless of ``label`` matching or not. To write a +filesystem directly to a device, use ``partition: none``. A label can be +specified for the filesystem using ``label``, and the filesystem type can be +specified using ``filesystem``. + +.. note:: + If specifying device using the ``.`` format, + the value of ``partition`` will be overwritten. + +.. note:: + Using ``overwrite: true`` for filesystems is dangerous and can lead to data + loss, so double check the entry in ``fs_setup``. + +**Internal name:** ``cc_disk_setup`` + +**Module frequency:** per instance + +**Supported distros:** all + +**Config keys**:: + + device_aliases: + : + disk_setup: + : + table_type: <'mbr'/'gpt'> + layout: + - [33,82] + - 66 + overwrite: + fs_setup: + - label: