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 * Using the ``glance-control`` server daemon wrapper program
We recommend using the second way.
Manually starting the server 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`` Glance ships with an ``etc/`` directory that contains sample ``paste.deploy``
configuration files that you can copy to a standard configuation directory and 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 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 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 * /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 $> glance-api
ERROR: Unable to locate any configuration file. Cannot load application 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 Here is an example showing how you can manually start the ``glance-api`` server and ``glance-registry`` in a shell.::
in a shell.::
$> sudo glance-api etc/glance.conf.sample --debug $ sudo glance-api glance.conf --debug &
2011-02-09 14:58:29 DEBUG [glance-api] ******************************************************************************** jsuh@mc-ats1:~$ 2011-04-13 14:50:12 DEBUG [glance-api] ********************************************************************************
2011-02-09 14:58:29 DEBUG [glance-api] Configuration options gathered from config file: 2011-04-13 14:50:12 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-04-13 14:50:12 DEBUG [glance-api] /home/jsuh/glance.conf
2011-02-09 14:58:29 DEBUG [glance-api] ================================================ 2011-04-13 14:50:12 DEBUG [glance-api] ================================================
2011-02-09 14:58:29 DEBUG [glance-api] bind_host 0.0.0.0 2011-04-13 14:50:12 DEBUG [glance-api] bind_host 65.114.169.29
2011-02-09 14:58:29 DEBUG [glance-api] bind_port 9292 2011-04-13 14:50:12 DEBUG [glance-api] bind_port 9292
2011-02-09 14:58:29 DEBUG [glance-api] debug True 2011-04-13 14:50:12 DEBUG [glance-api] debug True
2011-02-09 14:58:29 DEBUG [glance-api] default_store file 2011-04-13 14:50:12 DEBUG [glance-api] default_store file
2011-02-09 14:58:29 DEBUG [glance-api] filesystem_store_datadir /var/lib/glance/images/ 2011-04-13 14:50:12 DEBUG [glance-api] filesystem_store_datadir /home/jsuh/images/
2011-02-09 14:58:29 DEBUG [glance-api] registry_host 0.0.0.0 2011-04-13 14:50:12 DEBUG [glance-api] registry_host 65.114.169.29
2011-02-09 14:58:29 DEBUG [glance-api] registry_port 9191 2011-04-13 14:50:12 DEBUG [glance-api] registry_port 9191
2011-02-09 14:58:29 DEBUG [glance-api] verbose False 2011-04-13 14:50:12 DEBUG [glance-api] verbose False
2011-02-09 14:58:29 DEBUG [glance-api] ******************************************************************************** 2011-04-13 14:50:12 DEBUG [glance-api] ********************************************************************************
2011-02-09 14:58:29 DEBUG [routes.middleware] Initialized with method overriding = True, and path info altering = True 2011-04-13 14:50:12 DEBUG [routes.middleware] Initialized with method overriding = True, and path info altering = True
(16333) wsgi starting up on http://0.0.0.0:9292/ 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 Simply supply the configuration file as the first argument
(``etc/glance.conf.sample`` in the above example) and then any common options (``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 configuration files, see the section entitled
:doc:`Configuring Glance servers <configuring>` :doc:`Configuring Glance servers <configuring>`
Note that the server does not `daemonize` itself when run manually Note that the server `daemonizes` itself by using the standard
from the terminal. You can force the server to daemonize using the standard shell backgrounding indicator, ``&``, in the previous example. For most use cases, we recommend
shell backgrounding indicator, ``&``. However, for most use cases, we recommend
using the ``glance-control`` server daemon wrapper for daemonizing. See below using the ``glance-control`` server daemon wrapper for daemonizing. See below
for more details on daemonization with ``glance-control``. 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 Here is an example that shows how to start the ``glance-registry`` server
with the ``glance-control`` wrapper script. :: 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`` 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 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:: .. note::
To start all the Glance servers (currently the glance-api and glance-registry To start each of Glance servers (currently the glance-api and glance-registry
programs) at once, you can specify "all" for the <SERVER> programs), you can specify glance-api and glance-registry, respectively for the <SERVER>.
Stopping a 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 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. 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 If Glance was able to successfully upload and store your VM image data and
metadata attributes, you would see something like this:: 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 Added new image with ID: 2
You can use the ``--verbose`` (or ``-v``) command-line option to print some more You can use the ``--verbose`` (or ``-v``) command-line option to print some more
information about the metadata that was saved with the image:: 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 Added new image with ID: 4
Returned the following metadata for the new image: Returned the following metadata for the new image:
container_format => ovf 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`` 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:: 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: Dry run. We would have done the following:
Add new image with metadata: Add new image with metadata:
container_format => ovf 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 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:: 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 Updated image 5
Using the ``--verbose`` flag will show you all the updated data about the image:: 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 5
Updated image metadata for image 5: Updated image metadata for image 5:
URI: http://example.com/images/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:: 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 Deleted image 5
The ``index`` command The ``index`` command
@ -282,7 +282,7 @@ The ``index`` command
The ``index`` command displays brief information about the *public* images The ``index`` command displays brief information about the *public* images
available in Glance, as shown below:: available in Glance, as shown below::
$> glance index $> glance index --host=65.114.169.29
Found 4 public images... Found 4 public images...
ID Name Disk Format Container Format Size ID Name Disk Format Container Format Size
---------------- ------------------------------ -------------------- -------------------- -------------- ---------------- ------------------------------ -------------------- -------------------- --------------
@ -297,7 +297,7 @@ The ``details`` command
The ``details`` command displays detailed information about the *public* images The ``details`` command displays detailed information about the *public* images
available in Glance, as shown below:: available in Glance, as shown below::
$> glance details $> glance details --host=65.114.169.29
Found 4 public images... Found 4 public images...
================================================================================ ================================================================================
URI: http://example.com/images/1 URI: http://example.com/images/1
@ -349,7 +349,7 @@ The ``show`` command
The ``show`` command displays detailed information about a specific image, specified The ``show`` command displays detailed information about a specific image, specified
with ``<ID>``, as shown below:: with ``<ID>``, as shown below::
$> glance show 3 $> glance show 3 --host=65.114.169.29
URI: http://example.com/images/3 URI: http://example.com/images/3
Id: 3 Id: 3
Public? Yes 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 and all image metadata. Passing the ``--verbose`` command will print brief
information about all the images that were deleted, as shown below:: 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 1 "Some web image" ... done
Deleting image 2 "Some other web image" ... done Deleting image 2 "Some other web image" ... done
Completed in 0.0328 sec. Completed in 0.0328 sec.