Merge lp:~jsuh/glance/glance-doc-jsuh into lp:~hudson-openstack/glance/trunk

[Jay Pipes]

I modified documentation to show more first-time user friendly examples on using glance. With the previous examples, I followed it as a first-time user and had to spend more than necessary time to figure out how to use it. With this modification, other first-time users would make it work on their systems more quickly.

[Jay Pipes (jaypipes)]

OK, Joseph, I still see the merge conflict marks in the diff (search below for <<<<<<< TREE).

These appear because you did not properly resolve the merge conflict before doing a bzr resolve --all.

You need to go into the doc/source/controllingservers.rst file and cut out the lines that you do not want and keep the lines you do. The lines between <<<<<<< TREE and ======= represent the lines you will want to keep. The lines between ======= and >>>>>>> MERGE-SOURCE are the lines you will want to remove, I believe.

Cheers,
jay

review: Needs Fixing

[lp:~jsuh/glance/glance-doc-jsuh]

117. By Joseph Suh <jsuh@bespin> on 2011-04-18

chnaged output

118. By Joseph Suh <jsuh@bespin> on 2011-04-18

 resolve merge conflicts

[Jay Pipes (jaypipes)]

Hi Joseph! Thanks for fixing it up! :)

review: Approve

[Jinwoo "Joseph" Suh (jsuh)]

Jay,

It was my pleasure.

Thanks,

Joseph

----- Original Message -----
From: "Jay Pipes" <email address hidden>
To: <email address hidden>
Sent: Thursday, April 21, 2011 11:05:53 AM
Subject: Re: [Merge] lp:~jsuh/glance/glance-doc-jsuh into lp:glance

Review: Approve
Hi Joseph! Thanks for fixing it up! :)
--
https://code.launchpad.net/~jsuh/glance/glance-doc-jsuh/+merge/58184
You are the owner of lp:~jsuh/glance/glance-doc-jsuh.

=== modified file 'doc/source/controllingservers.rst'
--- doc/source/controllingservers.rst	2011-02-09 21:56:48 +0000
+++ doc/source/controllingservers.rst	2011-04-18 20:38:35 +0000
@@ -30,6 +30,8 @@
 
 * Using the ``glance-control`` server daemon wrapper program
 
+We recommend using the second way.
+
 Manually starting the server
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -41,7 +43,7 @@
 
   Glance ships with an ``etc/`` directory that contains sample ``paste.deploy``
   configuration files that you can copy to a standard configuation directory and
-  adapt for your own uses.
+  adapt for your own uses. Specifically, bind_host must be set properly.
 
 If you do `not` specifiy a configuration file on the command line, Glance will
 do its best to locate a ``glance.conf`` configuration file in one of the
@@ -57,30 +59,62 @@
 
 * /etc
 
-If no configuration file is found, you will see any error, like so::
+If no configuration file is found, you will see an error, like::
 
   $> glance-api
   ERROR: Unable to locate any configuration file. Cannot load application glance-api
 
