Storage specification

This section describes the FCOS Configuration (FCC) YAML format for defining the desired state of storage associated with a FCOS instance. See also Configuring Storage which contains examples for customizing the default storage layout.

The storage block contains a list of objects, which can be of the following type:

  • disks: List of disks

  • raid: List of RAID arrays

  • filesystems: List of filesystems

  • files: List of files to be written

  • directories: List of directories to be created

  • links: List of links to be created

Disks

Every entry under the disks node must correspond to a unique device. For each device, specify a list of GPT partitions. Unless specified as optional, all nodes are mandatory. The contents of disks is as follows:

  • device (string): Absolute path of the disk device. Disks are typically referenced by the /dev/disk/by-* symlinks. Avoid specifying the disk device /dev/sdx directly: when new disks are inserted, the system might re-enumerate devices at boot. This could change the order of the /dev/sdx devices. The /dev/disk/by-* symlinks always point to the right devices.

  • wipe_table (boolean, optional): When true, Ignition erases the partition table before proceeding. Otherwise, the table’s existing partition entries are left alone.

  • partitions (object list, optional): List of partitions to be written to the partition table of the device. Each partition occupies a slot in the table. You can either specify the slot directly with the number node, or specify number: 0 and supply a unique label.

    • label (string, optional): GPT PARTLABEL for the partition.

    • number (integer, optional): Slot number occupied by the partition, starting at 1. To use the next available slot, specify 0. In this case, you should also specify a unique label.

    • size_mib (integer, optional): Size of the partition in mebibytes. If 0, the partition is sized as large as possible. Note: 1 mebibytes = 1024 * 1024 bytes.

    • start_mib (integer, optional): Start position of the partition from the beginning of the disk, in mebibytes. If 0, the partition will be placed at the start of the largest block available.

    • type_guid (string, optional): Partition type GUID. If omitted, it defaults to 0FC63DAF-8483-4772-8E79-3D69D8477DE4, the Linux native file system GUID. The ultimate reference list for the type GUIDs is currently the parttypes.cc file in the GPT fdisk source code. A more readable list can be found in the GUID Partition Table article on Wikipedia.

    • guid (string, optional, must be unique): GUID of the partition. You can omit this when creating new partitions.

    • wipe_partition_entry (boolean, optional)

      • true: Ignition erases any existing partition that does not match this entry.

      • false: Ignition leaves the partition unchanged, which will fail.

    • should_exist (boolean, optional). Defaults to true.

      • true: If true and if it does not already exist, the partition with the specified number is created. If the partition exists, and wipe_partition_entry is false, then number must be specified as a non-zero integer, and label, start_mib, size_mib, guid and type_guid must all be omitted.

      • false: If false and the partition exists, Ignition looks at the wipe_partition_entry value and deletes the partition if true, or fails if false.

Example for defining a disk containing some partitions
variant: fcos
version: 1.3.0
storage:
  disks:
    -
      # Mandatory. We use the World-Wide Number ID of the drive to ensure
      # uniqueness.
      device: /dev/disk/by-id/wwn-0x50014e2eb507fcdf
      # This ensures that the partition table is re-created, along with all
      # the partitions.
      wipe_table: true
      partitions:
        # The first partition (slot number 1) is 32 GiB and starts at the
        # beginning of the device. Its type_guid identifies it as a Linux
        # swap partition.
        - label: part1
          number: 1
          size_mib: 32768
          start_mib: 0
          type_guid: 0657fd6d-a4ab-43c4-84e5-0933c84b4f4f
        # The second partition (implicit slot number 2) will be placed after
        # partition 1 and will occupy the rest of the available space.
        # Since type_guid is not specified, it will be a Linux native
        # partition.
        - label: part2
          number: 0

Raid

