Document object storage commands and library

docs/commands.rst

@@ -420,6 +420,57 @@ Showcase: Connect a network to a VM
 
 .. Note:: In kamaki shell, / is used to access top-level command groups while working in command group contexts
 
+volume (Block Storage)
+----------------------
+
+.. code-block:: text
+
+    info        Get details about a volume
+    list        List volumes
+    create      Create a new volume
+    modify      Modify a volumes' properties
+    reassign    Reassign volume to a different project
+    type        Get volume type details
+    types       List volume types
+    delete      Delete a volume
+
+Showcase: Create a volume
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: console
+
+    $ kamaki volume create --server-id=11687 --name='Small Volume' --size=2
+    id: v0lum31d
+    name: Small Volume
+    size: 2
+    ...
+    $ kamaki volume list
+    v0lum31d   Small Volume
+
+snapshot (Block Storage)
+------------------------
+
+.. code-block:: text
+
+    info    Get details about a snapshot
+    list    List snapshots
+    create  Create a new snapshot
+    modify  Modify a snapshots' properties
+    delete  Delete a snapshot
+
+Showcase: Create a snapshot
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: console
+
+    $ kamaki snapshot create --volume-id=v0lum31d --name='Small Snapshot'
+    id: sn4p5h071d
+    name: Small Snapshot
+    ...
+    $ kamaki snapshot list
+    sn4p5h071d   Small Snapshot
+    ...
+
 container (Storage/Pithos+)
 ---------------------------
 

docs/developers/clients-api.rst

@@ -307,7 +307,7 @@ Two servers and a private network
 
 .. code-block:: python
 
