From 37dc071dcd8e5c9546e165cb2138475ae39cc294 Mon Sep 17 00:00:00 2001 From: Brian Waldon Date: Wed, 22 Aug 2012 19:17:46 -0700 Subject: [PATCH] Drop deprecated client docs 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 --- doc/source/client.rst | 371 ---------------------- doc/source/glance.rst | 609 ------------------------------------ doc/source/glanceclient.rst | 26 ++ doc/source/index.rst | 3 +- 4 files changed, 27 insertions(+), 982 deletions(-) delete mode 100644 doc/source/client.rst delete mode 100644 doc/source/glance.rst create mode 100644 doc/source/glanceclient.rst diff --git a/doc/source/client.rst b/doc/source/client.rst deleted file mode 100644 index 535a4cda7f..0000000000 --- a/doc/source/client.rst +++ /dev/null @@ -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 ` - -* ``disk_format: FORMAT`` - - Filters images having a ``disk_format`` attribute matching ``FORMAT`` - - For more information, see :doc:`About Disk and Container Formats ` - -* ``status: STATUS`` - - Filters images having a ``status`` attribute matching ``STATUS`` - - For more information, see :doc:`About Image 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 ` 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. diff --git a/doc/source/glance.rst b/doc/source/glance.rst deleted file mode 100644 index cf5b8cf049..0000000000 --- a/doc/source/glance.rst +++ /dev/null @@ -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 [options] [args] - -Where ```` 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 ```` argument shows detailed help -about a specific command. Running ``glance`` without any arguments shows -a brief help message, like so:: - - $> glance - Usage: glance [options] [args] - - Commands: - - help 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 ```` argument, more information on the command is shown, -like so:: - - $> glance help update - - glance update [options] - - 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 [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 ````, 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 ````, 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 ````, 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 ````, access -to a private image, specified with ````. 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 -````, to a private image, specified with ````, 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 ````, and replaces them with a membership for one -member, specified with ````. 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. diff --git a/doc/source/glanceclient.rst b/doc/source/glanceclient.rst new file mode 100644 index 0000000000..4a541ce8dc --- /dev/null +++ b/doc/source/glanceclient.rst @@ -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 `_ +* `Pypi Page `_ +* `GitHub Project `_ diff --git a/doc/source/index.rst b/doc/source/index.rst index b6ada5c8e2..04bead5a9b 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -70,9 +70,8 @@ Using Glance .. toctree:: :maxdepth: 1 - glance + glanceclient glanceapi - client Developer Docs ==============