Commit d0cae1ab authored by Constantinos Venetsanopoulos's avatar Constantinos Venetsanopoulos
Browse files

docs: split Image IDs and Storage backends

Split the section `Image IDs and Storage backends' to decouple
the actual feature, the logic and the configuration. Feature and
logic is moved to a new section under 'Architecture' and the rest
remain under 'Usage'. Also add examples for each case.
parent 3f11e70a
......@@ -80,14 +80,49 @@ The architecture is presented below:
.. image:: /images/arch.png
.. _storage-backends:
Storage backends
^^^^^^^^^^^^^^^^
As stated above, for step (1), *snf-image* is capable of fetching images that
are stored in a variety of different backends and then extracting them onto the
newly created block device. The following backends are supported:
* **Local backend**:
The local backend is used to retrieve images that are stored on the Ganeti
node that the image deployment takes place. All local images are expected to be
found under a predifined image directory. By default */var/lib/snf-image* is
used, but the user may change this by overwriting the value of the
*IMAGE_DIR* variable under ``/etc/default/snf-image``.
* **Network backend**:
The network backend is used to retrieve images that are accessible from the
network. snf-image can fetch images via *http:*, *https:*, *ftp:* or *ftps:*,
using `cURL <http://curl.haxx.se/>`_.
* **Pithos backend**:
*snf-image* contains a special command-line tool (*pithcat*) for retrieving
images residing on a Pithos installation. To set up snf-image's Pithos backend
the user needs to setup the ``PITHOS_DATA`` and ``PITHOS_DB`` variables inside
``/etc/default/snf-image`` accordingly.
* **Null backend**:
If the null backend is selected, no image copying is performed. This actually
is meant for bypassing step (1) alltogether. This is useful, if the disk
provisioned by Ganeti already contains an OS installation before *snf-image* is
executed (for example if the disk was created as a clone of an existing VM's
hard disk).
.. _image-configuration-tasks:
Image Configuration Tasks
^^^^^^^^^^^^^^^^^^^^^^^^^
Configuration tasks are scripts called by snf-image-helper to accomplish
various configuration steps on the newly created instance. See below for a
description of each one of them:
Configuration tasks are scripts called by snf-image-helper inside the helper VM
to accomplish various configuration steps on the newly created instance. See
below for a description of each one of them:
**FixPartitionTable**: Enlarges the last partition in the partition table of
the instance, to consume all the available space and optionally adds a swap
......
......@@ -21,8 +21,8 @@ following OS Parameters:
.. _image-format:
Image Format
^^^^^^^^^^^^
Image Format (img_format)
^^^^^^^^^^^^^^^^^^^^^^^^^
snf-image supports 3 different types of image formats:
......@@ -38,46 +38,46 @@ image formats please see the :ref:`corresponding advanced section
.. _image-id:
Image IDs & Storage back-ends
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
*snf-image* capable of deploying images that are stored in a variety of
different back-ends. The back-end to be used is determined by the value of the
*img_id* OS parameter. The following back-ends are supported:
* **Local back-end**:
The local back-end is used to retrieve images that are stored in the ganeti
node that the image deployment takes place. The local back-end is used if
the value of the *img_id* ganeti OS parameter is either prefixed with
*file://* or is not prefixed at all. All local images are expected to be
found under a predifined image directory. By default */var/lib/snf-image* is
used, but the user may change this by overwriting the value of the
*IMAGE_DIR* variable under ``/etc/default/snf-image``. The name of the image
file is created by adding the image type extension in the end of the
*img_id*. For example if the *img_id* is *file://slackware* and the image
type is *diskdump*, snf-image will expect to find an image file under the
following path: ``/usr/lib/snf-image/slackware.diskdump``
* **Network back-end**:
The network back-end is used to retrieve images that are accessible from the
network. If the *imd_id* starts with *http:*, *https:*, *ftp:* or *ftps:*,
snf-image will treat the *img_id* as a remote URL and will try to fetch the
Image ID (img_id)
^^^^^^^^^^^^^^^^^
The **img_id** OS parameter points to the actual Image that we want to deploy.
It is a URI and its prefix denotes the type of :ref:`backend <storage-backends>`
to be used. If no prefix is used, it defaults to the local backend:
* **Local backend**:
To select it, the prefix should be ``file://``, followed by the name of the
image. All local images are expected to be found under a predefined image
directory (``/var/lib/snf-image`` by default). The name of the actual file
should be ``<img_id>.<img_format>``.
| For example, if we want to deploy the image file:
| ``/var/lib/snf-image/slackware.diskdump``
| Then:
| ``img_format=diskdump`` and ``img_id=file://slackware``
* **Network backend**:
If the **imd_id** starts with ``http:``, ``https:``, ``ftp:`` or ``ftps:``,
snf-image will treat the **img_id** as a remote URL and will try to fetch the
image using `cURL <http://curl.haxx.se/>`_.
* **Pithos back-end**:
If an *img_id* is prefixed with *pithos:* or *pithosmap:* the image is
considered to be pithos back-ended. *snf-image* contains a special
command-line tool (*pithcat*) for retrieving this kind of images. For
*pithosmap:* images, the user needs to have set a valid value for the
*PITHOS_DATA* variable. For *pithos:* images, in addition to PITHOS_DATA,
the PITHOS_DB variable needs to contain a valid value too.
``/etc/default/snf-image`` may be used to set both values.
* **Null back-end**:
The null back-end is used if the *img_id* value is *null*. In this case no
image copying is performed. This is usefull if the hard disk already
contains an OS installation before *snf-image* is executed (for example if
the hard disk is a snapshot of an existing VM's hard disk).
| For example, if we want to deploy an image from an http location:
| ``img_id=http://www.synnefo.org/path/to/image/slackware-image``
* **Pithos backend**:
If the **img_id** is prefixed with ``pithos://`` or ``pithosmap://`` the
image is considered to reside on a Pithos deployment. For ``pithosmap://``
images, the user needs to have set a valid value for the
``PITHOS_DATA`` variable in snf-image's configuration file
(``/etc/default/snf-image`` by default). For ``pithos://`` images, in
addition to ``PITHOS_DATA``, the user needs to have set a valid value for the
``PITHOS_DB`` variable, too.
| For example, if we want to deploy using a full Pithos URI:
| ``img_id=pithos://<user-uuid>/<container>/<slackware-image>``
| or if we already know the map:
| ``img_id=pithosmap://<slackware-image-map-name>``
* **Null backend**:
To select the Null backend and skip the fetching and extraction step, we set
``img_id=null``.
.. _image-properties:
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment