From f22a5a8b912332bc755b89150ff605df625dd472 Mon Sep 17 00:00:00 2001 From: Antoine Musso Date: Thu, 18 Jun 2015 11:24:13 +0200 Subject: [PATCH] doc: migrate from README.rst to Sphinx The README.rst has a lot of information that has been duplicated in the Sphinx maintained documentation (3600330). Remove dupes from README.rst Point to http://docs.openstack.org/developer/diskimage-builder/ Change summary: =====================+====================================== README.md | Sphinx document section | =====================+====================================== Installation | installation.rst ---------------------+-------------------------------------- Invocation | invocation.rst ---------------------+-------------------------------------- Requirements | installation.rst Speedups ---------------------+-------------------------------------- Caches/offline | caches.rst + changes from 849e9cb2 | fix some markup ---------------------+-------------------------------------- Install Types | install_types.rst ---------------------+-------------------------------------- Writing an element | developing_elements.rst + fe7823a2 | `Testing element` from b9b6640f | `3rd party elements' from f1e7bf3a ---------------------+-------------------------------------- Existing elements | elements.rst ---------------------+-------------------------------------- What tools are there | components.rst ---------------------+-------------------------------------- Design | design.rst ---------------------+-------------------------------------- Change-Id: I578daa8e3a8d876b3ee3c9a748d7c8aa2bf7a0b7 --- README.rst | 526 +------------------ doc/source/developer/caches.rst | 15 +- doc/source/developer/components.rst | 4 + doc/source/developer/developing_elements.rst | 19 +- 4 files changed, 33 insertions(+), 531 deletions(-) diff --git a/README.rst b/README.rst index 49a771108..379ca203b 100644 --- a/README.rst +++ b/README.rst @@ -15,531 +15,9 @@ The TripleO project also develops elements that can be used to deploy OpenStack itself. These live in the TripleO elements repository (https://git.openstack.org/cgit/openstack/tripleo-image-elements). -What tools are there? ---------------------- +Online documentation: -* disk-image-create [-a i386|amd64|armhf] -o filename {element} [{element} ...] - Create an image of element {element}, optionally mixing in other elements. - Element dependencies are automatically included. Support for other - architectures depends on your environment being able to run binaries of that - platform. For instance, to enable armhf on Ubuntu install the qemu-user-static - package. The default output format from disk-image-create is qcow2. To instead - output a tarball pass in "-t tar". This tarball could then be used as an image - for a linux container(see docs/docker.md). - -* ramdisk-image-create -o filename {element} [{element} ...] : Create a kernel+ - ramdisk pair for running maintenance on bare metal machines (deployment, - inventory, burnin etc). - - To generate kernel+ramdisk pair for use with nova-baremetal, use - ramdisk-image-create -o deploy.ramdisk deploy-baremetal - - To generate kernel+ramdisk pair for use with ironic, use - ramdisk-image-create -o deploy.ramdisk deploy-ironic - -* elements can be found in the top level elements directory. - -* element-info : Extract information about elements. - -* tests/run_functests.sh - This runs a set of functional tests for diskimage-builder. - -Why? ----- - -Automation: While users and operators can manually script or put together ram -disks and disk images, mature automation makes customisation and testing easier. - -Installation -============ - -* Clone the repository locally, then add bin to your path. - -* Make sure you have qemu-img (qemu-utils package on Ubuntu/Debian, - qemu on Fedora/RHEL/openSUSE) and kpartx installed. - -Invocation -========== - -The scripts can generally just be run. Options can be set on the command line -or by exporting variables to override those present in lib/img-defaults. -h to -get help. -The image building scripts expect to be able to invoke commands with sudo, so if you -want them to run non-interactively, you should either run them as root, with -sudo -E, or allow your build user to run any sudo command without password. - -Using the variable ELEMENTS\_PATH will allow to specify multiple elements locations. -It's a colon (:) separated path list, and it will work in a first path/element found, -first served approach. The included elements tree is used when no path is supplied, -and is added to the end of the path if a path is supplied. - -By default, the image building scripts will not overwrite existing disk images, -allowing you to compare the newly built image with the existing one. To change -that behaviour, set the variable OVERWRITE\_OLD\_IMAGE to any value that isn't -0. - -Requirements -============ - -If you have 4GB of available physical RAM\*, or more, diskimage-builder will -create a tmpfs mount to build the image in. This will improve image build time -by building in RAM. This can be disabled completely by passing --no-tmpfs to -disk-image-create. ramdisk-image-create builds a regular image and then within -that does ramdisk creation. If tmpfs is not used, you will need enough room in -/tmp to store two uncompressed cloud images. If you do have tmpfs, you will -still need /tmp space for one uncompressed cloud image and about 20% of that -for working files. - -\* As reported by /proc/meminfo MemTotal - -Caches and offline mode -======================= - -Since retrieving and transforming operating system image files, git -repositories, Python or Ruby packages, and so on can be a significant -overhead, we cache many of the inputs to the build process. The cache -location is read from DIB\_IMAGE\_CACHE. `Writing an element`_ -describes the interface within disk-image-builder for caching. When -invoking disk-image-builder, the ``--offline`` option will instruct -disk-image-builder to not refresh cached resources. - -Note that we don't maintain operating system package caches, instead -depending on your local infrastructure (e.g. Squid cache, or an APT or -Yum proxy) to facilitate caching of that layer, so you need to arrange -independently for offline mode. For more information about setting up -a squid proxy, consult the [TripleO -documentation](http://docs.openstack.org/developer/tripleo-incubator/devtest_setup.html#f3). - -Base images ------------ - -These are cached by the standard elements - fedora, redhat, ubuntu, -debian and opensuse. - -source-repositories -------------------- - -Git repositories and tarballs obtained via the source-repositories element will -be cached. - -Install Types -------------- - -Install types permit elements to be installed from different sources, such as -git repositories, distribution packages, or pip. The default install type -is 'source' but it can be modified on the disk-image-create command line -via the --install-type option. For example you can set: - - --install-type=package - -to enable package installs by default. Alternately, you can also -set DIB\_DEFAULT\_INSTALLTYPE. - -Many elements expose different install types. The different implementations -live under `--install` directories under an -element's install.d. The base element enables the chosen install type by -symlinking the correct hook scripts under install.d directly. -`` can be a string of alphanumeric and '-' characters, but -typically corresponds to the element name. - -For example, the nova element would provide: - - nova/install.d/nova-package-install/74-nova - nova/install.d/nova-source-install/74-nova - -The following symlink would be created for the package install type: - - install.d/74-nova -> nova-package-install/74-nova - -Or, for the source install type: - - install.d/74-nova -> nova-source-install/74-nova - -All other scripts that exist under install.d for an element will be executed as -normal. This allows common install code to live in a script under install.d. - -To set the install type for an element define an environment variable -`DIB_INSTALLTYPE_`. Note that if you used `-` characters in -your install directory prefix, those need to be replaced with `_` in the -environment variable. - -For example, to enable the package install type for the set of nova elements -that use `nova` as the install type prefix, define the following: - - export DIB_INSTALLTYPE_nova=package - - -C and C++ compilation ---------------------- - -Ccache is configured by the base element. Any compilation that honours ccache -will be cached. - -PyPI ----- - -The pypi element will bind mount a PyPI mirror from the cache dir and configure -pip and easy-install to use it. - -Design -====== - -Images are built using a chroot and bind mounted /proc /sys and /dev. The goal -of the image building process is to produce blank slate machines that have all -the necessary bits to fulfill a specific purpose in the running of an OpenStack -cloud: e.g. a nova-compute node. Images produce either a filesystem image with -a label of cloudimg-rootfs, or can be customised to produce whole disk images -(but will still contain a filesystem labelled cloudimg-rootfs). Once the file -system tree is assembled a loopback device with filesystem (or partition table -and file system) is created and the tree copied into it. The file system -created is an ext4 filesystem just large enough to hold the file system tree -and can be resized up to 1PB in size. - -An element is a particular set of code that alters how the image is built, or -runs within the chroot to prepare the image. E.g. the local-config element -copies in the http proxy and ssh keys of the user running the image build -process into the image, whereas the vm element makes the image build a regular -VM image with partition table and installed grub boot sector. The mellanox -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, ubuntu, debian and -opensuse. 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) and accepts keys via the cloud metadata -service, loading them into the distribution specific default user -account. - -The goal of a built image is to have any global configuration ready to roll, -but nothing that ties it to a specific cloud instance: images should be able to -be dropped into a test cloud and validated, and then deployed into a production -cloud (usually via bare metal nova) for production use. As such, the image -contents can be modelled as three distinct portions: - -- global content: the actual code, kernel, always-applicable config (like - disabling password authentication to sshd). -- metadata / config management provided configuration: user ssh keys, network - address and routes, configuration management server location and public key, - credentials to access other servers in the cloud. These are typically - refreshed on every boot. -- persistent state: sshd server key, database contents, swift storage areas, - nova instance disk images, disk image cache. These would typically be stored - on a dedicated partition and not overwritten when re-deploying the image. - -The goal of the image building tools is to create machine images that contain -the correct global content and are ready for 'last-mile' configuration by the -nova metadata API, after which a configuration management system can take over -(until the next deploy, when it all starts over from scratch). - -Existing elements ------------------ - -Elements are found in the subdirectory elements. Each element is in a directory -named after the element itself. Elements *should* have a README.md in the root -of the element directory describing what it is for. - -Writing an element ------------------- - -Conform to the following conventions: - -* Use the environment for overridable defaults, prefixing environment variable - names with "DIB\_". For example: DIB\_MYDEFAULT=${DIB\_MYDEFAULT:-default} - If you do not use the DIB\_ prefix you may find that your overrides are - discarded as the build environment is sanitised. - -* Consider that your element co-exists with many others and try to guard - against undefined behaviours. Some examples: - - * Two elements use the source-repositories element, but use the same filename - for the source-repositories config file. Files such as these (and indeed the - scripts in the various .d directories listed below) should be named such - that they are unique. If they are not unique, when the combined tree is - created by disk-image-builder for injecting into the build environment, one - of the files will be overwritten. - - * Two elements copy different scripts into /usr/local/bin with the same name. - If they both use set -e and cp -n then the conflict will be caught and cause - the build to fail. - -* If your element mounts anything into the image build tree ($TMP\_BUILD\_DIR) - then it will be automatically unmounted when the build tree is unmounted - - and not remounted into the filesystem image - if the mount point is needed - again, your element will need to remount it at that point. - -* If caching is required, elements should use a location under - $DIB\_IMAGE\_CACHE. - -* Elements should allow for remote data to be cached. When - $DIB\_OFFLINE is set, this cached data should be used if - possible. See the *Global image-build variables* section of this - document for more information. - -### 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. - -* 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 $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 - 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 $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 environment.d. -This directory contains bash script snippets that are sourced before running -scripts in each phase. - -DIB exposes an internal IMAGE\_ELEMENT variable which provides elements access -to the full set of elements that are included in the image build. This can -be used to process local in-element files across all the elements -(pkg-map for example). - -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. - - - -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. - -Global image-build variables ----------------------------- - -* DIB\_OFFLINE : this is always set. When not empty, any operations that - perform remote data access should avoid it if possible. If not possible - the operation should still be attempted as the user may have an external - cache able to keep the operation functional. - -* DIB\_IMAGE\_ROOT\_FS\_UUID : this contains the UUID of the root fs, when - diskimage-builder is building a disk image. This works only for ext - filesystems. - -* DIB\_IMAGE\_CACHE : path to where cached inputs to the build process - are stored. Defaults to ~/.cache/image_create. - -Structure of an element ------------------------ - -The above-mentioned global content can be further broken down in a way that -encourages composition of elements and reusability of their components. One -possible approach to this would be to label elements as either a "driver", -"service", or "config" element. Below are some examples. - -- 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, - containing several scripts across several phases: - - elements/ - service-nova/ - source-repository-nova - register a source repository - pre-install.d/ - 50-my-ppa - add a PPA - install.d/ - 10-user - common Nova user accts - 50-my-pack - install packages from my PPA - 60-nova - install nova and some dependencies - -- In the general case, configuration should probably be handled either by the - meta-data service (eg, o-r-c) or via normal CM tools - (eg, salt). That being said, it may occasionally be desirable to create a - set of elements which express a distinct configuration of the same software - components. - -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 - -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. - -Debugging elements ------------------- - -The build-time environment and command line arguments are captured by the -'base' element and written to /etc/dib\_environment and /etc/dib\_arguments -inside the image. - -Export 'break' to drop to a shell during the image build. Break points can be -set either before or after any of the hook points by exporting -"break=[before|after]-hook-name". Multiple break points can be specified as a -comma-delimited string. Some examples: - -* break=before-block-device-size will break before the block device size hooks - are called. - -* break=before-pre-install will break before the pre-install hooks. - -* break=after-error will break after an error during a in target hookpoint. - -Images are built such that the Linux kernel is instructed not to switch into -graphical consoles (i.e. it will not activate KMS). This maximises -compatibility with remote console interception hardware, such as HP's iLO. -However, you will typically only see kernel messages on the console - init -daemons (e.g. upstart) will usually be instructed to output to a serial -console so nova's console-log command can function. There is an element in the -tripleo-image-elements repository called "remove-serial-console" which will -force all boot messages to appear on the main console. - -Ramdisk images can be debugged at run-time by passing "troubleshoot" as a -kernel command line argument, or by pressing "t" when an error is reached. This -will spawn a shell on the console (this can be extremely useful when network -interfaces or disks are not detected correctly). - -Testing Elements ----------------- - -Elements can be tested using python. To create a test: - -* Create a directory called 'tests' in the element directory. - -* Create an empty file called '\_\_init\_\_.py' to make it into a python - package. - -* Create your test files as 'test\_whatever.py', using regular python test - code. - -To run all the tests use testr - `testr run`. To run just some tests provide -one or more regex filters - tests matching any of them are run - -`testr run apt-proxy`. - -Third party elements --------------------- - -Additional elements can be incorporated by setting ELEMENTS_PATH, for example -if one were building tripleo-images, the variable would be set like:: - - export ELEMENTS_PATH=tripleo-image-elements/elements - disk-image-create rhel7 cinder-api +* http://docs.openstack.org/developer/diskimage-builder/ Copyright ========= diff --git a/doc/source/developer/caches.rst b/doc/source/developer/caches.rst index 4ae8cbc17..9c1aca853 100644 --- a/doc/source/developer/caches.rst +++ b/doc/source/developer/caches.rst @@ -3,15 +3,20 @@ Caches and offline mode Since retrieving and transforming operating system image files, git repositories, Python or Ruby packages, and so on can be a significant overhead, -we cache many of the inputs to the build process in ~/.cache/image-create/. The -writing an element documentation describes the interface within -disk-image-builder for caching. When invoking disk-image-builder the --offline -option will instruct disk-image-builder to not refresh cached resources. +we cache many of the inputs to the build process. + +The cache location is read from DIB\_IMAGE\_CACHE. :ref:`developing-elements` +describes the interface within disk-image-builder for caching. + +When invoking disk-image-builder, the ``--offline`` option will instruct +disk-image-builder to not refresh cached resources. Note that we don't maintain operating system package caches, instead depending on your local infrastructure (e.g. Squid cache, or an APT or Yum proxy) to facilitate caching of that layer, so you need to arrange independently for -offline mode. +offline mode. For more information about setting up a squid proxy, consult the +`TripleO documentation +`_. Base images ----------- diff --git a/doc/source/developer/components.rst b/doc/source/developer/components.rst index 3ce491b4b..35c9c7225 100644 --- a/doc/source/developer/components.rst +++ b/doc/source/developer/components.rst @@ -29,4 +29,8 @@ Components Extract information about elements. +`tests/run_functests.sh` + + This runs a set of functional tests for diskimage-builder. + elements can be found in the top level elements directory. diff --git a/doc/source/developer/developing_elements.rst b/doc/source/developer/developing_elements.rst index 0e86f8b3f..aaa0739e6 100644 --- a/doc/source/developer/developing_elements.rst +++ b/doc/source/developer/developing_elements.rst @@ -1,3 +1,5 @@ +.. _developing-elements: + Developing Elements =================== @@ -27,6 +29,14 @@ 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. +* If caching is required, elements should use a location under + $DIB\_IMAGE\_CACHE. + +* Elements should allow for remote data to be cached. When + $DIB\_OFFLINE is set, this cached data should be used if + possible. See the *Global image-build variables* section of this + document for more information. + Phase Subdirectories ^^^^^^^^^^^^^^^^^^^^ @@ -191,6 +201,9 @@ Global image-build variables diskimage-builder is building a disk image. This works only for ext filesystems. +* DIB\_IMAGE\_CACHE : path to where cached inputs to the build process + are stored. Defaults to ~/.cache/image_create. + Structure of an element ----------------------- @@ -315,6 +328,8 @@ one or more regex filters - tests matching any of them are run - Third party elements -------------------- -Pending implementation. The idea is to have a search path for elements. - +Additional elements can be incorporated by setting ELEMENTS_PATH, for example +if one were building tripleo-images, the variable would be set like:: + export ELEMENTS_PATH=tripleo-image-elements/elements + disk-image-create rhel7 cinder-api