Commit e34e0406 authored by Filippos Giannakos's avatar Filippos Giannakos
Browse files

Merge branch 'feature-archipdoc' into develop

parents 25630fcd d57ab3a8
......@@ -548,25 +548,174 @@ Block Storage Service (Archipelago)
Overview
--------
Archipelago offers Copy-On-Write snapshotable volumes based on pithos images
Architecture
------------
.. image:: images/archipelago-architecture.png
:width: 50%
:target: _images/archipelago-architecture.png
Prereqs
-------
The administrator must initialize the storage backend where archipelago volume
blocks will reside.
In case of a files backend, the administrator must create two directories. One
for the archipelago data blocks and one for the archipelago map blocks. These
should probably be over shared storage to enable sharing archipelago volumes
between multiple nodes. He or she, must also be able to supply a directory where
the pithos data and map blocks reside.
In case of a RADOS backend, the administrator must create two rados pools, one
for data blocks, and one for the map blocks. These pools, must be the same pools
used in pithos, in order to enable volume creation based on pithos images.
Installation
------------
Archipelago consists of
* ``libxseg0``: libxseg used to communicate over shared memory segments
* ``archipelago-kernel-dkms``: contains archipelago kernel modules to provide
block devices to be used as vm disks
* ``archipelago``: user space tools and peers for the archipelago management and
volume composition
* ``archipelago-ganeti``: ganeti ext storage scripts, that enable ganeti to
provision VMs over archipelago
Performing
.. code-block:: console
$ apt-get install archipelago-ganeti
should fetch all the required packages and get you up 'n going with archipelago
Bare in mind, that custom librados is required, which is provided in the apt
repo of grnet.
Librados is a dependency of archipelago, even if you do not intend to use
archipelago over RADOS
Configuration
-------------
Archipelago should work out of the box with a RADOS backend, but basic
configuration can be done in ``/etc/default/archipelago`` .
If you wish to change the storage backend to files, set
.. code-block:: console
STORAGE="files"
and provide the appropriate settings for files storage backend in the conf file.
These are:
* ``FILED_IMAGES``: directory for archipelago data blocks.
* ``FILED_MAPS``: directory for archipelago map blocks.
* ``PITHOS``: directory of pithos data blocks.
* ``PITHOSMAPS``: directory of pithos map blocks.
The settings for RADOS storage backend are:
* ``RADOS_POOL_MAPS``: The pool where archipelago and pithos map blocks reside.
(Defaults to "maps")
* ``RADOS_POOL_BLOCKS``: The pool where archipelago and pithos data blocks
reside. (Defaults to "blocks")
Examples can be found in the conf file.
Be aware that archipelago infrastructure doesn't provide default values for this
settings. If they are not set in the conf file, archipelago will not be able to
function.
Archipelago also provides ``VERBOSITY`` config options to control the output
generated by the userspace peers.
The available options are:
* ``VERBOSITY_BLOCKERB``
* ``VERBOSITY_BLOCKERM``
* ``VERBOSITY_MAPPER``
* ``VERBOSITY_VLMC``
and the available values are:
* 0 : Error only logging.
* 1 : Warning logging.
* 2 : Info logging.
* 3 : Debug logging. WARNING: This options produces tons of output, but the
logrotate daemon should take care of it.
Working with Archipelago
------------------------
``archipelago`` provides basic functionality for archipelago.
Currently it supports the following commands:
* ``start``
* ``stop``
* ``restart``
* ``status``
``start``, ``stop``, ``restart`` can be combined with the ``-u / --user`` option
to affect only the userspace peers supporting archipelago.
Archipelago advanced operations
-------------------------------
The ``vlmc`` tool provides a way to interact with archipelago volumes
* ``vlmc map <volumename>``: maps the volume to a xsegbd device.
* ``vlmc unmap </dev/xsegbd[1-..]``: unmaps the specified device from the
system.
* ``vlmc create <volumename> --snap <snapname> --size <size>``: creates a new
volume named <volumename> from snapshot name <snapname> with size <size>.
The ``--snap`` and ``--size`` are optional, but at least one of them is
mandatory. e.g:
``vlmc create <volumename> --snap <snapname>`` creates a volume named
volumename from snapshot snapname. The size of the volume is the same as
the size of the snapshot.
``vlmc create <volumename> --size <size>`` creates an empty volume of size
<size> named <volumename>.
* ``vlmc remove <volumename>``: removes the volume and all the related
archipelago blocks from storage.
* ``vlmc list``: provides a list of archipelago volumes. Currently only works
with RADOS storage backend.
* ``vlmc open <volumename>``: opens an archipelago volume. That is, taking all
the necessary locks and also make the rest of the infrastructure aware of the
operation.
This operation succeeds if the volume is alread opened.
* ``vlmc close <volumename>``: closes an archipelago volume. That is, performing
all the necessary functions in the insfrastrure to successfully release the
volume. Also releases all the acquired locks.
``vlmc close`` should be performed after a ``vlmc open`` operation.
* ``vlmc lock <volumename>``: locks a volume. This step allow the administrator
to lock an archipelago volume, independently from the rest of the
insfrastrure.
* ``vlmc unlock [-f] <volumename>``: unlocks a volume. This allow the
administrator to unlock a volume, independently from the rest of the
infrastructure.
The unlock option can be performed only by the blocker that acquired the lock
in the first place. To unlock a volume from another blocker, ``-f`` option
must be used to break the lock.
The "kamaki" API client
......
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