drydock/docs/topology.rst

Authoring Site Topology

Drydock uses a YAML-formatted site topology definition to configure downstream drivers to provision baremetal nodes. This topology describes the networking configuration of a site as well as the set of node configurations that will be deployed. A node configuration consists of network attachment, network addressing, local storage, kernel selection and configuration and metadata.

The best source for a sample of the YAML schema for a topology is the unit test input source /tests/yaml_samples/fullsite.yaml in tests/yaml_samples/fullsite.yaml.

Defining Node Storage

Storage can be defined in the storage stanza of either a HostProfile or BaremetalNode document. The storage configuration can describe creation of partitions on physical disks, the assignment of physical disks and/or partitions to volume groups, and the creation of logical volumes. Drydock will make a best effort to parse out system-level storage such as the root filesystem or boot filesystem and take appropriate steps to configure them in the active node provisioning driver.

Example YAML schema of the storage stanza:

storage:
  physical_devices:
    sda:
      labels:
        bootdrive: true
      partitions:
        - name: 'root'
          size: '10g'
          bootable: true
          filesystem:
            mountpoint: '/'
            fstype: 'ext4'
            mount_options: 'defaults'
        - name: 'boot'
          size: '1g'
          filesystem:
            mountpoint: '/boot'
            fstype: 'ext4'
            mount_options: 'defaults'
    sdb:
      volume_group: 'log_vg'
  volume_groups:
    log_vg:
      logical_volumes:
        - name: 'log_lv'
          size: '500m'
          filesystem:
            mountpoint: '/var/log'
            fstype: 'xfs'
            mount_options: 'defaults'

Schema

The storage stanza can contain two top level keys: physical_devices and volume_groups. The latter is optional.

Physical Devices and Partitions

A physical device can either be carved up in partitions (including a single partition consuming the entire device) or added to a volume group as a physical volume. Each key in the physical_devices mapping represents a device on a node. The key should either be a device alias defined in the HardwareProfile or the name of the device published by the OS. The value of each key must be a mapping with the following keys

• `labels`: A mapping of key/value strings providing generic labels for the device

* `partitions`: A sequence of mappings listing the partitions to be created on the device. The mapping is described below. Incompatible with the volume_group specification. * `volume_group`: A volume group name to add the device to as a physical volume. Incompatible with the partitions specification.

Partition

A partition mapping describes a GPT partition on a physical disk. It can left as a raw block device or formatted and mounted as a filesystem

• `name`: Metadata describing the partition in the topology
• `size`: The size of the partition. See the Size Format section below
• `bootable`: Boolean whether this partition should be the bootable device
• `part_uuid`: A UUID4 formatted UUID to assign to the partition. If not specified one will be generated

• `filesystem`: A optional mapping describing how the partition should be formatted and mounted

  • `mountpoint`: Where the filesystem should be mounted. If not specified the partition will be left as a raw deice
  • `fstype`: The format of the filesyste. Defaults to ext4
  • `mount_options`: fstab style mount options. Default is 'defaults'
  • `fs_uuid`: A UUID4 formatted UUID to assign to the filesystem. If not specified one will be generated
  • `fs_label`: A filesystem label to assign to the filesystem. Optional.

Size Format

The size specification for a partition or logical volume is formed from three parts

* The first character can optionally be > indicating that the size specified is a minimum and the calculated size should be at least the minimum and should take the rest of the available space on the physical device or volume group. * The second part is the numeric portion and must be an integer * The third part is a label * m|M|mb|`MB`: Megabytes or 10^6 * the numeric * g|G|gb|`GB`: Gigabytes or 10^9 * the numeric * t|T|tb|`TB`: Terabytes or 10^12 * the numeric * `%`: The percentage of total device or volume group space

Volume Groups and Logical Volumes

Logical volumes can be used to create RAID-0 volumes spanning multiple physical disks or partitions. Each key in the volume_groups mapping is a name assigned to a volume group. This name must be specified as the volume_group attribute on one or more physical devices or partitions, or the configuration is invalid. Each mapping value is another mapping describing the volume group.

• `vg_uuid`: A UUID4 format uuid applied to the volume group. If not specified, one is generated
• `logical_volumes`: A sequence of mappings listing the logical volumes to be created in the volume group

Logical Volume

A logical volume is a RAID-0 volume. Using logical volumes for / and /boot is supported

• `name`: Required field. Used as the logical volume name.
• `size`: The logical volume size. See Size Format above for details.
• `lv_uuid`: A UUID4 format uuid applied to the logical volume: If not specified, one is generated

* `filesystem`: A mapping specifying how the logical volume should be formatted and mounted. See the Partition section above for filesystem details.