openstack/glance
Code Issues Proposed changes

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.

Browse Source
This commit is contained in:
Joseph Suh 2011-04-21 15:07:43 +00:00 committed by Tarmac
commit 32e9b882e1
2 changed files with 80 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

95
doc/source/controllingservers.rst
View File

@ -30,6 +30,8 @@ reference implementation registry server that ships with Glance):
* Using the ``glance-control`` server daemon wrapper program
We recommend using the second way.
Manually starting the server
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -41,7 +43,7 @@ use when configuring the server application.
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 @@ following directories, stopping at the first config file it finds:
* /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.::
Here is an example showing how you can manually start the ``glance-api`` server and ``glance-registry`` 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/
$ 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 @@ For more information on configuring the server via the ``paste.deploy``
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 @@ in the following way::
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 @@ shows) a configuration file when starting the server.
.. 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
-----------------

24
doc/source/glance.rst
View File

@ -149,20 +149,20 @@ on our local filesystem in ``/tmp/images/myimage.tar.gz``.
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 @@ information about the metadata that was saved with the image::
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 @@ image. You use this command like so::
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 @@ The ``delete`` command
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
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
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
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 @@ The ``clear`` command is an administrative command that deletes **ALL** images
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.