-Here is an example showing how you can manually start the ``glance-api`` server
-in a shell.::
-
-  $> sudo glance-api etc/glance.conf.sample --debug
-  2011-02-09 14:58:29    DEBUG [glance-api] ********************************************************************************
-  2011-02-09 14:58:29    DEBUG [glance-api] Configuration options gathered from config file:
-  2011-02-09 14:58:29    DEBUG [glance-api] /home/jpipes/repos/glance/trunk/etc/glance.conf.sample
-  2011-02-09 14:58:29    DEBUG [glance-api] ================================================
-  2011-02-09 14:58:29    DEBUG [glance-api] bind_host                      0.0.0.0
-  2011-02-09 14:58:29    DEBUG [glance-api] bind_port                      9292
-  2011-02-09 14:58:29    DEBUG [glance-api] debug                          True
-  2011-02-09 14:58:29    DEBUG [glance-api] default_store                  file
-  2011-02-09 14:58:29    DEBUG [glance-api] filesystem_store_datadir       /var/lib/glance/images/
-  2011-02-09 14:58:29    DEBUG [glance-api] registry_host                  0.0.0.0
-  2011-02-09 14:58:29    DEBUG [glance-api] registry_port                  9191
-  2011-02-09 14:58:29    DEBUG [glance-api] verbose                        False
-  2011-02-09 14:58:29    DEBUG [glance-api] ********************************************************************************
-  2011-02-09 14:58:29    DEBUG [routes.middleware] Initialized with method overriding = True, and path info altering = True
-  (16333) wsgi starting up on http://0.0.0.0:9292/
+Here is an example showing how you can manually start the ``glance-api`` server and ``glance-registry`` in a shell.::
+
+  $ sudo glance-api glance.conf --debug &  
+  jsuh@mc-ats1:~$ 2011-04-13 14:50:12    DEBUG [glance-api] ********************************************************************************
+  2011-04-13 14:50:12    DEBUG [glance-api] Configuration options gathered from config file:
+  2011-04-13 14:50:12    DEBUG [glance-api] /home/jsuh/glance.conf
+  2011-04-13 14:50:12    DEBUG [glance-api] ================================================
+  2011-04-13 14:50:12    DEBUG [glance-api] bind_host                      65.114.169.29
+  2011-04-13 14:50:12    DEBUG [glance-api] bind_port                      9292
+  2011-04-13 14:50:12    DEBUG [glance-api] debug                          True
+  2011-04-13 14:50:12    DEBUG [glance-api] default_store                  file
+  2011-04-13 14:50:12    DEBUG [glance-api] filesystem_store_datadir       /home/jsuh/images/
+  2011-04-13 14:50:12    DEBUG [glance-api] registry_host                  65.114.169.29
+  2011-04-13 14:50:12    DEBUG [glance-api] registry_port                  9191
+  2011-04-13 14:50:12    DEBUG [glance-api] verbose                        False
+  2011-04-13 14:50:12    DEBUG [glance-api] ********************************************************************************
+  2011-04-13 14:50:12    DEBUG [routes.middleware] Initialized with method overriding = True, and path info altering = True
+  2011-04-13 14:50:12    DEBUG [eventlet.wsgi.server] (21354) wsgi starting up on http://65.114.169.29:9292/
+
+  $ sudo glance-registry glance.conf &  
+  jsuh@mc-ats1:~$ 2011-04-13 14:51:16     INFO [sqlalchemy.engine.base.Engine.0x...feac] PRAGMA table_info("images")
+  2011-04-13 14:51:16     INFO [sqlalchemy.engine.base.Engine.0x...feac] ()
+  2011-04-13 14:51:16    DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Col ('cid', 'name', 'type', 'notnull', 'dflt_value', 'pk')
+  2011-04-13 14:51:16    DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (0, u'created_at', u'DATETIME', 1, None, 0)
+  2011-04-13 14:51:16    DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (1, u'updated_at', u'DATETIME', 0, None, 0)
+  2011-04-13 14:51:16    DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (2, u'deleted_at', u'DATETIME', 0, None, 0)
+  2011-04-13 14:51:16    DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (3, u'deleted', u'BOOLEAN', 1, None, 0)
+  2011-04-13 14:51:16    DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (4, u'id', u'INTEGER', 1, None, 1)
+  2011-04-13 14:51:16    DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (5, u'name', u'VARCHAR(255)', 0, None, 0)
+  2011-04-13 14:51:16    DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (6, u'disk_format', u'VARCHAR(20)', 0, None, 0)
+  2011-04-13 14:51:16    DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (7, u'container_format', u'VARCHAR(20)', 0, None, 0)
+  2011-04-13 14:51:16    DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (8, u'size', u'INTEGER', 0, None, 0)
+  2011-04-13 14:51:16    DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (9, u'status', u'VARCHAR(30)', 1, None, 0)
+  2011-04-13 14:51:16    DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (10, u'is_public', u'BOOLEAN', 1, None, 0)
+  2011-04-13 14:51:16    DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (11, u'location', u'TEXT', 0, None, 0)
+  2011-04-13 14:51:16     INFO [sqlalchemy.engine.base.Engine.0x...feac] PRAGMA table_info("image_properties")
+  2011-04-13 14:51:16     INFO [sqlalchemy.engine.base.Engine.0x...feac] ()
+  2011-04-13 14:51:16    DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Col ('cid', 'name', 'type', 'notnull', 'dflt_value', 'pk')
+  2011-04-13 14:51:16    DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (0, u'created_at', u'DATETIME', 1, None, 0)
+  2011-04-13 14:51:16    DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (1, u'updated_at', u'DATETIME', 0, None, 0)
+  2011-04-13 14:51:16    DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (2, u'deleted_at', u'DATETIME', 0, None, 0)
+  2011-04-13 14:51:16    DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (3, u'deleted', u'BOOLEAN', 1, None, 0)
+  2011-04-13 14:51:16    DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (4, u'id', u'INTEGER', 1, None, 1)
+  2011-04-13 14:51:16    DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (5, u'image_id', u'INTEGER', 1, None, 0)
+  2011-04-13 14:51:16    DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (6, u'key', u'VARCHAR(255)', 1, None, 0)
+  2011-04-13 14:51:16    DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (7, u'value', u'TEXT', 0, None, 0)
+
+  $ ps aux | grep glance
+  root     20009  0.7  0.1  12744  9148 pts/1    S    12:47   0:00 /usr/bin/python /usr/bin/glance-api glance.conf --debug
+  root     20012  2.0  0.1  25188 13356 pts/1    S    12:47   0:00 /usr/bin/python /usr/bin/glance-registry glance.conf
+  jsuh     20017  0.0  0.0   3368   744 pts/1    S+   12:47   0:00 grep glance
 
 Simply supply the configuration file as the first argument
 (``etc/glance.conf.sample`` in the above example) and then any common options
