Cleanup of RST documentation and addition of docs on an image's status
This commit is contained in:
parent
1f4a644e61
commit
14cc5df1cc
|
@ -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,16 +132,12 @@ 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.
|
||||||
|
|
||||||
|
@ -147,7 +145,7 @@ The list of metadata that `image_meta` can contain are listed below.
|
||||||
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.
|
||||||
|
|
||||||
|
@ -158,9 +156,9 @@ The list of metadata that `image_meta` can contain are listed below.
|
||||||
When this key/value is *not* present, Glance will generate an identifier
|
When this key/value is *not* present, Glance will generate an identifier
|
||||||
for the image and return this identifier in the response (see below)
|
for the image and return this identifier in the response (see below)
|
||||||
|
|
||||||
* `store`
|
* `store`
|
||||||
|
|
||||||
This key/value is optional. Valid values are one of `file` or `swift`
|
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
|
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
|
backing store indicated by the value. If the Glance node does not support
|
||||||
|
@ -170,12 +168,12 @@ The list of metadata that `image_meta` can contain are listed below.
|
||||||
store that is marked default. See the configuration option `default_store`
|
store that is marked default. See the configuration option `default_store`
|
||||||
for more information.
|
for more information.
|
||||||
|
|
||||||
* `type`
|
* `type`
|
||||||
|
|
||||||
This key/values is required. Valid values are one of `kernel`, `machine`,
|
This key/values is required. Valid values are one of `kernel`, `machine`,
|
||||||
`raw`, or `ramdisk`.
|
`raw`, or `ramdisk`.
|
||||||
|
|
||||||
* `size`
|
* `size`
|
||||||
|
|
||||||
This key/value is optional.
|
This key/value is optional.
|
||||||
|
|
||||||
|
@ -186,7 +184,7 @@ The list of metadata that `image_meta` can contain are listed below.
|
||||||
When not present, Glance will calculate the image's size based on the size
|
When not present, Glance will calculate the image's size based on the size
|
||||||
of the request body.
|
of the request body.
|
||||||
|
|
||||||
* `is_public`
|
* `is_public`
|
||||||
|
|
||||||
This key/value is optional.
|
This key/value is optional.
|
||||||
|
|
||||||
|
@ -198,7 +196,7 @@ The list of metadata that `image_meta` can contain are listed below.
|
||||||
When not present, the image is assumed to be *not public* and specific to
|
When not present, the image is assumed to be *not public* and specific to
|
||||||
a user.
|
a user.
|
||||||
|
|
||||||
* `properties`
|
* `properties`
|
||||||
|
|
||||||
This key/value is optional.
|
This key/value is optional.
|
||||||
|
|
||||||
|
@ -218,6 +216,11 @@ The list of metadata that `image_meta` can contain are listed below.
|
||||||
is a 8K limit on the size of all HTTP headers sent in a request and this
|
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.
|
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::
|
||||||
|
|
||||||
|
|
|
@ -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,19 +69,22 @@ 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
|
||||||
|
|
||||||
|
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
|
was last updated, not its image data, as all image data is immutable
|
||||||
once stored in Glance
|
once stored in Glance
|
||||||
* The `properties` field is a mapping of free-form key/value pairs that
|
|
||||||
|
The `properties` field is a mapping of free-form key/value pairs that
|
||||||
have been saved with the image metadata
|
have been saved with the image metadata
|
||||||
|
|
||||||
|
|
||||||
|
@ -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,13 +121,15 @@ 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
|
|
||||||
|
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's metadata was last updated, not its image data, as all
|
||||||
image data is immutable once stored in Glance
|
image data is immutable once stored in Glance
|
||||||
* There may be multiple headers that begin with the prefix
|
|
||||||
|
There may be multiple headers that begin with the prefix
|
||||||
`x-image-meta-property-`. These headers are free-form key/value pairs
|
`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
|
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
|
after `x-image-meta-property-` and the value is the value of the header
|
||||||
|
@ -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,19 +170,23 @@ 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
|
|
||||||
|
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's metadata was last updated, not its image data, as all
|
||||||
image data is immutable once stored in Glance
|
image data is immutable once stored in Glance
|
||||||
* There may be multiple headers that begin with the prefix
|
|
||||||
|
There may be multiple headers that begin with the prefix
|
||||||
`x-image-meta-property-`. These headers are free-form key/value pairs
|
`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
|
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
|
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 response's `Content-Length` header shall be equal to the value of
|
||||||
the `x-image-meta-size` header
|
the `x-image-meta-size` header
|
||||||
* The image data itself will be the body of the HTTP response returned
|
|
||||||
|
The image data itself will be the body of the HTTP response returned
|
||||||
from the request, which will have content-type of
|
from the request, which will have content-type of
|
||||||
`application/octet-stream`.
|
`application/octet-stream`.
|
||||||
|
|
||||||
|
@ -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,12 +217,12 @@ 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.
|
||||||
|
|
||||||
|
@ -221,47 +230,48 @@ The list of metadata headers that Glance accepts are listed below.
|
||||||
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.
|
When present, Glance will use the supplied identifier for the image.
|
||||||
If the identifier already exists in that Glance node, then a
|
If the identifier already exists in that Glance node, then a
|
||||||
`409 Conflict` will be returned by Glance.
|
**409 Conflict** will be returned by Glance.
|
||||||
|
|
||||||
When this header is *not* present, Glance will generate an identifier
|
When this header is *not* present, Glance will generate an identifier
|
||||||
for the image and return this identifier in the response (see below)
|
for the image and return this identifier in the response (see below)
|
||||||
|
|
||||||
* `x-image-meta-store`
|
* ``x-image-meta-store``
|
||||||
|
|
||||||
This header is optional. Valid values are one of `file` or `swift`
|
This header is optional. Valid values are one of ``file``, ``s3``, or
|
||||||
|
``swift``
|
||||||
|
|
||||||
When present, Glance will attempt to store the disk image data in the
|
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
|
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`.
|
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 not present, Glance will store the disk image data in the backing
|
||||||
store that is marked default. See the configuration option `default_store`
|
store that is marked default. See the configuration option ``default_store``
|
||||||
for more information.
|
for more information.
|
||||||
|
|
||||||
* `x-image-meta-type`
|
* ``x-image-meta-type``
|
||||||
|
|
||||||
This header is required. Valid values are one of `kernel`, `machine`, `raw`,
|
This header is required. Valid values are one of ``kernel``, ``machine``,
|
||||||
or `ramdisk`.
|
``raw``, or ``ramdisk``.
|
||||||
|
|
||||||
* `x-image-meta-size`
|
* ``x-image-meta-size``
|
||||||
|
|
||||||
This header is optional.
|
This header is optional.
|
||||||
|
|
||||||
When present, Glance assumes that the expected 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
|
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
|
body *does not match* the value of this header, Glance will return a
|
||||||
`400 Bad Request`.
|
**400 Bad Request**.
|
||||||
|
|
||||||
When not present, Glance will calculate the image's size based on the size
|
When not present, Glance will calculate the image's size based on the size
|
||||||
of the request body.
|
of the request body.
|
||||||
|
|
||||||
* `x-image-meta-is_public`
|
* ``x-image-meta-is_public``
|
||||||
|
|
||||||
This header is optional.
|
This header is optional.
|
||||||
|
|
||||||
|
@ -273,12 +283,12 @@ The list of metadata headers that Glance accepts are listed below.
|
||||||
When not present, the image is assumed to be *not public* and specific to
|
When not present, the image is assumed to be *not public* and specific to
|
||||||
a user.
|
a user.
|
||||||
|
|
||||||
* `x-image-meta-property-*`
|
* ``x-image-meta-property-*``
|
||||||
|
|
||||||
When Glance receives any HTTP header whose key begins with the string prefix
|
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,
|
``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
|
free-form image properties stored with the image. The key is the
|
||||||
lower-cased string following the prefix `x-image-meta-property-` with dashes
|
lower-cased string following the prefix ``x-image-meta-property-`` with dashes
|
||||||
and punctuation replaced with underscores.
|
and punctuation replaced with underscores.
|
||||||
|
|
||||||
For example, if the following HTTP header were sent::
|
For example, if the following HTTP header were sent::
|
||||||
|
@ -298,13 +308,15 @@ 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>`
|
||||||
|
|
|
@ -49,6 +49,7 @@ Concepts
|
||||||
|
|
||||||
identifiers
|
identifiers
|
||||||
registries
|
registries
|
||||||
|
statuses
|
||||||
|
|
||||||
Using Glance
|
Using Glance
|
||||||
============
|
============
|
||||||
|
|
|
@ -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)
|
Loading…
Reference in New Issue