From ce33576e832fa933bfb381b5806ea2c49026bc3c Mon Sep 17 00:00:00 2001 From: Brian Waldon Date: Tue, 13 Mar 2012 18:57:41 -0700 Subject: [PATCH] Update cli docs * Add current examples * Remove happiness * Remove extraneous example flags Change-Id: Ia41d2b4763bba58ef60f140b24a0c925a8d68fca --- bin/glance | 4 +- doc/source/glance.rst | 239 +++++++++++++++++++++++++----------------- 2 files changed, 144 insertions(+), 99 deletions(-) diff --git a/bin/glance b/bin/glance index a86a08bdb5..518ecb6c47 100755 --- a/bin/glance +++ b/bin/glance @@ -190,7 +190,7 @@ copy_from Optional. An external location (HTTP, S3 or Swift URI) to copy_from=s3://akey:skey@s3.amazonaws.com/images/fedora16 Any other field names are considered to be custom properties so be careful -to spell field names correctly. :) +to spell field names correctly. STREAMING IMAGE DATA =============================================================================== @@ -332,7 +332,7 @@ 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. :)""" +to spell field names correctly.""" c = get_client(options) try: image_id = args.pop(0) diff --git a/doc/source/glance.rst b/doc/source/glance.rst index 0f4c30b963..fd847fc9db 100644 --- a/doc/source/glance.rst +++ b/doc/source/glance.rst @@ -17,7 +17,7 @@ Using the Glance CLI Tool ========================= -Glance ships with a command-line tool for querying and managing Glance +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] @@ -89,27 +89,56 @@ a brief help message, like so:: 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: example.com + 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 - requests. The server certificate will not be - verified against any certificate authorities. - This option should be used with caution. + -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, --auth_token=TOKEN + Authentication token to use to identify the client to + the glance server + -I USER, --username=USER + User name used to acquire an authentication token + -K PASSWORD, --password=PASSWORD + Password used to acquire an authentication token -R REGION, --region=REGION - When using keystone authentication version 2.0 - or later this identifies the region name to - use when selecting the service endpoint. Where - more than one region endpoint is available a - region must be provided. + 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, --tenant=TENANT + Tenant name + -N AUTH_URL, --auth_url=AUTH_URL + Authentication URL + -S STRATEGY, --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. @@ -119,6 +148,7 @@ a brief help message, like so:: 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:: @@ -129,19 +159,26 @@ like so:: 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. - disk_format Format of the disk image (required) - container_format Format of the container (required) + 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. :) + to spell field names correctly. .. _glance-add: @@ -183,18 +220,13 @@ 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 -stored on our local filesystem that we wish to "upload" to Glance. This image -is stored on our local filesystem in ``/tmp/images/myimage.iso``. - -We'd also like to tell Glance that this image should be called "My Image", and +stored on our local filesystem at ``/tmp/images/myimage.iso``. 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. Change example IP number to your -server IP number.:: +Here is how we'd upload this image to Glance:: $> glance add name="My Image" is_public=true \ - container_format=ovf disk_format=raw \ - --host=65.114.169.29 < /tmp/images/myimage.iso + container_format=ovf disk_format=raw < /tmp/images/myimage.iso Note that the disk container formats are no longer defaulted and are thus strictly required. @@ -203,18 +235,17 @@ 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=ovf disk_format=raw \ - --host=65.114.169.29 < /tmp/images/myimage.iso + container_format=ovf disk_format=raw < /tmp/images/myimage.iso 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=ovf disk_format=raw \ - --host=65.114.169.29 < /tmp/images/myimage.iso + container_format=ovf disk_format=raw < /tmp/images/myimage.iso Added new image with ID: 541424be-27b1-49d6-a55b-6430b8ae0f5f Returned the following metadata for the new image: + checksum => 2cec138d7dae2aa59038ef8c9aec2390 container_format => ovf created_at => 2011-02-22T19:20:53.298556 deleted => False @@ -222,27 +253,33 @@ information about the metadata that was saved with the image:: disk_format => raw id => 541424be-27b1-49d6-a55b-6430b8ae0f5f is_public => True - location => file:///tmp/images/4 + min_disk => 0 + min_ram => 0 name => My Image + owner => tenant1 properties => {} + protected => False size => 58520278 status => active - updated_at => None + 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=ovf disk_format=raw \ - --host=65.114.169.29 < /tmp/images/myimage.iso + container_format=ovf disk_format=raw < /tmp/images/myimage.iso Dry run. We would have done the following: Add new image with metadata: container_format => ovf disk_format => raw + 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 @@ -257,53 +294,55 @@ 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 \ - < /root/maverick-server-uec-amd64.tar.gz + 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 + 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" + 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=ovf disk_format=raw \ - copy_from="http://uec-images.ubuntu.com/lucid/current/\ - lucid-server-uec-amd64.tar.gz" + container_format=ovf 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=ovf disk_format=qcow2 \ - distro="ubuntu 11.04" < /data/images/rock_natty.qcow2 + container_format=ovf disk_format=qcow2 \ + distro="ubuntu 11.04" < /data/images/rock_natty.qcow2 -To upload a kernel file, ramdisk file and filesystem image file:: +To upload kernel, ramdisk and machine image files:: $> glance add disk_format=aki container_format=aki \ - ./maverick-server-uec-amd64-vmlinuz-virtual \ - maverick-server-uec-amd64-vmlinuz-virtual + name="maverick-server-uec-amd64-vmlinuz-virtual" \ + < maverick-server-uec-amd64-vmlinuz-virtual $> glance add disk_format=ari container_format=ari \ - ./maverick-server-uec-amd64-loader maverick-server-uec-amd64-loader + 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 7 and 8: - $> glance add disk_format=ami container_format=ami kernel_id=7 \ - ramdisk_id=8 ./maverick-server-uec-amd64.img maverick-server-uec-amd64.img + # 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=ovf \ - ./maverick-server-uec-amd64.img maverick-server-uec-amd64.img_v2 - + name="maverick-server-uec-amd64.img_v2" < maverick-server-uec-amd64.img Register a virtual machine image in another location ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -322,24 +361,9 @@ 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 --verbose add name="Some web image" disk_format=vhd \ - container_format=ovf location="http://example.com/images/myimage.vhd" + $> 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 - Returned the following metadata for the new image: - container_format => ovf - created_at => 2011-02-23T00:42:04.688890 - deleted => False - deleted_at => None - disk_format => vhd - id => 71c675ab-d94f-49cd-a114-e12490b328d9 - is_public => True - location => http://example.com/images/myimage.vhd - name => Some web image - properties => {} - size => 0 - status => active - updated_at => None - Completed in 0.0356 sec. The ``update`` command ---------------------- @@ -355,27 +379,31 @@ 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 +'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 \ - --host=65.114.169.29 + $> 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 --host=65.114.169.29 + is_public=true Updated image 97243446-9c74-42af-a31a-34ba16555868 Updated image metadata for image 97243446-9c74-42af-a31a-34ba16555868: - URI: http://example.com/images/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 + 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 @@ -383,17 +411,17 @@ The ``delete`` command You can delete an image by using the ``delete`` command, shown below:: - $> glance --verbose delete 660c96a7-ef95-45e7-8e48-595df6937675 \ - --host=65.114.169.29 -f + $> 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 the *public* images -available in Glance, as shown below:: +The ``index`` command displays brief information about public images available +in Glance alongside any private images you can access, as shown below:: - $> glance index --host=65.114.169.29 + $> glance index ID Name Disk Format Container Format Size ------------------------------------ ------------------------------ -------------------- -------------------- -------------- baa87554-34d2-4e9e-9949-e9e5620422bb Ubuntu 10.10 vhd ovf 58520278 @@ -404,7 +432,7 @@ available in Glance, as shown below:: 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 metadata 'size.' Any unrecognized fields are handled as +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 @@ -426,49 +454,65 @@ The ``details`` command The ``details`` command displays detailed information about the *public* images available in Glance, as shown below:: - $> glance details --host=65.114.169.29 + $> glance details ============================================================================== URI: http://example.com/images/baa87554-34d2-4e9e-9949-e9e5620422bb Id: baa87554-34d2-4e9e-9949-e9e5620422bb - Public? Yes + 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 + 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 + 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 + 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 @@ -477,15 +521,19 @@ 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 --host=65.114.169.29 + $> 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 + 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 @@ -496,7 +544,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 --host=65.114.169.29 + $> 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. @@ -507,8 +555,7 @@ 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 \ - --host=65.114.169.29 + $> glance image-members ab15b8d3-8f33-4467-abf2-9f89a042a8c4 tenant1 tenant2 * @@ -520,7 +567,7 @@ 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 --host=65.114.169.29 + $> glance member-images tenant1 ab15b8d3-8f33-4467-abf2-9f89a042a8c4 dc9698b4-e9f1-4f75-b777-1a897633e488 * @@ -533,10 +580,8 @@ 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 tenant1 \ - --host=65.114.169.29 - $> glance member-add ab15b8d3-8f33-4467-abf2-9f89a042a8c4 tenant2 \ - --can-share --host=65.114.169.29 + $> glance member-add ab15b8d3-8f33-4467-abf2-9f89a042a8c4 tenant1 + $> glance member-add ab15b8d3-8f33-4467-abf2-9f89a042a8c4 tenant2 --can-share The ``member-delete`` Command ----------------------------- @@ -556,7 +601,7 @@ 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 --host=65.114.169.29 + --can-share The command is given in plural form to make it clear that all existing memberships are affected by the command.