====== Diskimage Builder ======
===== Installing Diskimage Builder =====

[[https://github.com/openstack/diskimage-builder| Github diskimage-builder repo]]

[[http://docs.openstack.org/developer/diskimage-builder/user_guide/installation.html | Openstack diskimage-builder user install guide]]

First, update your system as **root**:
<code>
$ apt-get update 
$ apt-get upgrade
</code>

To install the **diskimage-builder** on your instance, you need pip. Run as **root**

<code>
$ apt-get install python-pip
</code>

After this, install the **diskimage-builder** with pip as **root**:

<code>
$ pip install diskimage-builder
$ apt-get install qemu-utils
</code>

==== Errors while installing ====
=== Language Package ===

Depending on your locale settings or installed language-packages, it can happen that this error occur:
<file>
Traceback (most recent call last):
  File "/usr/bin/pip", line 11, in <module>
    sys.exit(main())
  File "/usr/lib/python2.7/dist-packages/pip/__init__.py", line 215, in main
    locale.setlocale(locale.LC_ALL, '')
  File "/usr/lib/python2.7/locale.py", line 581, in setlocale
    return _setlocale(category, locale)
locale.Error: unsupported locale setting
</file>

This can be resolved by installing your language-pack. For german, run as **root**
<code>
$ apt-get install language-pack-de
</code>
Check your 2 letters country code [[http://www.worldatlas.com/aatlas/ctycodes.htm|here]]

=== Unresolved Hostname ===

To prevent an error like this:

<file>
sudo: unable to resolve host <name_of_instance>
</file>


in /etc/hosts, add the name of the instance as **root**

<file>
127.0.0.1 localhost <name_of_instance>

# The following lines are desirable for IPv6 capable hosts
::1 ip6-localhost ip6-loopback
fe00::0 ip6-localnet
ff00::0 ip6-mcastprefix
ff02::1 ip6-allnodes
ff02::2 ip6-allrouters
ff02::3 ip6-allhosts
</file>

===== Create a new Disk Image =====

Basically, invoking the following command is sufficient to create a new image:

<code bash>
disk-image-create ubuntu vm 
</code>

Images can be customized by specifying further arguments. Read the following sections to learn more about customizing your image.

  * -a architecture
  * -o target output file
  * -p package name[s]
  * elements

==== Elements ====

Nevertheless, images can be customized either by passing package identifiers or element names.
Corresponding the OpenStack documentation, elements define "what goes into [the] image and what modifications will be performed". For an bootable image, one should at least provide two Elements, **vm** which "[s]ets up a partitioned disk (rather than building just one filesystem with no partition table)" and a **distribution name** (e.g. Ubuntu, CentOS, OpenSUSE). Whereas we recommend Ubuntu, due to the entire documentation covers Ubuntu examples.

See [[https://github.com/openstack/diskimage-builder/tree/master/elements | here]] for a list of pre-built elements.

Adding more elements to the image during the creation process can simply achieved be append them to the end of the function call:

<code bash>
disk-image-create ubuntu vm docker # Note: Element 'docker' needs further parameters
</code>

An element defines steps for each phase of the creation cycle. Every single step could be implemented as a Bash or Python script. Have a look [[ http://docs.openstack.org/developer/diskimage-builder/developer/developing_elements.html#phase-subdirectories | here]] to learn more about the single stages.

==== Packages ==== 

As mentioned above, packages which are available through the, e.g. Ubuntu, [[ http://packages.ubuntu.com/ | package repository ]], could be installed during the creation process by simply append package names.

<code bash>

# create Ubuntu Trusty as qcow2 image
disk-image-create -a amd64 -o ubuntu-trusty.qcow ubuntu vm

# create Ubuntu Trusty as qcow2 image, additionally install Tomcat from Ubuntu repositories
disk-image-create -a amd64 -o ubuntu-trusty-with-tomcat.qcow -p tomcat8 ubuntu vm

# create Ubuntu 16.04 (Xenial) as qcow2 image and Tomcat
DIB_RELEASE=xenial disk-image-create -a amd64 -o ubuntu-xenial-with-tomcat.qcow -p tomcat8 ubuntu vm

</code> 

==== Create own Elements  ====

Developing new elements is straightforward. All one have to do is to create an executable script containing the command and place it within a directory of the right execution stage (see section Elements). 

For example, placing the following script in ''/path/to/elements/clojure-boot/install.d'' instructs the image builder to create an image with Boot, a build tool for the Clojure programming language, pre-installed:

<file bash 01-clojure-boot>
#!/bin/bash

set -eu
set -o pipefail

sudo bash -c "cd /usr/local/bin && \ 
              curl -fsSLo boot https://github.com/boot-clj/boot-bin/releases/download/latest/boot.sh && \ 
              chmod 755 boot"

</file>

Don't forget to set right permissions:

<code bash>
chmod +x 01-clojure-boot
</code>

Additionally, pointing the environment variable ''ELEMENTS_PATH'' to a custom directory, let you define a personal element path:

<code bash>
export ELEMENTS_PATH=/home/ubuntu/elements/
</code>

By default, all elements are located in ''/usr/local/share/diskimage-builder/elements''. Have a look [[ http://docs.openstack.org/developer/diskimage-builder/elements.html | here]] or [[ https://github.com/openstack/diskimage-builder/tree/master/elements | here ]] to examine whether a desired element already exists or which elements are available, in general.

**Note:** All executable files without extension are executed, thus removing the executable flag prevents the image builder to execute those files.

In order to create your customized image, simply invoke:

<code bash>
# creates image with GNU Octave, Octave documentation and gnuplot (from Ubuntu repository)
# identifier of the custom element have to match with directory name (/path/to/elements/clojure-boot)
disk-image-create -a amd64 -o ubuntu-with-clojure.qcow2 -p octave,octave-doc,gnuplot ubuntu vm clojure-boot
</code>

=== Docker install latest ===

This is an example for using shell scripts to install packages manually
https://get.docker.com/

<code>
$mkdir -p elements/latest_docker/install.d
$cd elements/latest_docker/install.d
</code>

Edit file ''10-latest-docker'' in ''install.d''. Pay attention that you don't use file extensions. Additionally, you have to use a [[https://en.wikipedia.org/wiki/Shebang_(Unix)|shebang]].

<file>
#!/bin/bash

curl https://get.docker.com | sh
</file>

<code>
chmod a+x 10-latest-docker
disk-image-create -a amd64 -o ubuntu-trusty_dap.qcow2 ubuntu vm latest_docker
</code>

==== package-installs.yaml ====

Placing a ''package-installs.yaml'' into a element directory is further way to specify packages, which should be installed.

Basically, the yaml file has the following structure:

<code>
---
package:version
</code>

See [[ http://docs.openstack.org/developer/diskimage-builder/elements/package-installs/README.html | here ]] for more details.

=== Example Docker ===

To remember the path of the host home directory:

<code>
home=$(dirname $0)
</code>

You need a system variable ''ELEMENTS_PATH'' with the path to your elements:

<code>
mkdir /home/ubuntu/elements
export ELEMENTS_PATH=/home/ubuntu/elements/
</code>

<code>
mkdir -p /home/ubuntu/elements/docker_as_package && cd /home/ubuntu/elements/docker_as_package
touch package-installs.yaml
</code>

Edit package-installs.yaml

<file>
---
docker.io:
</file>

Finally, create your new image by invoking the following command:

<code>
$ disk-image-create -a amd64 -o ubuntu-trusty_dap.qcow2 ubuntu vm docker_as_package
</code>

===== Upload Image (via CLI) =====

As soon your image was successfully created, it's possible to upload and register the image in Glance, the OpenStack service to manage images, via the command line.

Firstly, one have to set up neccessary user credentials to "set[...] variables in your shell that allow you to interact with OpenStack services". For this purpose, enter the "Access & Security" screen and switch to the "API Access" tab. Here, download the ''OpenStack RC File V3''. 

Afterwards, issue the following commands:

<code>
source <name of your project>-openrc.sh
sudo apt-get install python-openstackclient
openstack
(openstack) router list
(openstack) help
</code>

The command below will upload your image. After the upload is completed, an image called ''dlatest'' should be available through the "Images" tab, within the OpenStack dashboard.

  * %%--%%disk-format qcow2
  * %%--%%file <path_to_file>
  * <image-name >

== Example 1 ==

<code>
(openstack) image create --disk-format qcow2 --file ubuntu-trusty_dlatest.qcow2 dlatest
</code>

== Example 2 ==

<code>
(openstack) image create --disk-format qcow2 --file /home/ubuntu/ubuntu-trusty_dap.qcow2 docker_as_a_package
</code>