@@ -93,9 +127,8 @@
 configuration files, see the section entitled
 :doc:`Configuring Glance servers <configuring>`
 
-Note that the server does not `daemonize` itself when run manually
-from the terminal. You can force the server to daemonize using the standard
-shell backgrounding indicator, ``&``. However, for most use cases, we recommend
+Note that the server `daemonizes` itself by using the standard
+shell backgrounding indicator, ``&``, in the previous example. For most use cases, we recommend
 using the ``glance-control`` server daemon wrapper for daemonizing. See below
 for more details on daemonization with ``glance-control``.
 
@@ -125,8 +158,16 @@
 Here is an example that shows how to start the ``glance-registry`` server
 with the ``glance-control`` wrapper script. ::
 
-  $> sudo glance-control registry start etc/glance.conf.sample
-  Starting glance-registry with /home/jpipes/repos/glance/trunk/etc/glance.conf.sample
+
+  $ sudo glance-control all start glance.conf
+  Starting glance-api with /home/jsuh/glance.conf
+  Starting glance-registry with /home/jsuh/glance.conf
+
+  $ ps aux | grep glance
+  root     20038  4.0  0.1  12728  9116 ?        Ss   12:51   0:00 /usr/bin/python /usr/bin/glance-api /home/jsuh/glance.conf
+  root     20039  6.0  0.1  25188 13356 ?        Ss   12:51   0:00 /usr/bin/python /usr/bin/glance-registry /home/jsuh/glance.conf
+  jsuh     20042  0.0  0.0   3368   744 pts/1    S+   12:51   0:00 grep glance
+
  
 The same ``paste.deploy`` configuration files are used by ``glance-control``
 to start the Glance server programs, and you can specify (as the example above
@@ -134,8 +175,8 @@
 
 .. note::
 
-  To start all the Glance servers (currently the glance-api and glance-registry
-  programs) at once, you can specify "all" for the <SERVER>
+  To start each of Glance servers (currently the glance-api and glance-registry
+  programs), you can specify glance-api and glance-registry, respectively for the <SERVER>.
 
 Stopping a server
 -----------------

=== modified file 'doc/source/glance.rst'
--- doc/source/glance.rst	2011-02-25 16:33:24 +0000
+++ doc/source/glance.rst	2011-04-18 20:38:35 +0000
@@ -149,20 +149,20 @@
 We'd also like to tell Glance that this image should be called "My Image", and
 that the image should be public -- anyone should be able to fetch it.
 
-Here is how we'd upload this image to Glance::
+Here is how we'd upload this image to Glance. Change example ip number to your server ip number.::
 
-  $> glance add name="My Image" is_public=true < /tmp/images/myimage.tar.gz
+  $> glance add name="My Image" is_public=true < /tmp/images/myimage.tar.gz --host=65.114.169.29
 
 If Glance was able to successfully upload and store your VM image data and
 metadata attributes, you would see something like this::
 
-  $> glance add name="My Image" is_public=true < /tmp/images/myimage.tar.gz
+  $> glance add name="My Image" is_public=true < /tmp/images/myimage.tar.gz --host=65.114.169.29
   Added new image with ID: 2
 
 You can use the ``--verbose`` (or ``-v``) command-line option to print some more
 information about the metadata that was saved with the image::
 
-  $> glance --verbose add name="My Image" is_public=true < /tmp/images/myimage.tar.gz
+  $> glance --verbose add name="My Image" is_public=true < /tmp/images/myimage.tar.gz --host=65.114.169.29
   Added new image with ID: 4
   Returned the following metadata for the new image:
                  container_format => ovf
@@ -183,7 +183,7 @@
 If you are unsure about what will be added, you can use the ``--dry-run``
 command-line option, which will simply show you what *would* have happened::
 
-  $> glance --dry-run add name="Foo" distro="Ubuntu" is_publi=True < /tmp/images/myimage.tar.gz
+  $> glance --dry-run add name="Foo" distro="Ubuntu" is_publi=True < /tmp/images/myimage.tar.gz --host=65.114.169.29
   Dry run. We would have done the following:
   Add new image with metadata:
                  container_format => ovf
@@ -250,12 +250,12 @@
 Let's say we have an image with identifier 5 that we wish to change the is_public
 attribute of the image from False to True. The following would accomplish this::
 
-  $> glance update 5 is_public=true
+  $> glance update 5 is_public=true --host=65.114.169.29
   Updated image 5
 
 Using the ``--verbose`` flag will show you all the updated data about the image::
 
-  $> glance --verbose update 5 is_public=true
+  $> glance --verbose update 5 is_public=true --host=65.114.169.29
   Updated image 5
   Updated image metadata for image 5:
   URI: http://example.com/images/5
@@ -273,7 +273,7 @@
 
 You can delete an image by using the ``delete`` command, shown below::
 
-  $> glance --verbose delete 5
+  $> glance --verbose delete 5 --host=65.114.169.29
   Deleted image 5
 
 The ``index`` command
@@ -282,7 +282,7 @@
 The ``index`` command displays brief information about the *public* images
 available in Glance, as shown below::
 
-  $> glance index
+  $> glance index --host=65.114.169.29
   Found 4 public images...
   ID               Name                           Disk Format          Container Format     Size          
   ---------------- ------------------------------ -------------------- -------------------- --------------
@@ -297,7 +297,7 @@
 The ``details`` command displays detailed information about the *public* images
 available in Glance, as shown below::
 
-  $> glance details
+  $> glance details --host=65.114.169.29
   Found 4 public images...
   ================================================================================
   URI: http://example.com/images/1
@@ -349,7 +349,7 @@
 The ``show`` command displays detailed information about a specific image, specified
 with ``<ID>``, as shown below::
 
-  $> glance show 3
+  $> glance show 3 --host=65.114.169.29
   URI: http://example.com/images/3
   Id: 3
   Public? Yes
@@ -368,7 +368,7 @@
 and all image metadata. Passing the ``--verbose`` command will print brief
 information about all the images that were deleted, as shown below::
 
-  $> glance --verbose clear
+  $> glance --verbose clear --host=65.114.169.29
   Deleting image 1 "Some web image" ... done
   Deleting image 2 "Some other web image" ... done
   Completed in 0.0328 sec.