From 14cc5df1ccbc94dc3e367348b76e0fcd9c44dfee Mon Sep 17 00:00:00 2001 From: "jaypipes@gmail.com" <> Date: Mon, 17 Jan 2011 13:09:14 -0500 Subject: [PATCH] Cleanup of RST documentation and addition of docs on an image's status --- doc/source/client.rst | 145 ++++++++++++------------ doc/source/glanceapi.rst | 230 ++++++++++++++++++++------------------- doc/source/index.rst | 1 + doc/source/statuses.rst | 48 ++++++++ 4 files changed, 244 insertions(+), 180 deletions(-) create mode 100644 doc/source/statuses.rst diff --git a/doc/source/client.rst b/doc/source/client.rst index a4f014dac0..97ae0feaf5 100644 --- a/doc/source/client.rst +++ b/doc/source/client.rst @@ -38,9 +38,9 @@ server knows about. 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() @@ -53,9 +53,9 @@ that the Glance server knows about. 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() @@ -74,9 +74,9 @@ 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:: - 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") @@ -95,9 +95,9 @@ 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:: - 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") @@ -108,9 +108,11 @@ first public image returned and its image data, we can use the following code:: f.write(chunk) f.close() -Note that 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. +.. 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 ---------------------------------- @@ -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 wish to do two things: - * Store the disk image data in Glance - * Store metadata about this image in Glance +* 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 @@ -130,93 +132,94 @@ 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. - -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 `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` +* `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 - would be an unrealistic expectation of users to know all the unique - names of all other user's images. + 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` +* `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. + This key/value is optional. - When this key/value is *not* present, Glance will generate an identifier - for the image and return this identifier in the response (see below) + 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. - * `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 - backing store indicated by the value. If the Glance node does not support - the backing store, Glance will raise a `glance.common.exception.BadRequest` + This key/value is optional. Valid values are one of `file`, `s3` or `swift` - 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. + 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` - * `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`, - `raw`, or `ramdisk`. +* `type` - * `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 - 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` + This key/value is optional. - When not present, Glance will calculate the image's size based on the size - of the request body. + 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` - * `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" - 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. + This key/value is optional. - When not present, the image is assumed to be *not public* and specific to - a user. + 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. - * `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 - attributes to store with the image. + This key/value is optional. - For example, if the following is the value of the `properties` key in the - `image_meta` argument:: + When present, the value is assumed to be a mapping of free-form key/value + 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 - image in Glance. + {'distro': 'Ubuntu 10.10'} - 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. + 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:: diff --git a/doc/source/glanceapi.rst b/doc/source/glanceapi.rst index 57b007735a..ea8493b56e 100644 --- a/doc/source/glanceapi.rst +++ b/doc/source/glanceapi.rst @@ -20,11 +20,11 @@ The Glance REST API Glance has a RESTful API that exposes both metadata about registered virtual 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*. 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. @@ -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 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 mapping in the following format:: @@ -45,9 +45,9 @@ mapping in the following format:: '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 @@ -56,7 +56,7 @@ 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. -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 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', 'updated_at': '2010-02-03 09:34:01', 'deleted_at': '', - 'status': 'available', + 'status': 'active', 'is_public': True, 'properties': {'distro': 'Ubuntu 10.04 LTS'}}, ...]} -Notes: +.. note:: - * 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 - was last updated, not its image data, as all image data is immutable - once stored in Glance - * The `properties` field is a mapping of free-form key/value pairs that - have been saved with the image metadata + 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 + was last updated, not its image data, as all image data is immutable + 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 @@ -97,14 +100,14 @@ data returned includes the `uri` field for each available image. This for a specific image. 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. -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 -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 -`HEAD` request:: +``HEAD`` request:: x-image-meta-uri http://glance.example.com/images/1 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-property-distro Ubuntu 10.04 LTS -Notes: +.. note:: - * 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 - image data is immutable once stored in Glance - * There may be multiple headers that begin with the prefix - `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 + 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 + image data is immutable once stored in Glance + + There may be multiple headers that begin with the prefix + `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 @@ -142,16 +147,16 @@ data returned includes the `uri` field for each available image. This for a specific image. 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. -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 into the response body. 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 -returned from the above `GET` request:: +prefix ``x-image-meta-``. The following shows an example of the HTTP headers +returned from the above ``GET`` request:: x-image-meta-uri http://glance.example.com/images/1 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-property-distro Ubuntu 10.04 LTS -Notes: +.. note:: - * 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 - image data is immutable once stored in Glance - * There may be multiple headers that begin with the prefix - `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 - * The response's `Content-Length` header shall be equal to the value of - 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`. + 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 + image data is immutable once stored in Glance + + There may be multiple headers that begin with the prefix + `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 + + The response's `Content-Length` header shall be equal to the value of + 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 @@ -194,7 +203,7 @@ wish to do two things: 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 -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:: 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 -`POST` request where the header key is prefixed with the strings -`x-image-meta-` and `x-image-meta-property-`. +``POST`` request where the header key is prefixed with the strings +``x-image-meta-`` and ``x-image-meta-property-``. 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 - would be an unrealistic expectation of users to know all the unique - names of all other user's images. + 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. - * `x-image-meta-id` +* ``x-image-meta-id`` - 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. + This header is optional. - When this header is *not* present, Glance will generate an identifier - for the image and return this identifier in the response (see below) + 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. - * `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 - backing store indicated by the value of the header. If the Glance node - does not support the backing store, Glance will return a `400 Bad Request`. + This header is optional. Valid values are one of ``file``, ``s3``, or + ``swift`` - 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. + When present, Glance will attempt to store the disk image data in the + backing store indicated by the value of the header. If the Glance node + 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`, - or `ramdisk`. +* ``x-image-meta-type`` - * `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 - 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`. + This header is optional. - When not present, Glance will calculate the image's size based on the size - of the request body. + When present, Glance assumes that the expected size 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, - 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. + This header is optional. - When not present, the image is assumed to be *not public* and specific to - a user. + When present, Glance converts the value of the header 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. - * `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-`, 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-*`` - 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 - image in Glance. + x-image-meta-property-distro Ubuntu 10.10 - 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. + 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. 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 ***************** 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 -`x-image-meta-` and `x-image-meta-property-`. +``PUT`` request where the header key is prefixed with the strings +``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 -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. +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. -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. + +See more about image statuses here: :doc:`Image Statuses ` diff --git a/doc/source/index.rst b/doc/source/index.rst index aa49dafd26..cc0bd85ee9 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -49,6 +49,7 @@ Concepts identifiers registries + statuses Using Glance ============ diff --git a/doc/source/statuses.rst b/doc/source/statuses.rst new file mode 100644 index 0000000000..c9c875f2b3 --- /dev/null +++ b/doc/source/statuses.rst @@ -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)