Developing Elements¶

Phase Subdirectories¶

Make as many of the following subdirectories as you need, depending on what part of the process you need to customise. The subdirectories are executed in the order given here. Scripts within the subdirectories should be named with a two-digit numeric prefix, and are executed in numeric order.

Only files which are marked executable (+x) will be run, so other files can be stored in these directories if needed. As a convention, we try to only store executable scripts in the phase subdirectories and store data files elsewhere in the element.

The phases are:

1. root.d
2. extra-data.d
3. pre-install.d
4. install.d
5. post-install.d
6. block-device.d
7. finalise.d
8. cleanup.d

root.d

Create or adapt the initial root filesystem content. This is where alternative distribution support is added, or customisations such as building on an existing image.

Only one element can use this at a time unless particular care is taken not to blindly overwrite but instead to adapt the context extracted by other elements.

• runs: outside chroot
• inputs:
  • $ARCH=i386|amd64|armhf|arm64
  • $TARGET_ROOT=/path/to/target/workarea

extra-data.d

Pull in extra data from the host environment that hooks may need during image creation. This should copy any data (such as SSH keys, http proxy settings and the like) somewhere under $TMP_HOOKS_PATH.

• runs: outside chroot
• inputs: $TMP_HOOKS_PATH
• outputs: None

pre-install.d

Run code in the chroot before customisation or packages are installed. A good place to add apt repositories.

• runs: in chroot

install.d

Runs after pre-install.d in the chroot. This is a good place to install packages, chain into configuration management tools or do other image specific operations.

• runs: in chroot

post-install.d

Run code in the chroot. This is a good place to perform tasks you want to handle after the OS/application install but before the first boot of the image. Some examples of use would be:

Run chkconfig to disable unneeded services

Clean the cache left by the package manager to reduce the size of the image.

• runs: in chroot

block-device.d

Customise the block device that the image will be made on (for example to make partitions). Runs after the target tree has been fully populated but before the cleanup.d phase runs.

• runs: outside chroot
• inputs:
  • $IMAGE_BLOCK_DEVICE={path}
  • $TARGET_ROOT={path}
• outputs: $IMAGE_BLOCK_DEVICE={path}

finalise.d

Perform final tuning of the root filesystem. Runs in a chroot after the root filesystem content has been copied into the mounted filesystem: this is an appropriate place to reset SELinux metadata, install grub bootloaders and so on.

Because this happens inside the final image, it is important to limit operations here to only those necessary to affect the filesystem metadata and image itself. For most operations, post-install.d is preferred.

• runs: in chroot

cleanup.d

Perform cleanup of the root filesystem content. For instance, temporary settings to use the image build environment HTTP proxy are removed here in the dpkg element.

• runs: outside chroot
• inputs:
  • $ARCH=i386|amd64|armhf|arm64
  • $TARGET_ROOT=/path/to/target/workarea

Other Subdirectories¶

Elements may have other subdirectories that are processed by specific elements rather than the diskimage-builder tools themselves.

One example of this is the bin directory. The rpm-distro, dpkg and opensuse elements install all files found in the bin directory into /usr/local/bin within the image as executable files.

Environment Variables¶

To set environment variables for other hooks, add a file to your element environment.d. This directory contains bash script snippets that are sourced before running scripts in each phase. Note that because environment includes are sourced together, they should not set global flags like set -x because they will affect all preceeding imports.

Dependencies¶

Each element can use the following files to define or affect dependencies:

element-deps

A plain text, newline separated list of elements which will be added to the list of elements built into the image at image creation time.

element-provides

A plain text, newline separated list of elements which are provided by this element. These elements will be excluded from elements built into the image at image creation time.

For example if element A depends on element B and element C includes element B in its element-provides file and A and C are included when building an image, then B is not used.

Operating system elements¶

Some elements define the base structure for an operating system – for example, the opensuse element builds a base openSUSE system. Such elements have more requirements than the other elements:

• they must have operating-system in their element-provides, so this indicates they are an “operating system”.
• they must export the DISTRO_NAME environment variable with the name of the distribution built, using an environment.d script. For example, the opensuse element exports DISTRO_NAME=opensuse.

Ramdisk Elements¶

Ramdisk elements support the following files in their element directories:

binary-deps.d

Text files listing executables required to be fed into the ramdisk. These need to be present in $PATH in the build chroot (i.e. need to be installed by your elements as described above).

init.d

POSIX shell script fragments that will be appended to the default script executed as the ramdisk is booted (/init).

ramdisk-install.d

Called to copy files into the ramdisk. The variable $TMP_MOUNT_PATH points to the root of the tree that will be packed into the ramdisk.

udev.d

udev rules files that will be copied into the ramdisk.

Element coding standard¶

• lines should not include trailing whitespace.
• there should be no hard tabs in the file.
• indents are 4 spaces, and all indentation should be some multiple of them.
• do and then keywords should be on the same line as the if, while or for conditions.

import os
import yaml

elements = yaml.load(os.getenv('IMAGE_ELEMENT_YAML'))
for element, path in elements:
   ...

# note eval to expand the result of the get function
eval declare -A image_elements=($(get_image_element_array))
for i in ${!image_elements[$i]}; do
  element=$i
  path=${image_elements[$i]}
done

tox -efunc

tox -efunc ironic-agent

# dib-lint: safe_sudo

# dib-lint: disable=safe_sudo