Synnefo

Block Storage Service (Archipelago)

===================================

Overview

--------

Archipelago offers Copy-On-Write snapshotable volumes. Pithos images can be used

to provision a volume with Copy-On-Write semantics (i.e. a clone). Snapshots

offer a unique deduplicated image of a volume, that reflects the volume state

during snapshot creation and are indistinguishable from a Pithos image.

Archipelago is used by Cyclades and Ganeti for fast provisioning of VMs based on

CoW volumes. Moreover, it enables live migration of thinly-provisioned VMs with

no physically shared storage.

Archipelago Architecture

------------------------

.. image:: images/archipelago-architecture.png

   :width: 50%

   :target: _images/archipelago-architecture.png

.. _syn+archip+rados:

Overview of Synnefo + Archipelago + RADOS

-----------------------------------------

.. image:: images/synnefo-arch3.png

   :width: 100%

   :target: _images/synnefo-arch3.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

* ``python-xseg``: python bindings for libxseg

* ``archipelago-kernel-dkms``: contains archipelago kernel modules to provide

  block devices to be used as vm disks

* ``python-archipelago``: archipelago python module. Includes archipelago and

  vlmc functionality.

* ``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.

For now, 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.

* ``RADOS_POOL_BLOCKS``: The pool where archipelago and pithos data blocks

  reside.

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.

Usage:

.. code-block:: console

  $ archipelago [-u] command

Currently it supports the following commands:

* ``start [peer]``

  Starts archipelago or the specified peer.

* ``stop [peer]``

  Stops archipelago or the specified peer.

* ``restart [peer]``

  Restarts archipelago or the specified peer.

* ``status``

  Show the status of archipelago.

Available peers: ``blockerm``, ``blockerb``, ``mapperd``, ``vlmcd``.

``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 info <volumename>``: shows volume information. Currently returns only

  volume size.

* ``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

  infrastrure.

* ``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.