openstack/glance
Code Issues Proposed changes
c9a22eeb6c
glance/doc/source/glanceapi.rst

355 lines
13 KiB
ReStructuredText
Raw Normal View History

Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
..
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.
The Glance REST API
===================
Glance has a RESTful API that exposes both metadata about registered virtual
machine images and the image data itself.
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
A host that runs the ``bin/glance-api`` service is said to be a *Glance API
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
Server*.
Assume there is a Glance API server running at the URL
Adding some basic documentation
2011-02-02 06:53:05 +00:00
``http://glance.example.com``.
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
Let's walk through how a user might request information from this server.
Requesting a List of Public VM Images
-------------------------------------
We want to see a list of available virtual machine images that the Glance
server knows about.
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
We issue a ``GET`` request to ``http://glance.example.com/images/`` to retrieve
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
this list of available *public* images. The data is returned as a JSON-encoded
mapping in the following format::
{'images': [
review fixes
2010-12-23 12:31:47 -05:00
{'uri': 'http://glance.example.com/images/1',
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
'name': 'Ubuntu 10.04 Plain',
Adds lots of unit tests for verifying exceptions are raised properly with invalid or mismatched disk and container formats. Adds documentation on disk and container formats. Updates existing documentation to remove references to the now-gone type column and replaces these references with disk_format and container_format. Reworked the validates_image() method in the registry.db.api to be like what Rick was describing in reviews.
2011-02-25 09:55:26 -05:00
'disk_format': 'vhd',
'container_format': 'ovf',
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
'size': '5368709120'}
...]}
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
.. note::
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
All images returned from the above `GET` request are *public* images
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
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.
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
We issue a ``GET`` request to ``http://glance.example.com/images/detail`` to
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
retrieve this list of available *public* images. The data is returned as a
JSON-encoded mapping in the following format::
{'images': [
review fixes
2010-12-23 12:31:47 -05:00
{'uri': 'http://glance.example.com/images/1',
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
'name': 'Ubuntu 10.04 Plain 5GB',
Adds lots of unit tests for verifying exceptions are raised properly with invalid or mismatched disk and container formats. Adds documentation on disk and container formats. Updates existing documentation to remove references to the now-gone type column and replaces these references with disk_format and container_format. Reworked the validates_image() method in the registry.db.api to be like what Rick was describing in reviews.
2011-02-25 09:55:26 -05:00
'disk_format': 'vhd',
'container_format': 'ovf',
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
'size': '5368709120',
Adds checksumming to Glance. When adding an image (or uploading an image during PUT operations), you may now supply an optional X-Image-Meta-Checksum header. When storing the uploaded image, the backend image stores now are required to return a checksum of the data they just stored. The optional X-Image-Meta-Checksum header is compared against this generated checksum and returns a 409 Bad Request if there is a mismatch. The ETag header is now properly set to the image's checksum now for all GET /images/<ID>, HEAD /images/<ID>, POST /images and PUT /images/<ID> operations. Adds unit tests verifying the checksumming behaviour in the API, and in the Swift and Filesystem backend stores.
2011-03-08 10:22:44 -05:00
'checksum': 'c2e5db72bd7fd153f53ede5da5a06de3',
Adds lots of unit tests for verifying exceptions are raised properly with invalid or mismatched disk and container formats. Adds documentation on disk and container formats. Updates existing documentation to remove references to the now-gone type column and replaces these references with disk_format and container_format. Reworked the validates_image() method in the registry.db.api to be like what Rick was describing in reviews.
2011-02-25 09:55:26 -05:00
'location': 'swift://account:key/container/image.tar.gz.0',
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
'created_at': '2010-02-03 09:34:01',
'updated_at': '2010-02-03 09:34:01',
'deleted_at': '',
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
'status': 'active',
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
'is_public': True,
'properties': {'distro': 'Ubuntu 10.04 LTS'}},
...]}
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
.. note::
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
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
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
Make it clear that the checksum is an MD5 checksum in docs.
2011-03-08 11:40:35 -05:00
The `checksum` field is an MD5 checksum of the image file data
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
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
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
first public image returned, we can issue a ``HEAD`` request to the Glance
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
server for the image's URI.
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
We issue a ``HEAD`` request to ``http://glance.example.com/images/1`` to
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
retrieve complete metadata for that image. The metadata is returned as a
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
set of HTTP headers that begin with the prefix ``x-image-meta-``. The
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
following shows an example of the HTTP headers returned from the above
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
``HEAD`` request::
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
review fixes
2010-12-23 12:31:47 -05:00
x-image-meta-uri http://glance.example.com/images/1
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
x-image-meta-name Ubuntu 10.04 Plain 5GB
Adds lots of unit tests for verifying exceptions are raised properly with invalid or mismatched disk and container formats. Adds documentation on disk and container formats. Updates existing documentation to remove references to the now-gone type column and replaces these references with disk_format and container_format. Reworked the validates_image() method in the registry.db.api to be like what Rick was describing in reviews.
2011-02-25 09:55:26 -05:00
x-image-meta-disk-format vhd
x-image-meta-container-format ovf
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
x-image-meta-size 5368709120
Adds checksumming to Glance. When adding an image (or uploading an image during PUT operations), you may now supply an optional X-Image-Meta-Checksum header. When storing the uploaded image, the backend image stores now are required to return a checksum of the data they just stored. The optional X-Image-Meta-Checksum header is compared against this generated checksum and returns a 409 Bad Request if there is a mismatch. The ETag header is now properly set to the image's checksum now for all GET /images/<ID>, HEAD /images/<ID>, POST /images and PUT /images/<ID> operations. Adds unit tests verifying the checksumming behaviour in the API, and in the Swift and Filesystem backend stores.
2011-03-08 10:22:44 -05:00
x-image-meta-checksum c2e5db72bd7fd153f53ede5da5a06de3
Adds lots of unit tests for verifying exceptions are raised properly with invalid or mismatched disk and container formats. Adds documentation on disk and container formats. Updates existing documentation to remove references to the now-gone type column and replaces these references with disk_format and container_format. Reworked the validates_image() method in the registry.db.api to be like what Rick was describing in reviews.
2011-02-25 09:55:26 -05:00
x-image-meta-location swift://account:key/container/image.tar.gz.0
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
x-image-meta-created_at 2010-02-03 09:34:01
x-image-meta-updated_at 2010-02-03 09:34:01
Adding some basic documentation
2011-02-02 06:53:05 +00:00
x-image-meta-deleted_at
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
x-image-meta-status available
Adds lots of unit tests for verifying exceptions are raised properly with invalid or mismatched disk and container formats. Adds documentation on disk and container formats. Updates existing documentation to remove references to the now-gone type column and replaces these references with disk_format and container_format. Reworked the validates_image() method in the registry.db.api to be like what Rick was describing in reviews.
2011-02-25 09:55:26 -05:00
x-image-meta-is-public True
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
x-image-meta-property-distro Ubuntu 10.04 LTS
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
.. note::
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
All timestamps returned are in UTC
The `x-image-meta-updated_at` timestamp is the timestamp when an
Adding some basic documentation
2011-02-02 06:53:05 +00:00
image's metadata was last updated, not its image data, as all
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
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
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
Adds checksumming to Glance. When adding an image (or uploading an image during PUT operations), you may now supply an optional X-Image-Meta-Checksum header. When storing the uploaded image, the backend image stores now are required to return a checksum of the data they just stored. The optional X-Image-Meta-Checksum header is compared against this generated checksum and returns a 409 Bad Request if there is a mismatch. The ETag header is now properly set to the image's checksum now for all GET /images/<ID>, HEAD /images/<ID>, POST /images and PUT /images/<ID> operations. Adds unit tests verifying the checksumming behaviour in the API, and in the Swift and Filesystem backend stores.
2011-03-08 10:22:44 -05:00
The response's `ETag` header will always be equal to the
`x-image-meta-checksum` value
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
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 metadata about the
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
first public image returned, we can issue a ``HEAD`` request to the Glance
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
server for the image's URI.
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
We issue a ``GET`` request to ``http://glance.example.com/images/1`` to
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
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
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
prefix ``x-image-meta-``. The following shows an example of the HTTP headers
returned from the above ``GET`` request::
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
review fixes
2010-12-23 12:31:47 -05:00
x-image-meta-uri http://glance.example.com/images/1
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
x-image-meta-name Ubuntu 10.04 Plain 5GB
Adds lots of unit tests for verifying exceptions are raised properly with invalid or mismatched disk and container formats. Adds documentation on disk and container formats. Updates existing documentation to remove references to the now-gone type column and replaces these references with disk_format and container_format. Reworked the validates_image() method in the registry.db.api to be like what Rick was describing in reviews.
2011-02-25 09:55:26 -05:00
x-image-meta-disk-format vhd
x-image-meta-container-format ovf
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
x-image-meta-size 5368709120
Adds checksumming to Glance. When adding an image (or uploading an image during PUT operations), you may now supply an optional X-Image-Meta-Checksum header. When storing the uploaded image, the backend image stores now are required to return a checksum of the data they just stored. The optional X-Image-Meta-Checksum header is compared against this generated checksum and returns a 409 Bad Request if there is a mismatch. The ETag header is now properly set to the image's checksum now for all GET /images/<ID>, HEAD /images/<ID>, POST /images and PUT /images/<ID> operations. Adds unit tests verifying the checksumming behaviour in the API, and in the Swift and Filesystem backend stores.
2011-03-08 10:22:44 -05:00
x-image-meta-checksum c2e5db72bd7fd153f53ede5da5a06de3
Adds lots of unit tests for verifying exceptions are raised properly with invalid or mismatched disk and container formats. Adds documentation on disk and container formats. Updates existing documentation to remove references to the now-gone type column and replaces these references with disk_format and container_format. Reworked the validates_image() method in the registry.db.api to be like what Rick was describing in reviews.
2011-02-25 09:55:26 -05:00
x-image-meta-location swift://account:key/container/image.tar.gz.0
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
x-image-meta-created_at 2010-02-03 09:34:01
x-image-meta-updated_at 2010-02-03 09:34:01
Adding some basic documentation
2011-02-02 06:53:05 +00:00
x-image-meta-deleted_at
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
x-image-meta-status available
Adds lots of unit tests for verifying exceptions are raised properly with invalid or mismatched disk and container formats. Adds documentation on disk and container formats. Updates existing documentation to remove references to the now-gone type column and replaces these references with disk_format and container_format. Reworked the validates_image() method in the registry.db.api to be like what Rick was describing in reviews.
2011-02-25 09:55:26 -05:00
x-image-meta-is-public True
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
x-image-meta-property-distro Ubuntu 10.04 LTS
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
.. note::
All timestamps returned are in UTC
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
The `x-image-meta-updated_at` timestamp is the timestamp when an
Adding some basic documentation
2011-02-02 06:53:05 +00:00
image's metadata was last updated, not its image data, as all
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
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
Adds checksumming to Glance. When adding an image (or uploading an image during PUT operations), you may now supply an optional X-Image-Meta-Checksum header. When storing the uploaded image, the backend image stores now are required to return a checksum of the data they just stored. The optional X-Image-Meta-Checksum header is compared against this generated checksum and returns a 409 Bad Request if there is a mismatch. The ETag header is now properly set to the image's checksum now for all GET /images/<ID>, HEAD /images/<ID>, POST /images and PUT /images/<ID> operations. Adds unit tests verifying the checksumming behaviour in the API, and in the Swift and Filesystem backend stores.
2011-03-08 10:22:44 -05:00
The response's `ETag` header will always be equal to the
`x-image-meta-checksum` value
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
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`.
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
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 API.
Assuming, like in the examples above, that a Glance API server is running
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
at ``glance.example.com``, we issue a ``POST`` request to add an image to
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
Glance::
review fixes
2010-12-23 12:31:47 -05:00
POST http://glance.example.com/images/
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
The metadata about the image is sent to Glance in HTTP headers. The body
of the HTTP request to the Glance API will be the MIME-encoded disk
image data.
Adding Image Metadata in HTTP Headers
*************************************
Glance will view as image metadata any HTTP header that it receives in a
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
``POST`` request where the header key is prefixed with the strings
``x-image-meta-`` and ``x-image-meta-property-``.
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
The list of metadata headers that Glance accepts are listed below.
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
* ``x-image-meta-name``
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
This header is required. Its value should be the name of the image.
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
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.
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
* ``x-image-meta-id``
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
Adding some basic documentation
2011-02-02 06:53:05 +00:00
This header is optional.
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
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.
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
When this header is *not* present, Glance will generate an identifier
for the image and return this identifier in the response (see below)
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
* ``x-image-meta-store``
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
This header is optional. Valid values are one of ``file``, ``s3``, or
``swift``
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
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**.
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
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.
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
Adds lots of unit tests for verifying exceptions are raised properly with invalid or mismatched disk and container formats. Adds documentation on disk and container formats. Updates existing documentation to remove references to the now-gone type column and replaces these references with disk_format and container_format. Reworked the validates_image() method in the registry.db.api to be like what Rick was describing in reviews.
2011-02-25 09:55:26 -05:00
* ``x-image-meta-disk-format``
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
Final review fixes. Makes disk_format and container_format optional. Makes glance-upload --type put the type in properties
2011-03-05 12:04:43 -05:00
This header is optional. Valid values are one of ``aki``, ``ari``, ``ami``,
Adds lots of unit tests for verifying exceptions are raised properly with invalid or mismatched disk and container formats. Adds documentation on disk and container formats. Updates existing documentation to remove references to the now-gone type column and replaces these references with disk_format and container_format. Reworked the validates_image() method in the registry.db.api to be like what Rick was describing in reviews.
2011-02-25 09:55:26 -05:00
``raw``, ``vhd``, ``vdi``, ``qcow2``, or ``vmdk``.
For more information, see :doc:`About Disk and Container Formats <formats>`
* ``x-image-meta-container-format``
Final review fixes. Makes disk_format and container_format optional. Makes glance-upload --type put the type in properties
2011-03-05 12:04:43 -05:00
This header is optional. Valid values are one of ``aki``, ``ari``, ``ami``,
Adds lots of unit tests for verifying exceptions are raised properly with invalid or mismatched disk and container formats. Adds documentation on disk and container formats. Updates existing documentation to remove references to the now-gone type column and replaces these references with disk_format and container_format. Reworked the validates_image() method in the registry.db.api to be like what Rick was describing in reviews.
2011-02-25 09:55:26 -05:00
``bare``, or ``ovf``.
For more information, see :doc:`About Disk and Container Formats <formats>`
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
* ``x-image-meta-size``
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
This header is optional.
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
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**.
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
When not present, Glance will calculate the image's size based on the size
of the request body.
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
Adds checksumming to Glance. When adding an image (or uploading an image during PUT operations), you may now supply an optional X-Image-Meta-Checksum header. When storing the uploaded image, the backend image stores now are required to return a checksum of the data they just stored. The optional X-Image-Meta-Checksum header is compared against this generated checksum and returns a 409 Bad Request if there is a mismatch. The ETag header is now properly set to the image's checksum now for all GET /images/<ID>, HEAD /images/<ID>, POST /images and PUT /images/<ID> operations. Adds unit tests verifying the checksumming behaviour in the API, and in the Swift and Filesystem backend stores.
2011-03-08 10:22:44 -05:00
* ``x-image-meta-checksum``
Make it clear that the checksum is an MD5 checksum in docs.
2011-03-08 11:40:35 -05:00
This header is optional. When present it shall be the expected **MD5**
checksum of the image file data.
Adds checksumming to Glance. When adding an image (or uploading an image during PUT operations), you may now supply an optional X-Image-Meta-Checksum header. When storing the uploaded image, the backend image stores now are required to return a checksum of the data they just stored. The optional X-Image-Meta-Checksum header is compared against this generated checksum and returns a 409 Bad Request if there is a mismatch. The ETag header is now properly set to the image's checksum now for all GET /images/<ID>, HEAD /images/<ID>, POST /images and PUT /images/<ID> operations. Adds unit tests verifying the checksumming behaviour in the API, and in the Swift and Filesystem backend stores.
2011-03-08 10:22:44 -05:00
When present, Glance will verify the checksum generated from the backend
store when storing your image against this value and return a
**400 Bad Request** if the values do not match.
Adds lots of unit tests for verifying exceptions are raised properly with invalid or mismatched disk and container formats. Adds documentation on disk and container formats. Updates existing documentation to remove references to the now-gone type column and replaces these references with disk_format and container_format. Reworked the validates_image() method in the registry.db.api to be like what Rick was describing in reviews.
2011-02-25 09:55:26 -05:00
* ``x-image-meta-is-public``
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
This header is optional.
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
OK, fix docs to make it clear that only the string 'true' is allowed for boolean headers. Add False-hood unit tests as well.
2011-04-12 17:45:16 -04:00
When Glance finds the string "true" (case-insensitive), the image is marked as
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
a public image, meaning that any user may view its metadata and may read
the disk image from Glance.
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
When not present, the image is assumed to be *not public* and specific to
a user.
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
* ``x-image-meta-property-*``
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
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.
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
For example, if the following HTTP header were sent::
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
x-image-meta-property-distro Ubuntu 10.10
Documentation cleanup. Splits out index.rst into multiple section docs.
2010-12-22 12:38:54 -05:00
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
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 docs
2011-01-11 11:34:48 -06:00
Updating an Image
*****************
Glance will view as image metadata any HTTP header that it receives in a
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
``PUT`` request where the header key is prefixed with the strings
``x-image-meta-`` and ``x-image-meta-property-``.
Updating docs
2011-01-11 11:34:48 -06:00
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
If an image was previously reserved, and thus is in the ``queued`` state, then
Updating docs
2011-01-11 11:34:48 -06:00
image data can be added by including it as the request body. If the image
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
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.
Updating docs
2011-01-11 11:34:48 -06:00
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
On success, the ``PUT`` request will return the image metadata encoded as HTTP
Updating docs
2011-01-11 11:34:48 -06:00
headers.
Cleanup of RST documentation and addition of docs on an image's status
2011-01-17 13:09:14 -05:00
See more about image statuses here: :doc:`Image Statuses <statuses>`
Copy Permalink