Every entry under the raid node must correspond to a unique RAID array. The resulting configuration is implemented as an mdadm "software" RAID. The contents of raid is as follows. Unless specified as optional, all nodes are mandatory.

  • name (string): Name of the resulting md device.

  • level (string): Redundancy level of the array. See the supported levels in the Fedora mdadm man page. Examples: linear, raid0, raid.

  • devices (list of strings): List of devices that should be part of the array, referenced by absolute path.

  • spares (optional, integer): Number of spares in the array, if applicable.

  • options (optional, list of strings): Additional options to be passed to mdadm.

File systems

Entries under the filesystems node list the file systems to be created and mounted. Each file system must have a unique device. The contents of filesystems is as follows. Unless specified as optional, all nodes are mandatory.

  • path (string): Mount point of of the filesystem while Ignition is running, relative to where the root filesystem will be mounted. This is not necessarily the same as where it should be mounted in the real root, but you should set it as such.

  • device (string): Absolute path of the device.

  • format (string): File system "format" (ie - file system type). Accepted values: ext4, btrfs, xfs, vfat, or swap.

  • wipe_filesystem (boolean, optional): If true, the device is wiped before the file system is created.

  • label (string, optional): Label of the file system.

  • uuid (string, optional): UUID of the file system.

  • options (list of strings, optional): Additional options to be passed to mkfs.

Example for defining a file system on a RAID storage device
variant: fcos
version: 1.3.0
storage:
  disks:
  # This defines two partitions, each on its own disk. The disks are
  # identified by their WWN.
  - device: /dev/disk/by-id/wwn-0x50014ee261e524e4
    wipe_table: true
    partitions:
    -
      # Each partition gets a human-readable label.
      label: "raid.1.1"
      # Each partition is placed at the beginning of the disk and is 64 GiB
      # long.
      number: 1
      size_mib: 65536
      start_mib: 0
  - device: /dev/disk/by-id/wwn-0x50014ee0b8442cd3
    wipe_table: true
    partitions:
    - label: "raid.1.2"
      number: 1
      size_mib: 65536
      start_mib: 0
  # We use the previously defined partitions as devices in a RAID1 md array.
  raid:
    - name: publicdata
      level: raid1
      devices:
      - /dev/disk/by-partlabel/raid.1.1
      - /dev/disk/by-partlabel/raid.1.2
  # The resulting md array is used to create an EXT4 file system.
  filesystems:
    - path: /var/publicdata
      device: /dev/md/publicdata
      format: ext4
      label: PUB

Files

The files node lets you define a list of files, identified by a unique path, that Ignition will create with the required contents and attributes as needed.

An empty file would not be very useful, so the files can be defined with a contents option to specify either a source from which the file will be copied, or inline data.

The contents of files is as follows. Unless specified as optional, all nodes are mandatory.

  • path (string, must be unique): Absolute path of the file to be created.

  • overwrite (boolean, optional): Defaults to false. If true, source must be specified, and any preexisting file of the specified path will be overwritten with the contents of source.

  • contents (object, optional): Specifies the contents of the file.

    • compression (string, optional): Type of compression of the source. Possible values are null or gzip. Defaults to null. Compression cannot be specified if source uses an s3 scheme.

    • source (string, optional): Mandatory if overwrite is true. Mutually exclusive with option inline. Specifies the URL of the source to be copied to the path. Supported schemes are http, https, tftp, s3, and data. If you use the http scheme, you should specify a verification option to ensure the remote contents have not changed. If source is omitted, Ignition checks if the file already exists:

      • File exists: Ignition does nothing.

      • File does not exist: Ignition creates an empty file.

    • inline (string, optional): Mutually exclusive with option source. Specifies a string to be written to the file.

    • verification (object, optional): Tells Ignition to verify the contents of the file. Currently, only one verification option has been implemented: hash.

      • hash (string, mandatory if verification is specified): Hash of the file contents, in the form <type>-<value>. The only supported type is sha512.

  • append (object list, optional): This node has the same options as source. It specifies contents to be appended to the (presumably existing) file.

    • compression: See contents.

    • source: See contents.

    • inline: See contents.

    • verification: See contents.

      • hash: See contents.

  • mode (integer, optional): Specifies the file’s permission or mode. If mode is not specified, Ignition checks to see if the file already exists:

    • File exists: Keep the existing file mode if overwrite is false and source is not specified. Otherwise, set mode to octal 0644.

    • File does not exist: mode defaults to octal 0644.

  • user (object, optional): Specifies the user ID of the file owner. Either an ID or name must be specified.

    • id (integer, optional): User ID of the owner.

    • name (string, optional): User name of the owner.

  • group (object, optional): Specifies the group of the file owner. Either an ID or name must be specified.

    • id (integer, optional): Group ID of the owner.

    • name (string, optional): Group name of the owner.

