From c60ed49e2e94937a94994f4a7acd3f70211be44f Mon Sep 17 00:00:00 2001 From: "Dustin J. Mitchell" Date: Fri, 21 Feb 2014 13:50:42 -0500 Subject: [PATCH] Update README formatting and content This orders the phase subdirectories by execution order, adds subheadings, and fixes some markdown formatting issues. This also replaces all double-spaces after full-stops with single spaces. Change-Id: I2d5526cbe4a902067fa9cad1456c35d13f81e183 --- README.md | 114 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 71 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index dc1c5b38..7bd7c550 100644 --- a/README.md +++ b/README.md @@ -142,7 +142,7 @@ element adds support for mellanox infiniband hardware to both the deploy ramdisk and the built images. Images must specify a base distribution image element. Currently base -distribution elements exist for fedora, rhel, and ubuntu. Other +distribution elements exist for fedora, rhel, and ubuntu. Other distributions may be added in future, the infrastructure deliberately makes few assumptions about the exact operating system in use. The base image has opensshd running (a new key generated on first boot) @@ -206,21 +206,59 @@ Conform to the following conventions: and not remounted into the filesystem image - if the mount point is needed again, your element will need to remount it at that point. +### Phase Subdirectories ### + Make as many of the following subdirectories as you need, depending on what -part of the process you need to customise: +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. * 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. - Runs outside the chroot on the host environment. - 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 $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 and 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 + (e.g. to make partitions). Runs after the target tree has been fully + populated but before the cleanup hook 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 @@ -229,45 +267,29 @@ part of the process you need to customise: 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 the chroot on the host - environment. + are removed here in the dpkg element. + * runs: outside chroot * inputs: $ARCH=i386|amd64|armhf $TARGET\_ROOT=/path/to/target/workarea -* block-device.d: customise the block device that the image will be made on - (e.g. to make partitions). Runs outside the chroot, after the target tree - has been fully populated but before the cleanup hook runs. +### Environment Variables ### - * outputs: $IMAGE\_BLOCK\_DEVICE={path} - * inputs: $IMAGE\_BLOCK\_DEVICE={path} $TARGET\_ROOT={path} +To set environment variables for other hooks, add a file to environment.d. +This directory contains bash script snippets that are sourced before running +scripts in each phase. -* 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. - * outputs: None - * inputs: $TMP\_HOOKS\_PATH +### Dependencies ### -* pre-install.d: Run code in the chroot before customisation or packages are - installed. A good place to add apt repositories. +Each element has a file named 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. -* 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. - -* 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 and clean the cache left by the package - manager to reduce the size of the image. - -* environment.d: Bash script snippets that are sourced before running scripts - in each phase. Use this to set an environment variable for other hooks. - -* 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. +### First-boot files ### * first-boot.d: **DEPRECATED** Runs inside the image before rc.local. Scripts from here are good for doing per-instance @@ -275,6 +297,8 @@ part of the process you need to customise: future release of diskimage-builder. The os-refresh-config element in tripleo-image-elements is recommended as a replacement.** +### 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 @@ -304,13 +328,16 @@ possible approach to this would be to label elements as either a "driver", - Driver-specific elements should only contain the necessary bits for that driver: + elements/ driver-mellanox/ init - modprobe line install.d/ 10-mlx - package installation -- An element that installs and configures Nova might be a bit more complex: +- An element that installs and configures Nova might be a bit more complex, + containing several scripts across several phases: + elements/ service-nova/ source-repository-nova - register a source repository @@ -329,6 +356,7 @@ possible approach to this would be to label elements as either a "driver", set of elements which express a distinct configuration of the same software components. For example, if one were to bake a region-specific SSL cert into the images deployed in each region, one might express it like this: + elements/ config-az1/ first-boot.d/ @@ -340,20 +368,20 @@ possible approach to this would be to label elements as either a "driver", In this way, depending on the hardware and in which availability zone it is to be deployed, an image would be composed of: - zero or more driver-elements - one or more service-elements - zero or more config-elements + * zero or more driver-elements + * one or more service-elements + * zero or more config-elements It should be noted that this is merely a naming convention to assist in managing elements. Diskimage-builder is not, and should not be, functionally dependent upon specific element names. -- diskimage-builder has the ability to retrieve source code for an element and - place it into a directory on the target image during the extra-data phase. The - default location/branch can then be overridden by the process running - diskimage-builder, making it possible to use the same element to track more - then one branch of a git repository or to get source for a local cache. See - elements/source-repositories/README.md for more information. +diskimage-builder has the ability to retrieve source code for an element and +place it into a directory on the target image during the extra-data phase. The +default location/branch can then be overridden by the process running +diskimage-builder, making it possible to use the same element to track more +then one branch of a git repository or to get source for a local cache. See +elements/source-repositories/README.md for more information. Debugging elements ------------------