Fix image register example sin documentation

Problem: it was not clear if properties are mandatory in image registration

diff --git a/docs/developers/showcase.rst b/docs/developers/showcase.rst
index 365ac27..a1b469e 100644 (file)
--- a/docs/developers/showcase.rst
+++ b/docs/developers/showcase.rst
@@ -169,6 +169,7 @@ and we want to register it to the Plankton *image* service.
         raise
 
     #  3.2 Register the image
+    properties = dict(osfamily='linux', root_partition='1')
     try:
         image = plankton.image_register(IMAGE_NAME, IMAGE_LOCATION)
     except ClientError:
@@ -580,12 +581,12 @@ logging more. We also added some command line interaction candy.
             raise
 
 
-    def register_image(plankton, name, user_id, container, path):
+    def register_image(plankton, name, user_id, container, path, properties):
 
         image_location = (user_id, container, path)
         print(' Register the image')
         try:
-             return plankton.register(name, image_location)
+             return plankton.register(name, image_location, properties)
         except ClientError:
             log.debug('Failed to register image %s' % name)
             raise
@@ -691,7 +692,9 @@ logging more. We also added some command line interaction candy.
         plankton = init_plankton(endpoints['plankton'], token)
 
         image = register_image(
-            plankton, 'my image', user_id, opts.container, opts.imagefile)
+            plankton, 'my image', user_id, opts.container, opts.imagefile,
+            properties=dict(
+                osfamily=opts.osfamily, root_partition=opts.rootpartition))
 
         print('4.  Create  virtual  cluster')
         cluster = Cluster(
@@ -778,6 +781,16 @@ logging more. We also added some command line interaction candy.
                           help='Where to store information on created servers '
                                'including superuser passwords',
                           default='')
+        parser.add_option('--image-osfamily',
+                          action='store', type='string', dest='osfamily',
+                          metavar='OS FAMILY',
+                          help='linux, windows, etc.',
+                          default='linux')
+        parser.add_option('--image-root-partition',
+                          action='store', type='string', dest='rootpartition',
+                          metavar='IMAGE ROOT PARTITION',
+                          help='The partition where the root home is ',
+                          default='1')
 
         opts, args = parser.parse_args(argv[1:])
 

diff --git a/docs/examplesdir/imageregister.rst b/docs/examplesdir/imageregister.rst
index c4f1050..f8faaa4 100644 (file)
--- a/docs/examplesdir/imageregister.rst
+++ b/docs/examplesdir/imageregister.rst
@@ -3,8 +3,8 @@ Image registration
 
 In Synnefo, an image is loaded as a file to the storage service (Pithos+), and
 then is registered to the image service (Plankton). The image location at the
-storage server is unique through out a deployment and also necessary for the
-image to exist.
+storage server is unique in each a deployment and also a key for identifying
+the image.
 
 The image location format at user level::
 
@@ -18,9 +18,9 @@ The image location format at user level::
 
     *pithos://<user uuid>/<container>/<object path>*
 
-    The translation between
-    the two formats is handled internally by kamaki. The latest format is still
-    acceptable by kamaki due to backward compatibility but it is going to be deprecated from kamaki 0.12 and on.
+    The translation between the two formats is handled internally by kamaki.
+    The latest format is still acceptable by kamaki due to backward
+    compatibility but it is going to be deprecated from kamaki 0.12 and on.
 
 
 Register an image
@@ -40,6 +40,7 @@ Upload the image to container `pithos`
 
 Register the image object with the name 'Debian Base Alpha'
 
+
 .. code-block:: console
 
     [kamaki]: image register 'Debian Base Alpha' pithos:debian_base3.diskdump
@@ -60,14 +61,19 @@ Register the image object with the name 'Debian Base Alpha'
     Metadata file uploaded as pithos:debian_base3.diskdump.meta (version 1352)
     [kamaki]:
 
+.. warning:: The image created by the above command will not be able to create
+    a working virtual server, although the registration will be successful. In
+    the synnefo universe, an image has to be registered along with some
+    `properties <http://www.synnefo.org/docs/snf-image/latest/usage.html#image-properties>`_.
+
 .. note:: The `image register` command automatically creates a meta file and
     uploads it to the same location as the image. The meta file can be
     downloaded and reused for more image registrations.
 
-Another way to perform the two operations above is to call **/image register**
+Here is another way to perform the two operations above: **/image register**
 with the **\- -upload-image-file** argument. This single operation will upload
-the image file and then register it as an image, and is equivalent to manually
-calling **/file upload** and **/image register**.
+the image file and then register it as an image, and is equivalent to
+sequentially calling **/file upload** and **/image register**.
 
 In other words, the preceding and following command sequences are equivalent.
 
