openstack/glance
Code Issues Proposed changes

Drop deprecated client docs

Browse Source 
Link out to the necessary python-glanceclient resources rather than
maintain docs on legacy usage.

Related to bp glance-folsom-docs-cleanup

Change-Id: I769cd21b900df353e7eee3d675989b1ad32f8edf
This commit is contained in:
Brian Waldon 2012-08-22 19:17:46 -07:00
parent 087046b4e6
commit 37dc071dcd
4 changed files with 27 additions and 982 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

371
doc/source/client.rst
View File

@ -1,371 +0,0 @@
..
Copyright 2010 OpenStack, LLC
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Using Glance Programmatically with Glance's Client
==================================================
While it is perfectly acceptable to issue HTTP requests directly to Glance
via its RESTful API, sometimes it is better to be able to access and modify
image resources via a client class that removes some of the complexity and
tedium of dealing with raw HTTP requests.
Glance includes a client class for just this purpose. You can retrieve
metadata about an image, change metadata about an image, remove images, and
of course retrieve an image itself via this client class.
Below are some examples of using Glance's Client class. We assume that
there is a Glance server running at the address `glance.example.com`
on port `9292`.
Requesting a List of Public VM Images
-------------------------------------
We want to see a list of available virtual machine images that the Glance
server knows about.
Using Glance's Client, we can do this using the following code
.. code-block:: python
from glance.client import Client
c = Client("glance.example.com", 9292)
print c.get_images()
Requesting Detailed Metadata on Public VM Images
------------------------------------------------
We want to see more detailed information on available virtual machine images
that the Glance server knows about.
Using Glance's Client, we can do this using the following code
.. code-block:: python
from glance.client import Client
c = Client("glance.example.com", 9292)
print c.get_images_detailed()
Filtering Images Returned via ``get_images()`` and ``get_images_detailed()``
----------------------------------------------------------------------------
Both the ``get_images()`` and ``get_images_detailed()`` methods take query
parameters that serve to filter the returned list of images.
When calling, simply pass an optional dictionary to the method containing
the filters by which you wish to limit results, with the filter keys being one
or more of the below:
* ``name: NAME``
Filters images having a ``name`` attribute matching ``NAME``.
* ``container_format: FORMAT``
Filters images having a ``container_format`` attribute matching ``FORMAT``
For more information, see :doc:`About Disk and Container Formats <formats>`
* ``disk_format: FORMAT``
Filters images having a ``disk_format`` attribute matching ``FORMAT``
For more information, see :doc:`About Disk and Container Formats <formats>`
* ``status: STATUS``
Filters images having a ``status`` attribute matching ``STATUS``
For more information, see :doc:`About Image Statuses <statuses>`
* ``size_min: BYTES``
Filters images having a ``size`` attribute greater than or equal to ``BYTES``
* ``size_max: BYTES``
Filters images having a ``size`` attribute less than or equal to ``BYTES``
Here's a quick example that will return all images less than or equal to 5G
in size and in the `saving` status.
.. code-block:: python
from glance.client import Client
c = Client("glance.example.com", 9292)
filters = {'status': 'saving', 'size_max': 5368709120}
print c.get_images_detailed(filters=filters)
Sorting Images Returned via ``get_images()`` and ``get_images_detailed()``
--------------------------------------------------------------------------
Two parameters are available to sort the list of images returned by
these methods.
* ``sort_key: KEY``
Images can be ordered by the image attribute ``KEY``. Acceptable values:
``id``, ``name``, ``status``, ``container_format``, ``disk_format``,
``created_at`` (default) and ``updated_at``.
* ``sort_dir: DIR``
The direction of the sort may be defined by ``DIR``. Accepted values:
``asc`` for ascending or ``desc`` (default) for descending.
The following example will return a list of images sorted alphabetically
by name in ascending order.
.. code-block:: python
from glance.client import Client
c = Client("glance.example.com", 9292)
print c.get_images(sort_key='name', sort_dir='asc')
Requesting Detailed Metadata on a Specific Image
------------------------------------------------
We want to see detailed information for a specific virtual machine image
that the Glance server knows about.
We have queried the Glance server for a list of public images and the
data returned includes the `id` field for each available image. This
`id` field value is needed to get the metadata for a specific image.
In order to get metadata for a specific image using an id, we can use the
following code
.. code-block:: python
from glance.client import Client
c = Client("glance.example.com", 9292)
print c.get_image_meta("71c675ab-d94f-49cd-a114-e12490b328d9")
Retrieving a Virtual Machine Image
----------------------------------
We want to retrieve that actual raw data for a specific virtual machine image
that the Glance server knows about.
Continuing the example from above, in order to get both the metadata about the
first public image returned and its image data, we can use the following code
.. code-block:: python
from glance.client import Client
c = Client("glance.example.com", 9292)
meta, image_file = c.get_image("71c675ab-d94f-49cd-a114-e12490b328d9")
print meta
f = open('some_local_file', 'wb')
for chunk in image_file:
f.write(chunk)
f.close()
.. note::
The return from Client.get_image is a tuple of (`metadata`, `file`)
where `metadata` is a mapping of metadata about the image and `file` is a
generator that yields chunks of image data.
Adding a New Virtual Machine Image
----------------------------------
We have created a new virtual machine image in some way (created a
"golden" image or snapshotted/backed up an existing image) and we
wish to do two things:
* Store the disk image data in Glance
* Store metadata about this image in Glance
We can do the above two activities in a single call to the Glance client.
Assuming, like in the examples above, that a Glance API server is running
at `glance.example.com`, we issue a call to `glance.client.Client.add_image`.
The method signature is as follows::
glance.client.Client.add_image(image_meta, image_data=None)
The `image_meta` argument is a dictionary containing various image metadata.
The keys in this dictionary map directly to the 'x-image-meta-*' headers
accepted in the Glance API. Simply drop the leading 'x-image-meta-' from each
header to determine what key should be used in the metadata dictionary. See the
:doc:`API docs <glanceapi>` for a complete list of acceptable attributes.
The `image_data` argument is the disk image data and is an optional argument.
As a complete example, the following code would add a new machine image to
Glance
.. code-block:: python
from glance.client import Client
c = Client("glance.example.com", 9292)
meta = {'name': 'Ubuntu 10.10 5G',
'container_format': 'ovf',
'disk_format': 'vhd',
'is_public': True,
'properties': {'distro': 'Ubuntu 10.10'}}
new_meta = c.add_image(meta, open('/path/to/image.tar.gz'))
print 'Stored image. Got identifier: %s' % new_meta['id']
Requesting Image Memberships
----------------------------
We want to see a list of the other system tenants that may access a given
virtual machine image that the Glance server knows about.
Continuing from the example above, in order to get the memberships for the
image with ID '71c675ab-d94f-49cd-a114-e12490b328d9', we can use the
following code
.. code-block:: python
from glance.client import Client
c = Client("glance.example.com", 9292)
members = c.get_image_members('71c675ab-d94f-49cd-a114-e12490b328d9')
.. note::
The return from Client.get_image_members() is a list of dictionaries. Each
dictionary has a `member_id` key, mapping to the tenant the image is shared
with, and a `can_share` key, mapping to a boolean value that identifies
whether the member can further share the image.
Requesting Member Images
------------------------
We want to see a list of the virtual machine images a given system tenant may
access.
Continuing from the example above, in order to get the images shared with
'tenant1', we can use the following code
.. code-block:: python
from glance.client import Client
c = Client("glance.example.com", 9292)
images = c.get_member_images('tenant1')
.. note::
The return from Client.get_member_images() is a list of dictionaries. Each
dictionary has an `image_id` key, mapping to an image shared with the member,
and a `can_share` key, mapping to a boolean value that identifies whether
the member can further share the image.
Adding a Member To an Image
---------------------------
We want to authorize a tenant to access a private image.
Continuing from the example above, in order to share the image with ID
'71c675ab-d94f-49cd-a114-e12490b328d9' with 'tenant1', and to allow
'tenant2' to not only access the image but to also share it with other
tenants, we can use the following code
.. code-block:: python
from glance.client import Client
c = Client("glance.example.com", 9292)
c.add_member('71c675ab-d94f-49cd-a114-e12490b328d9', 'tenant1')
c.add_member('71c675ab-d94f-49cd-a114-e12490b328d9', 'tenant2', True)
.. note::
The Client.add_member() function takes one optional argument, the `can_share`
value. If one is not provided and the membership already exists, its current
`can_share` setting is left alone. If the membership does not already exist,
then the `can_share` setting will default to `False`, and the membership will
be created. In all other cases, existing memberships will be modified to use
the specified `can_share` setting, and new memberships will be created with
it. The return value of Client.add_member() is not significant.
Removing a Member From an Image
-------------------------------
We want to revoke a tenant's authorization to access a private image.
Continuing from the example above, in order to revoke the access of 'tenant1'
to the image with ID '71c675ab-d94f-49cd-a114-e12490b328d9', we can use
the following code
.. code-block:: python
from glance.client import Client
c = Client("glance.example.com", 9292)
c.delete_member('71c675ab-d94f-49cd-a114-e12490b328d9', 'tenant1')
.. note::
The return value of Client.delete_member() is not significant.
Replacing a Membership List For an Image
----------------------------------------
All existing image memberships may be revoked and replaced in a single
operation.
Continuing from the example above, in order to replace the membership list
of the image with ID '71c675ab-d94f-49cd-a114-e12490b328d9' with two
entries--the first allowing 'tenant1' to access the image, and the second
allowing 'tenant2' to access and further share the image, we can use the
following code
.. code-block:: python
from glance.client import Client
c = Client("glance.example.com", 9292)
c.replace_members('71c675ab-d94f-49cd-a114-e12490b328d9',
{'member_id': 'tenant1', 'can_share': False},
{'member_id': 'tenant2', 'can_share': True})
.. note::
The first argument to Client.replace_members() is the opaque identifier of
the image; the remaining arguments are dictionaries with the keys
`member_id` (mapping to a tenant name) and `can_share`. Note that
`can_share` may be omitted, in which case any existing membership for the
specified member will be preserved through the replace operation.
The return value of Client.replace_members() is not significant.

