openstack-attic/akanda
Code Issues Proposed changes

Merge "Document building an appliance image from source"

Browse Source
This commit is contained in:
Jenkins 2015-05-27 15:12:48 +00:00 committed by Gerrit Code Review
commit 8a569638e7
1 changed files with 99 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

99
doc/source/appliance.rst
View File

@ -10,6 +10,105 @@ possible to build your own custom Service VM image (running additional
services of your own on top of the routing and other default services provided services of your own on top of the routing and other default services provided
by Akanda). by Akanda).
.. _appliance_build:
Building a Service VM image from source
---------------------------------------
The router code that runs within the appliance is hosted in the ``akanda-appliance``
repository at ``https://github.com/stackforge/akanda-appliance``. Additional tooling
for actually building a VM image to run the appliance is stored in the ``akanda-appliance-builder``
repository at ``https://github.com/stackforge/akanda-appliance-builder`` in the form of build
elements to be used with ``diskimage-builder``. The following instructions will walk through
building the Debian-based appliance locally, publishing to Glance and configuring the RUG to
use said image. These instructions are for building the image on an Ubuntu 14.04+ system.
Install Prerequisites
+++++++++++++++++++++
First, install ``diskimage-builder`` and required packages:
::
sudo apt-get -y install debootstrap qemu-utils
sudo pip install "diskimage-builder<0.1.43"
Next, clone the ``akanda-appliance-builder`` repository:
::
git clone https://github.com/akanda-appliance-builder
Build the image
+++++++++++++++
Kick off an image build using diskimage-builder:
::
cd akanda-appliance-builder
ELEMENTS_PATH=diskimage-builder/elements DIB_RELEASE=wheezy DIB_EXTLINUX=1 \
disk-image-create debian vm akanda -o akanda
Publish the image
+++++++++++++++++
The previous step should produce a qcow2 image called ``akanda.qcow`` that can be
published into Glance for use by the system:
::
# We assume you have the required OpenStack credentials set as an environment
# variables
glance image-create --name akanda --disk-format qcow2 --container-format bare \
--file akanda.qcow2
+------------------+--------------------------------------+
| Property | Value |
+------------------+--------------------------------------+
| checksum | cfc24b67e262719199c2c4dfccb6c808 |
| container_format | bare |
| created_at | 2015-05-13T21:27:02.000000 |
| deleted | False |
| deleted_at | None |
| disk_format | qcow2 |
| id | e2caf7fa-9b51-4f42-9fb9-8cfce96aad5a |
| is_public | False |
| min_disk | 0 |
| min_ram | 0 |
| name | akanda |
| owner | df8eaa19c1d44365911902e738c2b10a |
| protected | False |
| size | 450573824 |
| status | active |
| updated_at | 2015-05-13T21:27:03.000000 |
| virtual_size | None |
+------------------+--------------------------------------+
Configure the RUG
+++++++++++++++++
Take the above image id and set the corresponding value in the RUG's config file, to instruct
the service to use that image for software router instances it manages:
::
vi /etc/akanda/rug.ini
...
router_image_uuid=e2caf7fa-9b51-4f42-9fb9-8cfce96aad5a
Making local changes to the appliance service
+++++++++++++++++++++++++++++++++++++++++++++
By default, building an image in this way pulls the ``akanda-appliance`` code directly
from the upstream tip of trunk. If you'd like to make modifications to this code locally
and build an image containing those changes, set DIB_REPOLOCATION_akanda and DIB_REPOREF_akanda
in your enviornment accordingly during the image build, ie:
::
export DIB_REPOLOCATION_akanda=~/src/akanda-appliance # Location of the local repository checkout
export DIB_REPOREF_akanda=my-new-feature # The branch name or SHA-1 hash of the git ref to build from.
.. _appliance_rest: .. _appliance_rest:
REST API REST API