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
         raise
 
     #  3.2 Register the image

+    properties = dict(osfamily='linux', root_partition='1')

     try:
         image = plankton.image_register(IMAGE_NAME, IMAGE_LOCATION)
     except ClientError:
     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
 
 
             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:
 
         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
         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 = 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(
 
         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='')
                           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:])
 
 
         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
 
 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::
 
 
 The image location format at user level::
 

@@ -18,9 +18,9 @@ The image location format at user level::
 
     *pithos://<user uuid>/<container>/<object path>*
 
 
     *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
 
 
 Register an image

@@ -40,6 +40,7 @@ Upload the image to container `pithos`
 
 Register the image object with the name 'Debian Base Alpha'
 
 
 Register the image object with the name 'Debian Base Alpha'
 

+

 .. code-block:: console
 
     [kamaki]: image register 'Debian Base Alpha' pithos:debian_base3.diskdump
 .. 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]:
 
     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.
 
 .. 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
 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.
 
 
 In other words, the preceding and following command sequences are equivalent.
 

@@ -83,7 +89,7 @@ Read the metafile
 
 .. code-block:: console
 
 
 .. code-block:: console
 

-    [kamaki]: file cat pithos:debian_base3.diskdump
+    [kamaki]: file cat pithos:debian_base3.diskdump.meta

     {
       "status": "available",
       "name": "Debian Base Gama",
     {
       "status": "available",
       "name": "Debian Base Gama",

@@ -167,19 +173,23 @@ Attempt to unregister an image of another user
 Register with properties
 ------------------------
 
 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::
 
 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.
 
 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
 
 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]:
 
     Metadata file pithos:debian_base3.diskdump.meta already exists
     [kamaki]:
 

@@ -188,7 +198,7 @@ it (**-f**)
 
 .. code-block:: console
 
 
 .. 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
     [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::
 
 
 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:
 
 
 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": {
       "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",
         "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
 
 .. 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).
 
 
 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:
     name:             Debian Base Delta
     owner:            s0m3-u53r-1d
     properties:

-            OS:     Linux
+            OS:     linux

             USER:   root
     size:             903471104
     status:           available
             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:
     name:             Changed Name
     owner:            s0m3-u53r-1d
     properties:

-            OS:     Linux
+            OS:     linux

             USER:   root
     size:             903471104
     status:           available
             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:
     [kamaki]: image info 7h1rd-1m4g3-1d
     ...
     properties:

-            OS:     Linux
+            OS:     linux

             USER:   user
     ...
     [kamaki]:
             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:
     [kamaki]: image info 7h1rd-1m4g3-1d
     ...
     properties:

-            OS:     Linux
+            OS:     linux

             USER:   root
             GREET:  Hi there
     ...
             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:
     [kamaki]: image info 7h1rd-1m4g3-1d
     ...
     properties:

-            OS:     Linux
+            OS:     linux

             USER:   root
     ...
     [kamaki]:
             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:
     name:             Debian Base Delta
     owner:            s0m3-u53r-1d
     properties:

-            OS:     Linux
+            OS:     linux

             USER:   root
     size:             903471104
     status:           available
             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:
     name:             Debian Base Delta
     owner:            s0m3-u53r-1d
     properties:

-            OS:     Linux
+            OS:     linux

             USER:   root
     size:             903471104
     status:           available
             USER:   root
     size:             903471104
     status:           available