328 lines
10 KiB
ReStructuredText
328 lines
10 KiB
ReStructuredText
..
|
|
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': (5 * 1024 * 1024 * 1024)}
|
|
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 `uri` field for each available image. This
|
|
`uri` field value contains the exact location needed to get the metadata
|
|
for a specific image.
|
|
|
|
Continuing the example from above, in order to get metadata about the
|
|
first public image returned, 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("http://glance.example.com/images/1")
|
|
|
|
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.
|
|
|
|
We have queried the Glance server for a list of public images and the
|
|
data returned includes the `uri` field for each available image. This
|
|
`uri` field value contains the exact location needed to get the metadata
|
|
for a specific image.
|
|
|
|
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("http://glance.example.com/images/1")
|
|
|
|
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 mapping containing various image metadata.
|
|
The `image_data` argument is the disk image data and is an optional argument.
|
|
|
|
The list of metadata that `image_meta` can contain are listed below.
|
|
|
|
* `name`
|
|
|
|
This key/value is required. Its value should be the name of the image.
|
|
|
|
Note that the name of an image *is not unique to a Glance node*. It
|
|
would be an unrealistic expectation of users to know all the unique
|
|
names of all other user's images.
|
|
|
|
* `id`
|
|
|
|
This key/value is optional.
|
|
|
|
When present, Glance will use the supplied identifier for the image.
|
|
If the identifier already exists in that Glance node, then a
|
|
`glance.common.exception.Duplicate` will be raised.
|
|
|
|
When this key/value is *not* present, Glance will generate an identifier
|
|
for the image and return this identifier in the response (see below)
|
|
|
|
* `store`
|
|
|
|
This key/value is optional. Valid values are one of `file`, `s3` or `swift`
|
|
|
|
When present, Glance will attempt to store the disk image data in the
|
|
backing store indicated by the value. If the Glance node does not support
|
|
the backing store, Glance will raise a `glance.common.exception.BadRequest`
|
|
|
|
When not present, Glance will store the disk image data in the backing
|
|
store that is marked default. See the configuration option `default_store`
|
|
for more information.
|
|
|
|
* `type`
|
|
|
|
This key/values is required. Valid values are one of `kernel`, `machine`,
|
|
`raw`, or `ramdisk`.
|
|
|
|
* `size`
|
|
|
|
This key/value is optional.
|
|
|
|
When present, Glance assumes that the expected size of the request body
|
|
will be the value. If the length in bytes of the request body *does not
|
|
match* the value, Glance will raise a `glance.common.exception.BadRequest`
|
|
|
|
When not present, Glance will calculate the image's size based on the size
|
|
of the request body.
|
|
|
|
* `is_public`
|
|
|
|
This key/value is optional.
|
|
|
|
When present, Glance converts the value to a boolean value, so "on, 1, true"
|
|
are all true values. When true, the image is marked as a public image,
|
|
meaning that any user may view its metadata and may read the disk image from
|
|
Glance.
|
|
|
|
When not present, the image is assumed to be *not public* and specific to
|
|
a user.
|
|
|
|
* `properties`
|
|
|
|
This key/value is optional.
|
|
|
|
When present, the value is assumed to be a mapping of free-form key/value
|
|
attributes to store with the image.
|
|
|
|
For example, if the following is the value of the `properties` key in the
|
|
`image_meta` argument::
|
|
|
|
{'distro': 'Ubuntu 10.10'}
|
|
|
|
Then a key/value pair of "distro"/"Ubuntu 10.10" will be stored with the
|
|
image in Glance.
|
|
|
|
There is no limit on the number of free-form key/value attributes that can
|
|
be attached to the image with `properties`. However, keep in mind that there
|
|
is a 8K limit on the size of all HTTP headers sent in a request and this
|
|
number will effectively limit the number of image properties.
|
|
|
|
If the `image_data` argument is omitted, Glance will add the `image_meta`
|
|
mapping to its registries and return the newly-registered image metadata,
|
|
including the new image's identifier. The `status` of the image will be
|
|
set to the value `queued`.
|
|
|
|
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',
|
|
'type': 'machine',
|
|
'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']
|