These tools are the components of TripleO (https://wiki.openstack.org/wiki/TripleO) that are responsible for building disk images.
This repository has the core functionality for building disk images, file system images and ramdisk images for use with OpenStack (both virtual and bare metal). The core functionality includes the various operating system specific modules for disk/filesystem images, and deployment and hardware inventory ramdisks.
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).
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
disk-image-get-kernel filename : DEPRECATED Extract the appropriate kernel and ramdisk to use when doing PXE boot using filename as the image for a machine. Consider using the baremetal element, rather than this tool.
elements can be found in the top level elements directory.
element-info : Extract information about elements.
Automation: While users and operators can manually script or put together ram disks and disk images, mature automation makes customisation and testing easier.
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.
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
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).
These are cached by the standard elements - fedora, redhat, ubuntu, debian and opensuse.
Git repositories and tarballs obtained via the source-repositories element will be cached.
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-dir-prefix>-<install-type>-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. <install-dir-prefix> 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_<install_dir_prefx>. 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
Ccache is configured by the base element. Any compilation that honours ccache will be cached.
The pypi element will bind mount a PyPI mirror from the cache dir and configure pip and easy-install to use it.
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:
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).
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.
Conform to the following conventions:
### 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
- runs: outside chroot
- inputs: $TMP_HOOKS_PATH
- outputs: None
- runs: in chroot
- runs: in chroot
- runs: in chroot
- runs: outside chroot
- inputs: $IMAGE_BLOCK_DEVICE={path} $TARGET_ROOT={path}
- outputs: $IMAGE_BLOCK_DEVICE={path}
- runs: in chroot
- runs: outside chroot
- inputs: $ARCH=i386|amd64|armhf $TARGET_ROOT=/path/to/target/workarea
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.
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).
Each element can use the following files to define or affect dependencies:
Ramdisk elements support the following files in their element directories:
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.
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:
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 typicallly 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).
Elements can be tested using python. To create a test:
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.
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
Copyright 2012 Hewlett-Packard Development Company, L.P. Copyright (c) 2012 NTT DOCOMO, INC.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
此处可能存在不合适展示的内容,页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容,可点击提交进行申诉,我们将尽快为您处理。