Directories

The directories node specifies a list of directories, identified by a unique path, that Ignition creates as needed.

The directories structure is similar to the files structure. Unless specified as optional, all nodes are mandatory.

  • path (string): See Files.

  • overwrite (boolean, optional): Defaults to false. If true, preexisting files or directories at the specified path are removed. If overwrite is false and a file system object already exists at the specified path, Ignition checks the type of the existing file system object:

    • Existing path is a directory: Ignition does nothing

    • Existing path is not a directory: Ignition fails.

  • mode (integer, optional): Specifies the directory’s permission or mode. If mode is not specified, Ignition checks to see if the directory already exists:

    • Directory exists: if overwrite is false, Ignition does nothing, otherwise the mode is set to octal 0755.

    • Directory does not exist: The mode is set to 0755.

  • user: Specifies the directory owner. See Files.

    • id: See Files

    • name: See Files

  • group: Specifies the directory group. See Files.

    • id: See Files

    • name: See Files

Links

The links node lets you specify links (hard or symbolic) to be created by Ignition as needed.

The contents of links is as follows. Unless specified as optional, all nodes are mandatory.

  • path (string, must be unique): Absolute path of the link to be created.

  • overwrite (boolean, optional): Defaults to false. If false and a link already exists at the specified path, Ignition sets only the owner and group.

  • user: Specifies the link owner. See Files.

    • id: See Files.

    • name: See Files.

  • group: Specifies the link group. See Files.

    • id: See Files.

    • name: See Files.

  • target (string): Target path of the link.

  • hard (boolean, optional): Defaults to false. If true, Ignition creates a hard link. If false, it creates a symbolic link

Example for defining files, directories and links
variant: fcos
version: 1.3.0
storage:
  # This creates a directory. Its mode is set to 0755 by default, that
  # is, readable and executable by all, and writable by the owner.
  directories:
  - path: /opt/tools
    overwrite: true
  files:
    -
      # Creates a file /var/helloworld containing a string defined in-line.
      path: /var/helloworld
      overwrite: true
      contents:
        inline: Hello, world!
      # Sets the file mode to 0644 (readable by all, also writable by the
      # owner).
      mode: 0644
      user:
        # The owner uid and group are defined by their numerical IDs.
        id: 500
      group:
        id: 500
    -
      # We need the nifty (and alas imaginary) transmogrifier tool.
      path: /opt/tools/transmogrifier
      overwrite: true
      # Deploys this tool by copying an executable from an https link. The
      # file is compressed with gzip.
      contents:
        source: https://mytools.example.com/path/to/archive.gzip
        compression: gzip
        verification:
          # The hash is sha512- followed by the 128 hex characters given by
          # the sha512sum command.
          hash: sha512-00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
      # Makes the tool file readable and executable by all.
      mode: 0555
  links:
    -
      # Creates a symlink to the tool location from /usr/local/bin. This is
      # useful to let local processes invoke this tool without altering
      # their PATH environment variable.
      path: /usr/local/bin/transmogrifier
      overwrite: true
      target: /opt/tools/transmogrifier
      hard: false