609
doc/source/glance.rst
View File

@ -1,609 +0,0 @@
..
Copyright 2011 OpenStack, LLC
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Using the Glance CLI Tool
=========================
Glance ships with a command-line tool for querying and managing Glance.
It has a fairly simple but powerful interface of the form::
Usage: glance <command> [options] [args]
Where ``<command>`` is one of the following:
* ``help``
Show detailed help information about a specific command
* ``add``
Adds an image to Glance
* ``update``
Updates an image's stored metadata in Glance
* ``delete``
Deletes an image and its metadata from Glance
* ``index``
Lists brief information about *public* images that Glance knows about
* ``details``
Lists detailed information about *public* images that Glance knows about
* ``show``
Lists detailed information about a specific image
* ``clear``
Destroys all **public** images and their associated metadata
This document describes how to use the ``glance`` tool for each of
the above commands.
The ``help`` command
--------------------
Issuing the ``help`` command with a ``<COMMAND>`` argument shows detailed help
about a specific command. Running ``glance`` without any arguments shows
a brief help message, like so::
$> glance
Usage: glance <command> [options] [args]
Commands:
help <command> Output help for one of the commands below
add Adds a new image to Glance
update Updates an image's metadata in Glance
delete Deletes an image from Glance
index Return brief information about images in Glance
details Return detailed information about images in
Glance
show Show detailed information about an image in
Glance
clear Removes all images and metadata from Glance
Member Commands:
image-members List members an image is shared with
member-images List images shared with a member
member-add Grants a member access to an image
member-delete Revokes a member's access to an image
members-replace Replaces all membership for an image
Options:
--version show program's version number and exit
-h, --help show this help message and exit
--silent-upload disable progress bar animation and information during
upload
-v, --verbose Print more verbose output
-d, --debug Print more verbose output
-H ADDRESS, --host=ADDRESS
Address of Glance API host. Default: 0.0.0.0
-p PORT, --port=PORT Port the Glance API host listens on. Default: 9292
-U URL, --url=URL URL of Glance service. This option can be used to
specify the hostname, port and protocol (http/https)
of the glance server, for example -U
https://localhost:9292/v1 Default: None
-k, --insecure Explicitly allow glance to perform "insecure" SSL
(https) requests. The server's certificate will not be
verified against any certificate authorities. This
option should be used with caution.
-A TOKEN, --os_auth_token=TOKEN
Authentication token to use to identify the client to
the glance server
-I USER, --os_username=USER
User name used to acquire an authentication token
-K PASSWORD, --os_password=PASSWORD
Password used to acquire an authentication token
-R REGION, --os_region_name=REGION
Region name. When using keystone authentication
version 2.0 or later this identifies the region name
to use when selecting the service endpoint. A region
name must be provided if more than one region endpoint
is available
-T TENANT, --os_tenant_name=TENANT
Tenant name
-N AUTH_URL, --os_auth_url=AUTH_URL
Authentication URL
-S STRATEGY, --os_auth_strategy=STRATEGY
Authentication strategy (keystone or noauth)
--limit=LIMIT Page size to use while requesting image metadata
--marker=MARKER Image index after which to begin pagination
--sort_key=KEY Sort results by this image attribute.
--sort_dir=[desc|asc]
Sort results in this direction.
-f, --force Prevent select actions from requesting user
confirmation
--dry-run Don't actually execute the command, just print output
showing what WOULD happen.
--can-share Allow member to further share image.
With a ``<COMMAND>`` argument, more information on the command is shown,
like so::
$> glance help update
glance update [options] <ID> <field1=value1 field2=value2 ...>
Updates an image's metadata in Glance. Specify metadata fields as arguments.
Metadata fields that are not specified in the update command will be deleted.
All field/value pairs are converted into a mapping that is passed
to Glance that represents the metadata for an image.
Field names that can be specified:
name A name for the image.
location An external location to serve out from.
copy_from An external location (HTTP, S3 or Swift URI) to copy image
content from.
is_public If specified, interpreted as a boolean value
and sets or unsets the image's availability to the public.
protected If specified, interpreted as a boolean value
and enables or disables deletion protection for the image.
disk_format Format of the disk image
container_format Format of the container
All other field names are considered to be custom properties so be careful
to spell field names correctly.
.. _glance-add:
The ``add`` command
-------------------
The ``add`` command is used to do both of the following:
* Store virtual machine image data and metadata about that image in Glance
* Let Glance know about an existing virtual machine image that may be stored
somewhere else
We cover both use cases below.
Important Information about Uploading Images
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Before we go over the commands for adding an image to Glance, it is
important to understand that Glance **does not currently inspect** the image
files you add to it. In other words, **Glance only understands what you tell it,
via attributes and custom properties**.
If the file extension of the file you upload to Glance ends in '.vhd', Glance
**does not** know that the image you are uploading has a disk format of ``vhd``.
You have to **tell** Glance that the image you are uploading has a disk format
by using the ``disk_format=vhd`` on the command line (see more below).
By the same token, Glance does not currently allow you to upload "multi-part"
disk images at once. **The common operation of bundling a kernel image and
ramdisk image into a machine image is not done automagically by Glance.**
Store virtual machine image data and metadata
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When adding an actual virtual machine image to Glance, you use the ``add``
command. You will pass metadata about the VM image on the command line, and
you will use a standard shell redirect to stream the image data file to
``glance``.
Let's walk through a simple example. Suppose we have a virtual disk image
in qcow2 format stored on our local filesystem at ``/tmp/images/myimage.img``.
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::
$> glance add name="My Image" is_public=true \
container_format=bare disk_format=qcow2 < /tmp/images/myimage.img
Note that the disk container formats are no longer defaulted and are thus
strictly required. However, if only one of disk or container format is specified
and is in Amazon format, the other parameter defaults to the specified
disk or container format value.
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 \
container_format=bare disk_format=qcow2 < /tmp/images/myimage.img
Added new image with ID: 991baaf9-cc0d-4183-a201-8facdf1a1430
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 \
container_format=bare disk_format=qcow2 < /tmp/images/myimage.img
Added new image with ID: 541424be-27b1-49d6-a55b-6430b8ae0f5f
Returned the following metadata for the new image:
checksum => 2cec138d7dae2aa59038ef8c9aec2390
container_format => bare
created_at => 2011-02-22T19:20:53.298556
deleted => False
deleted_at => None
disk_format => qcow2
id => 541424be-27b1-49d6-a55b-6430b8ae0f5f
is_public => True
min_disk => 0
min_ram => 0
name => My Image
owner => tenant1
properties => {}
protected => False
size => 58520278
status => active
updated_at => 2011-02-22T19:20:54.451291
Completed in 0.6141 sec.
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_public=True \
container_format=bare disk_format=qcow2 < /tmp/images/myimage.img
Dry run. We would have done the following:
Add new image with metadata:
container_format => bare
disk_format => qcow2
id => None
is_public => False
min_disk => 0
min_ram => 0
name => Foo
properties => {'is_public': 'True', 'distro': 'Ubuntu'}
protected => False
This is useful for detecting problems and for seeing what the default field
values supplied by ``glance`` are. For instance, there was a typo in
the command above (the ``is_public`` field was incorrectly spelled ``is_public``
which resulted in the image having an ``is_public`` custom property added to
the image and the *real* ``is_public`` field value being `False` (the default)
and not `True`...
Examples of uploading different kinds of images
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To upload an EC2 tarball VM image::
$> glance add name="ubuntu-10.10-amd64" is_public=true \
container_format=ovf disk_format=raw \
< maverick-server-uec-amd64.tar.gz
To upload an EC2 tarball VM image with an associated property (e.g., distro)::
$> glance add name="ubuntu-10.10-amd64" is_public=true \
container_format=ovf disk_format=raw \
distro="ubuntu 10.10" < /root/maverick-server-uec-amd64.tar.gz
To reference an EC2 tarball VM image available at an external URL::
$> glance add name="ubuntu-10.04-amd64" is_public=true \
container_format=ovf disk_format=raw \
location="http://uec-images.ubuntu.com/lucid/current/\
lucid-server-uec-amd64.tar.gz"
To upload a copy of that same EC2 tarball VM image::
$> glance add name="ubuntu-10.04-amd64" is_public=true \
container_format=bare disk_format=raw \
copy_from="http://uec-images.ubuntu.com/lucid/current/lucid-server-uec-amd64.tar.gz"
To upload a qcow2 image::
$> glance add name="ubuntu-11.04-amd64" is_public=true \
container_format=bare disk_format=qcow2 \
distro="ubuntu 11.04" < /data/images/rock_natty.qcow2
To upload kernel, ramdisk and machine image files::
$> glance add disk_format=aki container_format=aki \
name="maverick-server-uec-amd64-vmlinuz-virtual" \
< maverick-server-uec-amd64-vmlinuz-virtual
$> glance add disk_format=ari container_format=ari \
name="maverick-server-uec-amd64-loader" \
< maverick-server-uec-amd64-loader
# Determine what the ids associated with the kernel and ramdisk files
$> glance index
# Assuming the ids are 94c2adcf-1bca-4881-92f1-62fe7593f108 and 6e75405d-7de0-4c99-b936-87f98ff4959f:
$> glance add disk_format=ami container_format=ami \
name="maverick-server-uec-amd64" \
kernel_id=94c2adcf-1bca-4881-92f1-62fe7593f108 \
ramdisk_id=6e75405d-7de0-4c99-b936-87f98ff4959f \
< maverick-server-uec-amd64.img
To upload a raw image file::
$> glance add disk_format=raw container_format=bare \
name="maverick-server-uec-amd64.img_v2" < maverick-server-uec-amd64.img
Register a virtual machine image in another location
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sometimes, you already have stored the virtual machine image in some non-Glance
location -- perhaps even a location you have no write access to -- and you want
to tell Glance where this virtual machine image is located and some metadata
about it. The ``add`` command can do this for you.
When registering an image in this way, the only difference is that you do not
use a shell redirect to stream a virtual machine image file into Glance, but
instead, you tell Glance where to find the existing virtual machine image by
setting the ``location`` field. Below is an example of doing this.
Let's assume that there is a virtual machine image located at the URL
``http://example.com/images/myimage.vhd``. We can register this image with
Glance using the following::
$> glance add name="Some web image" disk_format=vhd \
container_format=ovf location="http://example.com/images/myimage.vhd"
Added new image with ID: 71c675ab-d94f-49cd-a114-e12490b328d9
The ``update`` command
----------------------
After uploading/adding a virtual machine image to Glance, it is not possible to
modify the actual virtual machine image -- images are read-only after all --
however, it *is* possible to update any metadata about the image after you add
it to Glance.
The ``update`` command allows you to update the metadata fields of a stored
image. You use this command like so::
glance update <ID> [field1=value1 field2=value2 ...]
Let's say we have an image with identifier
'9afc4097-1c70-45c3-8c12-1b897f083faa' that we wish to change the 'is_public'
attribute of the image from False to True. The following would accomplish this::
$> glance update 9afc4097-1c70-45c3-8c12-1b897f083faa is_public=true
Updated image 9afc4097-1c70-45c3-8c12-1b897f083faa
Using the ``--verbose`` flag will show you all the updated data about the
image::
$> glance --verbose update 97243446-9c74-42af-a31a-34ba16555868 \
is_public=true
Updated image 97243446-9c74-42af-a31a-34ba16555868
Updated image metadata for image 97243446-9c74-42af-a31a-34ba16555868:
URI: http://glance.example.com/v1/images/97243446-9c74-42af-a31a-34ba16555868
Id: 97243446-9c74-42af-a31a-34ba16555868
Public: Yes
Protected: No
Name: My Image
Status: active
Size: 58520278
Disk format: raw
Container format: ovf
Minimum Ram Required (MB): 0
Minimum Disk Required (GB): 0
Owner: tenant1
Completed in 0.0596 sec.
The ``delete`` command
----------------------
You can delete an image by using the ``delete`` command, shown below::
$> glance --verbose -f delete 660c96a7-ef95-45e7-8e48-595df6937675
Delete image 660c96a7-ef95-45e7-8e48-595df6937675? [y/N] y
Deleted image 660c96a7-ef95-45e7-8e48-595df6937675
The ``index`` command
---------------------
The ``index`` command displays brief information about public images available
in Glance alongside any private images you can access, as shown below::
$> glance index
ID Name Disk Format Container Format Size
------------------------------------ ------------------------------ -------------------- -------------------- --------------
baa87554-34d2-4e9e-9949-e9e5620422bb Ubuntu 10.10 vhd ovf 58520278
9e1aede2-dc6e-4981-9f3e-93dee24d48b1 Ubuntu 10.04 ami ami 58520278
771c0223-27b4-4789-a83d-79eb9c166578 Fedora 9 vdi bare 3040
cb8f4908-ef58-4e4b-884e-517cf09ead86 Vanilla Linux 2.6.22 qcow2 bare 0
Image metadata such as 'name', 'disk_format', 'container_format' and 'status'
may be used to filter the results of an index or details command. These
commands also accept 'size_min' and 'size_max' as lower and upper bounds
of the image attribute 'size.' Any unrecognized fields are handled as
custom image properties.
The 'limit' and 'marker' options are used by the index and details commands
to control pagination. The 'marker' indicates the last record that was seen
by the user. The page of results returned will begin after the provided image
ID. The 'limit' param indicates the page size. Each request to the api will be
restricted to returning a maximum number of results. Without the 'force'
option, the user will be prompted before each page of results is fetched
from the API.
Results from index and details commands may be ordered using the 'sort_key'
and 'sort_dir' options. Any image attribute may be used for 'sort_key',
while only 'asc' or 'desc' are allowed for 'sort_dir'.
The ``details`` command
-----------------------
The ``details`` command displays detailed information about the *public* images
available in Glance, as shown below::
$> glance details
==============================================================================
URI: http://example.com/images/baa87554-34d2-4e9e-9949-e9e5620422bb
Id: baa87554-34d2-4e9e-9949-e9e5620422bb
Public: Yes
Protected: No
Name: Ubuntu 10.10
Status: active
Size: 58520278
Disk format: vhd
Container format: ovf
Minimum Ram Required (MB): 0
Minimum Disk Required (GB): 0
Owner: None
Property 'distro_version': 10.10
Property 'distro': Ubuntu
==============================================================================
URI: http://example.com/images/9e1aede2-dc6e-4981-9f3e-93dee24d48b1
Id: 9e1aede2-dc6e-4981-9f3e-93dee24d48b1
Public: Yes
Protected: No
Name: Ubuntu 10.04
Status: active
Size: 58520278
Disk format: ami
Container format: ami
Minimum Ram Required (MB): 0
Minimum Disk Required (GB): 0
Owner: None
Property 'distro_version': 10.04
Property 'distro': Ubuntu
==============================================================================
URI: http://example.com/images/771c0223-27b4-4789-a83d-79eb9c166578
Id: 771c0223-27b4-4789-a83d-79eb9c166578
Public: Yes
Protected: No
Name: Fedora 9
Status: active
Size: 3040
Disk format: vdi
Container format: bare
Minimum Ram Required (MB): 512
Minimum Disk Required (GB): 10
Owner: None
Property 'distro_version': 9
Property 'distro': Fedora
==============================================================================
URI: http://example.com/images/cb8f4908-ef58-4e4b-884e-517cf09ead86
Id: cb8f4908-ef58-4e4b-884e-517cf09ead86
Public: Yes
Protected: No
Name: Vanilla Linux 2.6.22
Status: active
Size: 0
Disk format: qcow2
Container format: bare
Minimum Ram Required (MB): 0
Minimum Disk Required (GB): 0
Owner: tenant1
==============================================================================
The ``show`` command
--------------------
The ``show`` command displays detailed information about a specific image,
specified with ``<ID>``, as shown below::
$> glance show 771c0223-27b4-4789-a83d-79eb9c166578
URI: http://example.com/images/771c0223-27b4-4789-a83d-79eb9c166578
Id: 771c0223-27b4-4789-a83d-79eb9c166578
Public: Yes
Protected: No
Name: Fedora 9
Status: active
Size: 3040
Disk format: vdi
Container format: bare
Minimum Ram Required (MB): 512
Minimum Disk Required (GB): 10
Owner: None
Property 'distro_version': 9
Property 'distro': Fedora
The ``clear`` command
---------------------
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
Deleting image ab15b8d3-8f33-4467-abf2-9f89a042a8c4 "Some web image" ... done
Deleting image dc9698b4-e9f1-4f75-b777-1a897633e488 "Some other web image" ... done
Completed in 0.0328 sec.
The ``image-members`` Command
-----------------------------
The ``image-members`` command displays the list of members with which a
specific image, specified with ``<ID>``, is shared, as shown below::
$> glance image-members ab15b8d3-8f33-4467-abf2-9f89a042a8c4
tenant1
tenant2 *
(*: Can share image)
The ``member-images`` Command
-----------------------------
The ``member-images`` command displays the list of images which are shared
with a specific member, specified with ``<MEMBER>``, as shown below::
$> glance member-images tenant1
ab15b8d3-8f33-4467-abf2-9f89a042a8c4
dc9698b4-e9f1-4f75-b777-1a897633e488 *
(*: Can share image)
The ``member-add`` Command
--------------------------
The ``member-add`` command grants a member, specified with ``<MEMBER>``, access
to a private image, specified with ``<ID>``. The ``--can-share`` flag can be
given to allow the member to share the image, as shown below::
$> glance member-add ab15b8d3-8f33-4467-abf2-9f89a042a8c4 tenantId1
$> glance member-add ab15b8d3-8f33-4467-abf2-9f89a042a8c4 tenantId2 --can-share
The ``member-delete`` Command
-----------------------------
The ``member-delete`` command revokes the access of a member, specified with
``<MEMBER>``, to a private image, specified with ``<ID>``, as shown below::
$> glance member-delete ab15b8d3-8f33-4467-abf2-9f89a042a8c4 tenant1
$> glance member-delete ab15b8d3-8f33-4467-abf2-9f89a042a8c4 tenant2
The ``members-replace`` Command
-------------------------------
The ``members-replace`` command revokes all existing memberships on a private
image, specified with ``<ID>``, and replaces them with a membership for one
member, specified with ``<MEMBER>``. The ``--can-share`` flag can be given to
allow the member to share the image, as shown below::
$> glance members-replace ab15b8d3-8f33-4467-abf2-9f89a042a8c4 tenant1 \
--can-share
The command is given in plural form to make it clear that all existing
memberships are affected by the command.

26
doc/source/glanceclient.rst Normal file
View File

@ -0,0 +1,26 @@
..
Copyright 2011-2012 OpenStack, LLC
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Using Glance's Client Tools
===========================
The command-line tool and python library for Glance are both installed
through the python-glanceclient project. Explore the following resources
for more information:
* `Official Docs <http://docs.openstack.org/developer/python-glanceclient/>`_
* `Pypi Page <http://pypi.python.org/pypi/python-glanceclient>`_
* `GitHub Project <http://github.com/openstack/python-glanceclient>`_

3
doc/source/index.rst
View File

@ -70,9 +70,8 @@ Using Glance
.. toctree::
:maxdepth: 1
glance
glanceclient
glanceapi
client
Developer Docs
==============