openstack/glance
Code Issues Proposed changes

Cleanup of RST documentation and addition of docs on an image's status

Browse Source
This commit is contained in:
jaypipes@gmail.com
2011-01-17 13:09:14 -05:00
parent 1f4a644e61
commit 14cc5df1cc
4 changed files with 244 additions and 180 deletions
Download Patch File Download Diff File Expand all files Collapse all files

145
doc/source/client.rst
View File

@@ -38,9 +38,9 @@ server knows about.
Using Glance's Client, we can do this using the following code:: Using Glance's Client, we can do this using the following code::
from glance import client from glance.client import Client
c = client.Client("glance.example.com", 9292) c = Client("glance.example.com", 9292)
print c.get_images() print c.get_images()
@@ -53,9 +53,9 @@ that the Glance server knows about.
Using Glance's Client, we can do this using the following code:: Using Glance's Client, we can do this using the following code::
from glance import client from glance.client import Client
c = client.Client("glance.example.com", 9292) c = Client("glance.example.com", 9292)
print c.get_images_detailed() print c.get_images_detailed()
@@ -74,9 +74,9 @@ for a specific image.
Continuing the example from above, in order to get metadata about the Continuing the example from above, in order to get metadata about the
first public image returned, we can use the following code:: first public image returned, we can use the following code::
from glance import client from glance.client import Client
c = client.Client("glance.example.com", 9292) c = Client("glance.example.com", 9292)
print c.get_image_meta("http://glance.example.com/images/1") print c.get_image_meta("http://glance.example.com/images/1")
@@ -95,9 +95,9 @@ for a specific image.
Continuing the example from above, in order to get both the metadata about the 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:: first public image returned and its image data, we can use the following code::
from glance import client from glance.client import Client
c = client.Client("glance.example.com", 9292) c = Client("glance.example.com", 9292)
meta, image_file = c.get_image("http://glance.example.com/images/1") meta, image_file = c.get_image("http://glance.example.com/images/1")
@@ -108,9 +108,11 @@ first public image returned and its image data, we can use the following code::
f.write(chunk) f.write(chunk)
f.close() f.close()
Note that the return from Client.get_image() is a tuple of (`metadata`, `file`) .. note::
where `metadata` is a mapping of metadata about the image and `file` is a
generator that yields chunks of image data. 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 Adding a New Virtual Machine Image
---------------------------------- ----------------------------------
@@ -119,8 +121,8 @@ We have created a new virtual machine image in some way (created a
"golden image" or snapshotted/backed up an existing image) and we "golden image" or snapshotted/backed up an existing image) and we
wish to do two things: wish to do two things:
* Store the disk image data in Glance * Store the disk image data in Glance
* Store metadata about this image in Glance * Store metadata about this image in Glance
We can do the above two activities in a single call to the Glance client. 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 Assuming, like in the examples above, that a Glance API server is running
@@ -130,93 +132,94 @@ The method signature is as follows::
glance.client.Client.add_image(image_meta, image_data=None) glance.client.Client.add_image(image_meta, image_data=None)
The `image_meta` argument is a mapping containing various image metadata. The The `image_meta` argument is a mapping containing various image metadata.
`image_data` argument is the disk image data. The `image_data` argument is the disk image data and is an optional argument.
If the data is not yet available, but you would like to reserve a slot in
Glance to hold the image, you can create a 'queued' by omitting the
`image_data` parameter.
The list of metadata that `image_meta` can contain are listed below. The list of metadata that `image_meta` can contain are listed below.
* `name` * `name`
This key/value is required. Its value should be the name of the image. 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 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 would be an unrealistic expectation of users to know all the unique
names of all other user's images. names of all other user's images.
* `id` * `id`
This key/value is optional. 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 When present, Glance will use the supplied identifier for the image.
for the image and return this identifier in the response (see below) If the identifier already exists in that Glance node, then a
`glance.common.exception.Duplicate` will be raised.
* `store` When this key/value is *not* present, Glance will generate an identifier
for the image and return this identifier in the response (see below)
This key/value is optional. Valid values are one of `file` or `swift` * `store`
When present, Glance will attempt to store the disk image data in the This key/value is optional. Valid values are one of `file`, `s3` or `swift`
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 When present, Glance will attempt to store the disk image data in the
store that is marked default. See the configuration option `default_store` backing store indicated by the value. If the Glance node does not support
for more information. the backing store, Glance will raise a `glance.common.exception.BadRequest`
* `type` 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.
This key/values is required. Valid values are one of `kernel`, `machine`, * `type`
`raw`, or `ramdisk`.
* `size` This key/values is required. Valid values are one of `kernel`, `machine`,
`raw`, or `ramdisk`.
This key/value is optional. * `size`
When present, Glance assumes that the expected size of the request body This key/value is optional.
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 When present, Glance assumes that the expected size of the request body
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`
* `is_public` When not present, Glance will calculate the image's size based on the size
of the request body.
This key/value is optional. * `is_public`
When present, Glance converts the value to a boolean value, so "on, 1, true" This key/value is optional.
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 When present, Glance converts the value to a boolean value, so "on, 1, true"
a user. 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.
* `properties` When not present, the image is assumed to be *not public* and specific to
a user.
This key/value is optional. * `properties`
When present, the value is assumed to be a mapping of free-form key/value This key/value is optional.
attributes to store with the image.
For example, if the following is the value of the `properties` key in the When present, the value is assumed to be a mapping of free-form key/value
`image_meta` argument:: attributes to store with the image.
{'distro': 'Ubuntu 10.10'} For example, if the following is the value of the `properties` key in the
`image_meta` argument::
Then a key/value pair of "distro"/"Ubuntu 10.10" will be stored with the {'distro': 'Ubuntu 10.10'}
image in Glance.
There is no limit on the number of free-form key/value attributes that can Then a key/value pair of "distro"/"Ubuntu 10.10" will be stored with the
be attached to the image with `properties`. However, keep in mind that there image in Glance.
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. 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 As a complete example, the following code would add a new machine image to
Glance:: Glance::

230
doc/source/glanceapi.rst
View File

@@ -20,11 +20,11 @@ The Glance REST API
Glance has a RESTful API that exposes both metadata about registered virtual Glance has a RESTful API that exposes both metadata about registered virtual
machine images and the image data itself. machine images and the image data itself.
A host that runs the `bin/glance-api` service is said to be a *Glance API A host that runs the ``bin/glance-api`` service is said to be a *Glance API
Server*. Server*.
Assume there is a Glance API server running at the URL Assume there is a Glance API server running at the URL
http://glance.example.com. ``http://glance.example.com``.
Let's walk through how a user might request information from this server. Let's walk through how a user might request information from this server.
@@ -34,7 +34,7 @@ Requesting a List of Public VM Images
We want to see a list of available virtual machine images that the Glance We want to see a list of available virtual machine images that the Glance
server knows about. server knows about.
We issue a `GET` request to http://glance.example.com/images/ to retrieve We issue a ``GET`` request to ``http://glance.example.com/images/`` to retrieve
this list of available *public* images. The data is returned as a JSON-encoded this list of available *public* images. The data is returned as a JSON-encoded
mapping in the following format:: mapping in the following format::
@@ -45,9 +45,9 @@ mapping in the following format::
'size': '5368709120'} 'size': '5368709120'}
...]} ...]}
Notes: .. note::
* All images returned from the above `GET` request are *public* images All images returned from the above `GET` request are *public* images
Requesting Detailed Metadata on Public VM Images Requesting Detailed Metadata on Public VM Images
@@ -56,7 +56,7 @@ Requesting Detailed Metadata on Public VM Images
We want to see more detailed information on available virtual machine images We want to see more detailed information on available virtual machine images
that the Glance server knows about. that the Glance server knows about.
We issue a `GET` request to http://glance.example.com/images/detail to We issue a ``GET`` request to ``http://glance.example.com/images/detail`` to
retrieve this list of available *public* images. The data is returned as a retrieve this list of available *public* images. The data is returned as a
JSON-encoded mapping in the following format:: JSON-encoded mapping in the following format::
@@ -69,20 +69,23 @@ JSON-encoded mapping in the following format::
'created_at': '2010-02-03 09:34:01', 'created_at': '2010-02-03 09:34:01',
'updated_at': '2010-02-03 09:34:01', 'updated_at': '2010-02-03 09:34:01',
'deleted_at': '', 'deleted_at': '',
'status': 'available', 'status': 'active',
'is_public': True, 'is_public': True,
'properties': {'distro': 'Ubuntu 10.04 LTS'}}, 'properties': {'distro': 'Ubuntu 10.04 LTS'}},
...]} ...]}
Notes: .. note::
* All images returned from the above `GET` request are *public* images All images returned from the above `GET` request are *public* images
* All timestamps returned are in UTC
* The `updated_at` timestamp is the timestamp when an image's metadata All timestamps returned are in UTC
was last updated, not its image data, as all image data is immutable
once stored in Glance The `updated_at` timestamp is the timestamp when an image's metadata
* The `properties` field is a mapping of free-form key/value pairs that was last updated, not its image data, as all image data is immutable
have been saved with the image metadata once stored in Glance
The `properties` field is a mapping of free-form key/value pairs that
have been saved with the image metadata
Requesting Detailed Metadata on a Specific Image Requesting Detailed Metadata on a Specific Image
@@ -97,14 +100,14 @@ data returned includes the `uri` field for each available image. This
for a specific image. for a specific image.
Continuing the example from above, in order to get metadata about the Continuing the example from above, in order to get metadata about the
first public image returned, we can issue a `HEAD` request to the Glance first public image returned, we can issue a ``HEAD`` request to the Glance
server for the image's URI. server for the image's URI.
We issue a `HEAD` request to http://glance.example.com/images/1 to We issue a ``HEAD`` request to ``http://glance.example.com/images/1`` to
retrieve complete metadata for that image. The metadata is returned as a retrieve complete metadata for that image. The metadata is returned as a
set of HTTP headers that begin with the prefix `x-image-meta-`. The set of HTTP headers that begin with the prefix ``x-image-meta-``. The
following shows an example of the HTTP headers returned from the above following shows an example of the HTTP headers returned from the above
`HEAD` request:: ``HEAD`` request::
x-image-meta-uri http://glance.example.com/images/1 x-image-meta-uri http://glance.example.com/images/1
x-image-meta-name Ubuntu 10.04 Plain 5GB x-image-meta-name Ubuntu 10.04 Plain 5GB
@@ -118,16 +121,18 @@ following shows an example of the HTTP headers returned from the above
x-image-meta-is_public True x-image-meta-is_public True
x-image-meta-property-distro Ubuntu 10.04 LTS x-image-meta-property-distro Ubuntu 10.04 LTS
Notes: .. note::
* All timestamps returned are in UTC All timestamps returned are in UTC
* The `x-image-meta-updated_at` timestamp is the timestamp when an
image's metadata was last updated, not its image data, as all The `x-image-meta-updated_at` timestamp is the timestamp when an
image data is immutable once stored in Glance image's metadata was last updated, not its image data, as all
* There may be multiple headers that begin with the prefix image data is immutable once stored in Glance
`x-image-meta-property-`. These headers are free-form key/value pairs
that have been saved with the image metadata. The key is the string There may be multiple headers that begin with the prefix
after `x-image-meta-property-` and the value is the value of the header `x-image-meta-property-`. These headers are free-form key/value pairs
that have been saved with the image metadata. The key is the string
after `x-image-meta-property-` and the value is the value of the header
Retrieving a Virtual Machine Image Retrieving a Virtual Machine Image
@@ -142,16 +147,16 @@ data returned includes the `uri` field for each available image. This
for a specific image. for a specific image.
Continuing the example from above, in order to get metadata about the Continuing the example from above, in order to get metadata about the
first public image returned, we can issue a `HEAD` request to the Glance first public image returned, we can issue a ``HEAD`` request to the Glance
server for the image's URI. server for the image's URI.
We issue a `GET` request to http://glance.example.com/images/1 to We issue a ``GET`` request to ``http://glance.example.com/images/1`` to
retrieve metadata for that image as well as the image itself encoded retrieve metadata for that image as well as the image itself encoded
into the response body. into the response body.
The metadata is returned as a set of HTTP headers that begin with the The metadata is returned as a set of HTTP headers that begin with the
prefix `x-image-meta-`. The following shows an example of the HTTP headers prefix ``x-image-meta-``. The following shows an example of the HTTP headers
returned from the above `GET` request:: returned from the above ``GET`` request::
x-image-meta-uri http://glance.example.com/images/1 x-image-meta-uri http://glance.example.com/images/1
x-image-meta-name Ubuntu 10.04 Plain 5GB x-image-meta-name Ubuntu 10.04 Plain 5GB
@@ -165,21 +170,25 @@ returned from the above `GET` request::
x-image-meta-is_public True x-image-meta-is_public True
x-image-meta-property-distro Ubuntu 10.04 LTS x-image-meta-property-distro Ubuntu 10.04 LTS
Notes: .. note::
* All timestamps returned are in UTC All timestamps returned are in UTC
* The `x-image-meta-updated_at` timestamp is the timestamp when an
image's metadata was last updated, not its image data, as all The `x-image-meta-updated_at` timestamp is the timestamp when an
image data is immutable once stored in Glance image's metadata was last updated, not its image data, as all
* There may be multiple headers that begin with the prefix image data is immutable once stored in Glance
`x-image-meta-property-`. These headers are free-form key/value pairs
that have been saved with the image metadata. The key is the string There may be multiple headers that begin with the prefix
after `x-image-meta-property-` and the value is the value of the header `x-image-meta-property-`. These headers are free-form key/value pairs
* The response's `Content-Length` header shall be equal to the value of that have been saved with the image metadata. The key is the string
the `x-image-meta-size` header after `x-image-meta-property-` and the value is the value of the header
* The image data itself will be the body of the HTTP response returned
from the request, which will have content-type of The response's `Content-Length` header shall be equal to the value of
`application/octet-stream`. the `x-image-meta-size` header
The image data itself will be the body of the HTTP response returned
from the request, which will have content-type of
`application/octet-stream`.
Adding a New Virtual Machine Image Adding a New Virtual Machine Image
@@ -194,7 +203,7 @@ wish to do two things:
We can do the above two activities in a single call to the Glance API. We can do the above two activities in a single call to the Glance API.
Assuming, like in the examples above, that a Glance API server is running Assuming, like in the examples above, that a Glance API server is running
at `glance.example.com`, we issue a `POST` request to add an image to at ``glance.example.com``, we issue a ``POST`` request to add an image to
Glance:: Glance::
POST http://glance.example.com/images/ POST http://glance.example.com/images/
@@ -208,103 +217,106 @@ Adding Image Metadata in HTTP Headers
************************************* *************************************
Glance will view as image metadata any HTTP header that it receives in a Glance will view as image metadata any HTTP header that it receives in a
`POST` request where the header key is prefixed with the strings ``POST`` request where the header key is prefixed with the strings
`x-image-meta-` and `x-image-meta-property-`. ``x-image-meta-`` and ``x-image-meta-property-``.
The list of metadata headers that Glance accepts are listed below. The list of metadata headers that Glance accepts are listed below.
* `x-image-meta-name` * ``x-image-meta-name``
This header is required. Its value should be the name of the image. This header 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 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 would be an unrealistic expectation of users to know all the unique
names of all other user's images. names of all other user's images.
* `x-image-meta-id` * ``x-image-meta-id``
This header is optional. This header is optional.
When present, Glance will use the supplied identifier for the image.
If the identifier already exists in that Glance node, then a
`409 Conflict` will be returned by Glance.
When this header is *not* present, Glance will generate an identifier When present, Glance will use the supplied identifier for the image.
for the image and return this identifier in the response (see below) If the identifier already exists in that Glance node, then a
**409 Conflict** will be returned by Glance.
* `x-image-meta-store` When this header is *not* present, Glance will generate an identifier
for the image and return this identifier in the response (see below)
This header is optional. Valid values are one of `file` or `swift` * ``x-image-meta-store``
When present, Glance will attempt to store the disk image data in the This header is optional. Valid values are one of ``file``, ``s3``, or
backing store indicated by the value of the header. If the Glance node ``swift``
does not support the backing store, Glance will return a `400 Bad Request`.
When not present, Glance will store the disk image data in the backing When present, Glance will attempt to store the disk image data in the
store that is marked default. See the configuration option `default_store` backing store indicated by the value of the header. If the Glance node
for more information. does not support the backing store, Glance will return a **400 Bad Request**.
* `x-image-meta-type` 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.
This header is required. Valid values are one of `kernel`, `machine`, `raw`, * ``x-image-meta-type``
or `ramdisk`.
* `x-image-meta-size` This header is required. Valid values are one of ``kernel``, ``machine``,
``raw``, or ``ramdisk``.
This header is optional. * ``x-image-meta-size``
When present, Glance assumes that the expected size of the request body This header is optional.
will be the value of this header. If the length in bytes of the request
body *does not match* the value of this header, Glance will return a
`400 Bad Request`.
When not present, Glance will calculate the image's size based on the size When present, Glance assumes that the expected size of the request body
of the request body. will be the value of this header. If the length in bytes of the request
body *does not match* the value of this header, Glance will return a
**400 Bad Request**.
* `x-image-meta-is_public` When not present, Glance will calculate the image's size based on the size
of the request body.
This header is optional. * ``x-image-meta-is_public``
When present, Glance converts the value of the header to a boolean value, This header is optional.
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 When present, Glance converts the value of the header to a boolean value,
a user. 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.
* `x-image-meta-property-*` When not present, the image is assumed to be *not public* and specific to
a user.
When Glance receives any HTTP header whose key begins with the string prefix * ``x-image-meta-property-*``
`x-image-meta-property-`, Glance adds the key and value to a set of custom,
free-form image properties stored with the image. The key is the
lower-cased string following the prefix `x-image-meta-property-` with dashes
and punctuation replaced with underscores.
For example, if the following HTTP header were sent:: When Glance receives any HTTP header whose key begins with the string prefix
``x-image-meta-property-``, Glance adds the key and value to a set of custom,
free-form image properties stored with the image. The key is the
lower-cased string following the prefix ``x-image-meta-property-`` with dashes
and punctuation replaced with underscores.
x-image-meta-property-distro Ubuntu 10.10 For example, if the following HTTP header were sent::
Then a key/value pair of "distro"/"Ubuntu 10.10" will be stored with the x-image-meta-property-distro Ubuntu 10.10
image in Glance.
There is no limit on the number of free-form key/value attributes that can Then a key/value pair of "distro"/"Ubuntu 10.10" will be stored with the
be attached to the image. However, keep in mind that the 8K limit on the image in Glance.
size of all HTTP headers sent in a request will effectively limit the number
of image properties. There is no limit on the number of free-form key/value attributes that can
be attached to the image. However, keep in mind that the 8K limit on the
size of all HTTP headers sent in a request will effectively limit the number
of image properties.
Updating an Image Updating an Image
***************** *****************
Glance will view as image metadata any HTTP header that it receives in a Glance will view as image metadata any HTTP header that it receives in a
`PUT` request where the header key is prefixed with the strings ``PUT`` request where the header key is prefixed with the strings
`x-image-meta-` and `x-image-meta-property-`. ``x-image-meta-`` and ``x-image-meta-property-``.
If an image was previously reserved, and thus is in the `queued` state, then If an image was previously reserved, and thus is in the ``queued`` state, then
image data can be added by including it as the request body. If the image image data can be added by including it as the request body. If the image
already as data associated with it (e.g. not in the `queued` state), then already as data associated with it (e.g. not in the ``queued`` state), then
including a request body will result in a `409 Conflict` exception. including a request body will result in a **409 Conflict** exception.
On success, the `PUT` request will return the image metadata encoded as `HTTP` On success, the ``PUT`` request will return the image metadata encoded as HTTP
headers. headers.
See more about image statuses here: :doc:`Image Statuses <statuses>`

1
doc/source/index.rst
View File

@@ -49,6 +49,7 @@ Concepts
identifiers identifiers
registries registries
statuses
Using Glance Using Glance
============ ============

48
doc/source/statuses.rst Normal file
View File

@@ -0,0 +1,48 @@
..
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.
Image Statuses
==============
Images in Glance can be in one of four statuses:
* ``queued``
Denotes an image identifier has been reserved for an image in Glance (or
more specifically, reserved in the registries Glance uses) and that no
actual image data has yet to be uploaded to Glance
* ``saving``
Denotes that an image's raw image data is currently being uploaded to
Glance
* ``active``
Denotes an image that is fully available in Glance
* ``killed``
Denotes that an error occurred during the uploading of an image's data,
and that the image is not readable
.. note::
When an image is registered with a call to `POST /images` and there
is an `x-image-meta-location` header present, that image will never be in
the `saving` status (as the image data is already available in some other
location)