@@ -83,7 +89,7 @@ Read the metafile
 
 .. code-block:: console
 
-    [kamaki]: file cat pithos:debian_base3.diskdump
+    [kamaki]: file cat pithos:debian_base3.diskdump.meta
     {
       "status": "available",
       "name": "Debian Base Gama",
@@ -167,19 +173,23 @@ Attempt to unregister an image of another user
 Register with properties
 ------------------------
 
+.. warning:: A succesfully registered image will not be functional, if the
+    image properties are not defined correctly. Read the
+    `documentation <http://www.synnefo.org/docs/snf-image/latest/usage.html#image-properties>`_
+    for more information.
+
 The image will be registered again, but with some custom properties::
 
-    OS: Linux
-    user: someuser
+    OSFAMILY: linux
+    USER: someuser
 
 These properties can be added freely by the user, and they are not required by
 the image server, but they can be used by many applications.
-
 Attempt to register an image with custom properties
 
 .. code-block:: console
 
-    [kamaki]: image register 'Debian Base Gama' pithos:debian_base3.diskdump -p OS=Linux -p user=someuser
+    [kamaki]: image register 'Debian Base Gama' pithos:debian_base3.diskdump -p OS=linux -p user=someuser
     Metadata file pithos:debian_base3.diskdump.meta already exists
     [kamaki]:
 
@@ -188,7 +198,7 @@ it (**-f**)
 
 .. code-block:: console
 
-    [kamaki]: image register -f 'Debian Base Gama' pithos:debian_base3.diskdump -p OS=Linux -p user=someuser
+    [kamaki]: image register -f 'Debian Base Gama' pithos:debian_base3.diskdump -p OS=linux -p user=someuser
     [kamaki]:
 
 Register with a meta file
@@ -205,8 +215,8 @@ Download the meta file of the image (it was uploaded recently)
 
 The metadata file can be edited. Let's edit the file to add these properties::
 
-    OS: Linux
-    user: root
+    OS: linux
+    USER: root
 
 The resulting file will look like this:
 
@@ -220,7 +230,7 @@ The resulting file will look like this:
       "updated-at": "2013-06-19 08:01:00",
       "created-at": "2013-06-19 08:00:22",
       "properties": {
-        "OS": "Linux",
+        "OS": "linux",
         "USER": "root"
       },
       "location": "pithos://s0m3-u53r-1d/pithos/debian_base3.diskdump",
@@ -235,7 +245,7 @@ The resulting file will look like this:
 .. warning:: make sure the file is in a valid json format, otherwise image
     register will fail
 
-In the following registration, a different name will be used for the image.
+In the following registration, the image name will change to a new one.
 
 Register the image (don't forget the -f parameter, to override the metafile).
 
@@ -253,7 +263,7 @@ Register the image (don't forget the -f parameter, to override the metafile).
     name:             Debian Base Delta
     owner:            s0m3-u53r-1d
     properties:
-            OS:     Linux
+            OS:     linux
             USER:   root
     size:             903471104
     status:           available
@@ -292,7 +302,7 @@ A look at the image metadata reveals that the name is changed:
     name:             Changed Name
     owner:            s0m3-u53r-1d
     properties:
-            OS:     Linux
+            OS:     linux
             USER:   root
     size:             903471104
     status:           available
@@ -330,7 +340,7 @@ These operations can be used for properties with the same semantics:
     [kamaki]: image info 7h1rd-1m4g3-1d
     ...
     properties:
-            OS:     Linux
+            OS:     linux
             USER:   user
     ...
     [kamaki]:
@@ -344,7 +354,7 @@ Just to test the feature, let's create a property "greet" with value
     [kamaki]: image info 7h1rd-1m4g3-1d
     ...
     properties:
-            OS:     Linux
+            OS:     linux
             USER:   root
             GREET:  Hi there
     ...
@@ -352,7 +362,7 @@ Just to test the feature, let's create a property "greet" with value
     [kamaki]: image info 7h1rd-1m4g3-1d
     ...
     properties:
-            OS:     Linux
+            OS:     linux
             USER:   root
     ...
     [kamaki]:
@@ -404,7 +414,7 @@ Let's compine the metafile with a command line attribute `user: admin`
     name:             Debian Base Delta
     owner:            s0m3-u53r-1d
     properties:
-            OS:     Linux
+            OS:     linux
             USER:   root
     size:             903471104
     status:           available
@@ -458,7 +468,7 @@ Register the image without uploading a metafile
     name:             Debian Base Delta
     owner:            s0m3-u53r-1d
     properties:
-            OS:     Linux
+            OS:     linux
             USER:   root
     size:             903471104
     status:           available