-    #! /user/bin/python
+    #! /usr/bin/python
 
     from kamaki.clients.astakos import AstakosClient
     from kamaki.clients.cyclades import (
@@ -341,3 +341,91 @@ Two servers and a private network
 
     srv_state2 = cyclades.wait_server(srv2['id'])
     assert srv_state2 in ('ACTIVE', ), 'Server 2 built failure'
+
+Snapshot server and backup
+''''''''''''''''''''''''''
+
+.. code-block:: python
+
+    #! /usr/bin/python
+
+    from kamaki.clients.astakos import AstakosClient
+    from kamaki.clients.cyclades import (
+        CycladesClient, CycladesBlockStorageClient)
+    from kamaki.clients.image import ImageClient
+
+    AUTHENTICATION_URL = 'https://accounts.example.com/identity/v2.0'
+    TOKEN = 'replace this with your token'
+
+    astakos = AstakosClient(AUTHENTICATION_URL, TOKEN)
+
+    CYCLADES_URL = astakos.get_endpoint_url(CycladesClient.service_type)
+    compute = CycladesClient(CYCLADES_URL, TOKEN)
+
+    SERVER_ID = 'your server ID here'
+
+    srv = compute.get_server_details(SERVER_ID)
+    volume_id = srv['volumes'][0]
+
+    BS_URL = astakos.get_endpoint_url(CycladesBlockStorageClient.service_type)
+    block_storage = CycladesBlockStorageClient(BS_URL, TOKEN)
+
+    snp = block_storage.create_snapshot(volume_id, 'Srv %s BackUp' % srv['id'])
+
+    IMAGE_URL = astakos.get_endpoint_url(ImageClient.service_type)
+    plankton = ImageClient(IMAGE_URL, TOKEN)
+
+    #  Get location in the form pithos://UUID/CONTAINER/PATH
+    snp_location = plankton.get_meta(snp['id'])['location']
+
+    #  Optional: download to local storage
+    from kamaki.clients.pithos import PithosClient
+
+    PITHOS_URL = astakos.get_endpoint_url(PithosClient.service_type)
+    pref_len = len('pithos://')
+    ACCOUNT, sep, rel_path = snp_location[pref_len:].partition('/')
+    CONTAINER, sep, PATH = rel_path.partition('/')
+    pithos = PithosClient(PITHOS_URL, TOKEN, ACCOUNT, CONTAINER)
+
+    LOCAL_DESTINATION_PATH = 'local path for backup image file'
+
+    pithos.download_object(PATH, LOCAL_DESTINATION_PATH)
+
+Restore server from local snapshot image
+''''''''''''''''''''''''''''''''''''''''
+
+.. code-block:: python
+
+    #! /usr/bin/python
+
+    from kamaki.clients.astakos import AstakosClient
+    from kamaki.clients.cyclades import CycladesClient
+    from kamaki.clients.image import ImageClient
+    from kamaki.clients.pithos import PithosClient
+
+    AUTHENTICATION_URL = 'https://accounts.example.com/identity/v2.0'
+    TOKEN = 'replace this with your token'
+
+    astakos = AstakosClient(AUTHENTICATION_URL, TOKEN)
+
+    ACCOUNT, CONTAINER = astakos.user_info['id'], 'snapshots'
+    PITHOS_URL = astakos.get_endpoint_url(PithosClient.service_type)
+    pithos = PithosClient(PITHOS_URL, TOKEN, ACCOUNT, CONTAINER)
+
+    LOCAL_BACKUP_IMAGE = 'local backup image file here'
+    PATH = 'server_backup.diskdump'
+
+    with open(LOCAL_BACKUP_IMAGE) as f:
+        obj = pithos.upload_object(PATH, f)
+
+    IMAGE_URL = astakos.get_endpoint_url(ImageClient.service_type)
+    plankton = ImageClient(IMAGE_URL, TOKEN)
+
+    LOCATION = 'pithos://%s/%s/%s' % (ACCOUNT)
+    img = plankton.register('Backup Snapshot', LOCATION)
+
+    CYCLADES_URL = astakos.get_endpoint_url(CycladesClient.service_type)
+    compute = CycladesClient(CYCLADES_URL, TOKEN)
+
+    FLAVOR_ID = 'make sure to pick a flavor with enough resources'
+    restored_server = compute.create('Restored server', FLAVOR_ID, img['id'])

docs/examples.rst

@@ -12,4 +12,5 @@ Examples
     examplesdir/imageregister
     examplesdir/server
     examplesdir/network
+    examplesdir/blockstorage
     examplesdir/astakos

docs/examplesdir/blockstorage.rst

+Volumes and Snapshots
+=====================
+
+In this section we will snapshot a virtual server, backup the snapshot image to
+a local storage and then we will destroy and recreate the server.
+
+**List existing virtual servers and volumes**
+
+.. code-block:: console
+
+    $ kamaki server list
+    1 My test server
+    2 My very important server
+
+    $ kamaki volume list
+    v0lum31 Volume for test server
+    v0lum32 Volume for important server
+
+.. note:: Usually each virtual server corresponds to one volume, but new
+    volumes can also been created:
+
+    .. code-block:: console
+
+        $ kamaki volume create --name='extra volume' --server-id=2 --size=20
+
+**Take a snapshot**
+
+.. code-block:: console
+
+    $ kamaki snapshot create --name='Important server backup' --volume-id=2
+    id: imp0r74n7-s3rv3r-1m4g3
+    display_name: Important server backup
+    status: ACTIVE
+    size: 10
+    descrtiption: null
+    created_at: 2014-05-19T19:52:04.949734
+    metadata:
+    volume_id: v0lum32
+
+The new snapshot appears as a loaded image as well as a file stored in
+Pithos+
+
+.. code-block:: console
+
+    $ kamaki snapshot list
+    imp0r74n7-s3rv3r-1m4g3 Important server backup
+
+    $ kamaki file list /snapshots
+    20GB  v0lum31-snap-0
+
+    $ kamaki image list --id=imp0r74n7-s3rv3r-1m4g3
+    imp0r74n7-s3rv3r-1m4g3 Important server backup
+
+**Backup snapshot image to local storage**
+
+This is optional, but better safe than sorry.
+
+.. code-block:: console
+
+    $ kamaki file download /snapshots/v0lum31-snap-0 local.backup
+    ...
+
+**Destroy and reload**
+
+For demonstration purposes, let's destroy the server. The snapshot image will
+be used to recreate it afterwards.
+
+.. code-block:: console
+
+    $ kamaki server delete 2 -w
+    ...
+    Server status is now DELETED
+
+    $ kamaki server create --name='Important server' --flavor-id=1 --image-id=imp0r74n7-s3rv3r-1m4g3 -w
+    id: 3
+    name: Important server
+    ...
+    Server status is now ACTIVE
+
+**Reload from local backup**
+
+If both the server and the snapshot are lost, the local backup can be used to
+restore the server. To do this, we need to register the backup as an image (see
+`Image register <imageregister.html>`_ for more details).
+
+.. code-block:: console
+
+    $ kamaki image register --name='Image from BackUp' --location=/snapshots/reloaded.diskdump --upload-image-file=local.backup
+    id: r3l04d3d-5n4p5h07-1m4g3
+    name: Image from BackUp
+    ...
+
+    $ kamaki server create --name='Server from local BackUp' --flavor-id=1 --image-id=r3l04d3d-5n4p5h07-1m4g3 -w
+    id: 4
+    name: Server from local BackUp
+    ...
+    Server is now ACTIVE

docs/man/kamaki.rst

@@ -83,6 +83,12 @@ ip
 port
     Networking API network Commands
 
+volume
+    Block Storage API volume commands
+
+snapshot
+    Block Storage API snapshot commands
+
 config
     Kamaki option and cloud configuration
 
@@ -166,6 +172,27 @@ quota
 
 * list          Get user quotas
 
+volume
+******
+
+* info      Get details about a volume
+* list      List volumes
+* create    Create a new volume
+* modify    Modify a volumes' properties
+* reassign  Reassign volume to a different project
+* type      Get volume type details
+* types     List volume types
+* delete    Delete a volume
+
+snapshot
+********
+
+* info      Get details about a snapshot
+* list      List snapshots
+* create    Create a new snapshot
+* modify    Modify a snapshots' properties
+* delete    Delete a snapshot
+
 resource
 ********