Remove extra whitespace
Remove whitespace that is not needed like end-of-line whitespace and whitespace before a closing </param>. Change-Id: I6525fd74d3d38400605aa2af8be80d0a701c438f
This commit is contained in:
Andreas Jaeger
parent
b752317103
commit
a8c6b84019
@ -7,17 +7,17 @@
|
||||
<?dbhtml stop-chunking?>
|
||||
<para>OpenStack Image Service offers retrieval, storage, and
|
||||
metadata assignment for your images that you want to run in
|
||||
your OpenStack cloud. The project is code-named Glance. </para>
|
||||
your OpenStack cloud. The project is code-named Glance.</para>
|
||||
<para>OpenStack Image service enables users to store and retrieve
|
||||
images through a simple Web Service (ReST: Representational
|
||||
State Transfer) interface. </para>
|
||||
State Transfer) interface.</para>
|
||||
<para>For more details on the OpenStack Image service,
|
||||
please refer to <link xlink:href="http://docs.openstack.org/developer/glance/"
|
||||
>docs.openstack.org/developer/glance/</link>
|
||||
</para>
|
||||
<para>We welcome feedback, comments, and bug reports at <link
|
||||
xlink:href="http://bugs.launchpad.net/glance"
|
||||
>bugs.launchpad.net/glance</link>. </para>
|
||||
>bugs.launchpad.net/glance</link>.</para>
|
||||
<section xml:id="glance-api-intended-audience">
|
||||
<title>Intended Audience</title>
|
||||
<para>This guide is intended to assist software developers who
|
||||
@ -29,7 +29,7 @@
|
||||
here, you should first have a general understanding of the
|
||||
OpenStack Image Service and have access to an installation
|
||||
of OpenStack Image Service. You should also be familiar
|
||||
with: </para>
|
||||
with:</para>
|
||||
<itemizedlist spacing="compact">
|
||||
<listitem>
|
||||
<para>ReSTful web services</para>
|
||||
|
||||
@ -6,25 +6,25 @@
|
||||
<info>
|
||||
<title>The Glance REST API</title>
|
||||
</info>
|
||||
<para> Glance has a RESTful API that exposes both metadata about
|
||||
registered virtual machine images and the image data itself. </para>
|
||||
<para> A host that runs the <literal>bin/glance-api</literal>
|
||||
service is said to be a <emphasis>Glance API Server</emphasis>. </para>
|
||||
<para> Assume there is a Glance API server running at the URL
|
||||
<literal>http://glance.example.com</literal>. </para>
|
||||
<para> Let's walk through how a user might request information from
|
||||
this server. </para>
|
||||
<para>Glance has a RESTful API that exposes both metadata about
|
||||
registered virtual machine images and the image data itself.</para>
|
||||
<para>A host that runs the <literal>bin/glance-api</literal>
|
||||
service is said to be a <emphasis>Glance API Server</emphasis>.</para>
|
||||
<para>Assume there is a Glance API server running at the URL
|
||||
<literal>http://glance.example.com</literal>.</para>
|
||||
<para>Let's walk through how a user might request information from
|
||||
this server.</para>
|
||||
<section xml:id="requesting-a-list-of-public-vm-images">
|
||||
<info>
|
||||
<title>Requesting a List of Public VM Images</title>
|
||||
</info>
|
||||
<para> We want to see a list of available virtual machine images
|
||||
that the Glance server knows about. </para>
|
||||
<para> We issue a <literal>GET</literal> request to
|
||||
<para>We want to see a list of available virtual machine images
|
||||
that the Glance server knows about.</para>
|
||||
<para>We issue a <literal>GET</literal> request to
|
||||
<literal>http://glance.example.com/images/</literal> to
|
||||
retrieve this list of available <emphasis>public</emphasis>
|
||||
images. The data is returned as a JSON-encoded mapping in the
|
||||
following format: </para>
|
||||
following format:</para>
|
||||
<literallayout class="monospaced">
|
||||
{'images': [
|
||||
{'status: 'active',
|
||||
@ -43,13 +43,13 @@ All images returned from the above `GET` request are <emphasis role="bold">publi
|
||||
<title>Requesting Detailed Metadata on Public VM Images</title>
|
||||
</info>
|
||||
|
||||
<para> We want to see more detailed information on available
|
||||
virtual machine images that the Glance server knows about. </para>
|
||||
<para> We issue a <literal>GET</literal> request to
|
||||
<para>We want to see more detailed information on available
|
||||
virtual machine images that the Glance server knows about.</para>
|
||||
<para>We issue a <literal>GET</literal> request to
|
||||
<literal>http://glance.example.com/images/detail</literal> to
|
||||
retrieve this list of available <emphasis>public</emphasis>
|
||||
images. The data is returned as a JSON-encoded mapping in the
|
||||
following format: </para>
|
||||
following format:</para>
|
||||
<literallayout class="monospaced">
|
||||
{'images': [
|
||||
{'name': 'Ubuntu 10.04 Plain 5GB',
|
||||
@ -96,54 +96,54 @@ indicate the owner of the image
|
||||
/images/detail</literal></title>
|
||||
</info>
|
||||
|
||||
<para> Both the <literal>GET /images</literal> and <literal>GET
|
||||
<para>Both the <literal>GET /images</literal> and <literal>GET
|
||||
/images/detail</literal> requests take query parameters that
|
||||
serve to filter the returned list of images. The following list
|
||||
details these query parameters. </para>
|
||||
details these query parameters.</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>name=NAME</literal>
|
||||
</para>
|
||||
<para> Filters images having a <literal>name</literal>
|
||||
attribute matching <literal>NAME</literal>. </para>
|
||||
<para>Filters images having a <literal>name</literal>
|
||||
attribute matching <literal>NAME</literal>.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>container_format=FORMAT</literal>
|
||||
</para>
|
||||
<para> Filters images having a
|
||||
<para>Filters images having a
|
||||
<literal>container_format</literal> attribute matching
|
||||
<literal>FORMAT</literal>
|
||||
</para>
|
||||
<para> For more information, see :doc:`About Disk and
|
||||
<para>For more information, see :doc:`About Disk and
|
||||
Container Formats <formats>` </para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>disk_format=FORMAT</literal>
|
||||
</para>
|
||||
<para> Filters images having a <literal>disk_format</literal>
|
||||
<para>Filters images having a <literal>disk_format</literal>
|
||||
attribute matching <literal>FORMAT</literal>
|
||||
</para>
|
||||
<para> For more information, see :doc:`About Disk and
|
||||
<para>For more information, see :doc:`About Disk and
|
||||
Container Formats <formats>` </para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>status=STATUS</literal>
|
||||
</para>
|
||||
<para> Filters images having a <literal>status</literal>
|
||||
<para>Filters images having a <literal>status</literal>
|
||||
attribute matching <literal>STATUS</literal>
|
||||
</para>
|
||||
<para> For more information, see :doc:`About Image Statuses
|
||||
<para>For more information, see :doc:`About Image Statuses
|
||||
<statuses>` </para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>size_min=BYTES</literal>
|
||||
</para>
|
||||
<para> Filters images having a <literal>size</literal>
|
||||
<para>Filters images having a <literal>size</literal>
|
||||
attribute greater than or equal to <literal>BYTES</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
@ -151,33 +151,33 @@ indicate the owner of the image
|
||||
<para>
|
||||
<literal>size_max=BYTES</literal>
|
||||
</para>
|
||||
<para> Filters images having a <literal>size</literal>
|
||||
<para>Filters images having a <literal>size</literal>
|
||||
attribute less than or equal to <literal>BYTES</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para> These two resources also accept sort parameters: </para>
|
||||
<para>These two resources also accept sort parameters:</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>sort_key=KEY</literal>
|
||||
</para>
|
||||
<para> Results will be ordered by the specified image
|
||||
<para>Results will be ordered by the specified image
|
||||
attribute <literal>KEY</literal>. Accepted values include
|
||||
<literal>id</literal>, <literal>name</literal>,
|
||||
<literal>status</literal>, <literal>disk_format</literal>,
|
||||
<literal>container_format</literal>,
|
||||
<literal>size</literal>, <literal>created_at</literal>
|
||||
(default) and <literal>updated_at</literal>. </para>
|
||||
(default) and <literal>updated_at</literal>.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>sort_dir=DIR</literal>
|
||||
</para>
|
||||
<para> Results will be sorted in the direction
|
||||
<para>Results will be sorted in the direction
|
||||
<literal>DIR</literal>. Accepted values are
|
||||
<literal>asc</literal> for ascending or
|
||||
<literal>desc</literal> (default) for descending. </para>
|
||||
<literal>desc</literal> (default) for descending.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</section>
|
||||
@ -186,23 +186,23 @@ indicate the owner of the image
|
||||
<title>Requesting Detailed Metadata on a Specific Image</title>
|
||||
</info>
|
||||
|
||||
<para> We want to see detailed information for a specific virtual
|
||||
machine image that the Glance server knows about. </para>
|
||||
<para> We have queried the Glance server for a list of public
|
||||
<para>We want to see detailed information for a specific virtual
|
||||
machine image that the Glance server knows about.</para>
|
||||
<para>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. </para>
|
||||
<para> Continuing the example from above, in order to get metadata
|
||||
location needed to get the metadata for a specific image.</para>
|
||||
<para>Continuing the example from above, in order to get metadata
|
||||
about the first public image returned, we can issue a
|
||||
<literal>HEAD</literal> request to the Glance server for the
|
||||
image's URI. </para>
|
||||
<para> We issue a <literal>HEAD</literal> request to
|
||||
image's URI.</para>
|
||||
<para>We issue a <literal>HEAD</literal> request to
|
||||
<literal>http://glance.example.com/images/1</literal> to
|
||||
retrieve complete metadata for that image. The metadata is
|
||||
returned as a set of HTTP headers that begin with the prefix
|
||||
<literal>x-image-meta-</literal>. The following shows an
|
||||
example of the HTTP headers returned from the above
|
||||
<literal>HEAD</literal> request: </para>
|
||||
<literal>HEAD</literal> request:</para>
|
||||
<literallayout class="monospaced">
|
||||
x-image-meta-name Ubuntu 10.04 Plain 5GB
|
||||
x-image-meta-disk-format vhd
|
||||
@ -218,7 +218,7 @@ x-image-meta-is-public true
|
||||
x-image-meta-owner null
|
||||
x-image-meta-property-distro Ubuntu 10.04 LTS
|
||||
</literallayout>
|
||||
<para> All timestamps returned are in UTC The
|
||||
<para>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
|
||||
@ -231,31 +231,31 @@ x-image-meta-property-distro Ubuntu 10.04 LTS
|
||||
`x-image-meta-is-public` value is a boolean indicating whether
|
||||
the image is publicly available The response's
|
||||
`x-image-meta-owner` value is a string which may either be null
|
||||
or which will indicate the owner of the image </para>
|
||||
or which will indicate the owner of the image</para>
|
||||
</section>
|
||||
<section xml:id="retrieving-a-virtual-machine-image">
|
||||
<info>
|
||||
<title>Retrieving a Virtual Machine Image</title>
|
||||
</info>
|
||||
|
||||
<para> We want to retrieve that actual raw data for a specific
|
||||
virtual machine image that the Glance server knows about. </para>
|
||||
<para> We have queried the Glance server for a list of public
|
||||
<para>We want to retrieve that actual raw data for a specific
|
||||
virtual machine image that the Glance server knows about.</para>
|
||||
<para>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. </para>
|
||||
<para> Continuing the example from above, in order to get metadata
|
||||
location needed to get the metadata for a specific image.</para>
|
||||
<para>Continuing the example from above, in order to get metadata
|
||||
about the first public image returned, we can issue a
|
||||
<literal>HEAD</literal> request to the Glance server for the
|
||||
image's URI. </para>
|
||||
<para> We issue a <literal>GET</literal> request to
|
||||
image's URI.</para>
|
||||
<para>We issue a <literal>GET</literal> request to
|
||||
<literal>http://glance.example.com/images/1</literal> to
|
||||
retrieve metadata for that image as well as the image itself
|
||||
encoded into the response body. </para>
|
||||
<para> The metadata is returned as a set of HTTP headers that
|
||||
encoded into the response body.</para>
|
||||
<para>The metadata is returned as a set of HTTP headers that
|
||||
begin with the prefix <literal>x-image-meta-</literal>. The
|
||||
following shows an example of the HTTP headers returned from the
|
||||
above <literal>GET</literal> request: </para>
|
||||
above <literal>GET</literal> request:</para>
|
||||
<literallayout class="monospaced">
|
||||
x-image-meta-name Ubuntu 10.04 Plain 5GB
|
||||
x-image-meta-disk-format vhd
|
||||
@ -305,132 +305,132 @@ from the request, which will have content-type of
|
||||
<title>Adding a New Virtual Machine Image</title>
|
||||
</info>
|
||||
|
||||
<para> We have created a new virtual machine image in some way
|
||||
<para>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: </para>
|
||||
image) and we wish to do two things:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para> Store the disk image data in Glance </para>
|
||||
<para>Store the disk image data in Glance</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para> Store metadata about this image in Glance </para>
|
||||
<para>Store metadata about this image in Glance</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para> We can do the above two activities in a single call to the
|
||||
<para>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 <literal>glance.example.com</literal>,
|
||||
we issue a <literal>POST</literal> request to add an image to
|
||||
Glance: </para>
|
||||
Glance:</para>
|
||||
<literallayout class="monospaced">
|
||||
POST http://glance.example.com/images/
|
||||
</literallayout>
|
||||
<para> The metadata about the image is sent to Glance in HTTP
|
||||
<para>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. </para>
|
||||
the MIME-encoded disk image data.</para>
|
||||
<section xml:id="adding-image-metadata-in-http-headers">
|
||||
<info>
|
||||
<title>Adding Image Metadata in HTTP Headers</title>
|
||||
</info>
|
||||
|
||||
<para> Glance will view as image metadata any HTTP header that
|
||||
it receives in a </para>
|
||||
<para>Glance will view as image metadata any HTTP header that
|
||||
it receives in a</para>
|
||||
<literallayout class="monospaced">
|
||||
``POST`` request where the header key is prefixed with the strings
|
||||
``x-image-meta-`` and ``x-image-meta-property-``.
|
||||
</literallayout>
|
||||
<para> The list of metadata headers that Glance accepts are
|
||||
listed below. </para>
|
||||
<para>The list of metadata headers that Glance accepts are
|
||||
listed below.</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>x-image-meta-name</literal>
|
||||
</para>
|
||||
<para> This header is optional . Its value should be the
|
||||
name of the image. </para>
|
||||
<para> Note that the name of an image <emphasis>is not
|
||||
<para>This header is optional . Its value should be the
|
||||
name of the image.</para>
|
||||
<para>Note that the name of an image <emphasis>is not
|
||||
unique to a Glance node</emphasis>. It would be an
|
||||
unrealistic expectation of users to know all the unique
|
||||
names of all other user's images. </para>
|
||||
names of all other user's images.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>x-image-meta-id</literal>
|
||||
</para>
|
||||
<para> This header is optional. </para>
|
||||
<para> When present, Glance will use the supplied identifier
|
||||
<para>This header is optional.</para>
|
||||
<para>When present, Glance will use the supplied identifier
|
||||
for the image. If the identifier already exists in that
|
||||
Glance node, then a <emphasis role="strong">409
|
||||
Conflict</emphasis> will be returned by Glance. </para>
|
||||
<para> When this header is <emphasis>not</emphasis> present,
|
||||
Conflict</emphasis> will be returned by Glance.</para>
|
||||
<para>When this header is <emphasis>not</emphasis> present,
|
||||
Glance will generate an identifier for the image and
|
||||
return this identifier in the response (see below) </para>
|
||||
return this identifier in the response (see below)</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>x-image-meta-store</literal>
|
||||
</para>
|
||||
<para> This header is optional. Valid values are one of
|
||||
<para>This header is optional. Valid values are one of
|
||||
<literal>file</literal>, <literal>s3</literal>, or
|
||||
<literal>swift</literal>
|
||||
</para>
|
||||
<para> When present, Glance will attempt to store the disk
|
||||
<para>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 <emphasis
|
||||
role="strong">400 Bad Request</emphasis>. </para>
|
||||
<para> When not present, Glance will store the disk image
|
||||
role="strong">400 Bad Request</emphasis>.</para>
|
||||
<para>When not present, Glance will store the disk image
|
||||
data in the backing store that is marked default. See the
|
||||
configuration option <literal>default_store</literal> for
|
||||
more information. </para>
|
||||
more information.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>x-image-meta-disk-format</literal>
|
||||
</para>
|
||||
<para> This header is optional. Valid values are one of
|
||||
<para>This header is optional. Valid values are one of
|
||||
<literal>aki</literal>, <literal>ari</literal>,
|
||||
<literal>ami</literal>, <literal>raw</literal>,
|
||||
<literal>iso</literal>, <literal>vhd</literal>,
|
||||
<literal>vdi</literal>, <literal>qcow2</literal>, or
|
||||
<literal>vmdk</literal>. </para>
|
||||
<para> For more information, see :doc:`About Disk and
|
||||
<literal>vmdk</literal>.</para>
|
||||
<para>For more information, see :doc:`About Disk and
|
||||
Container Formats <formats>` </para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>x-image-meta-container-format</literal>
|
||||
</para>
|
||||
<para> This header is optional. Valid values are one of
|
||||
<para>This header is optional. Valid values are one of
|
||||
<literal>aki</literal>, <literal>ari</literal>,
|
||||
<literal>ami</literal>, <literal>bare</literal>, or
|
||||
<literal>ovf</literal>. </para>
|
||||
<para> For more information, see :doc:`About Disk and
|
||||
<literal>ovf</literal>.</para>
|
||||
<para>For more information, see :doc:`About Disk and
|
||||
Container Formats <formats>` </para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>x-image-meta-size</literal>
|
||||
</para>
|
||||
<para> This header is optional. </para>
|
||||
<para> When present, Glance assumes that the expected size
|
||||
<para>This header is optional.</para>
|
||||
<para>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 <emphasis>does not
|
||||
match</emphasis> the value of this header, Glance will
|
||||
return a <emphasis role="strong">400 Bad
|
||||
Request</emphasis>. </para>
|
||||
<para> When not present, Glance will calculate the image's
|
||||
size based on the size of the request body. </para>
|
||||
Request</emphasis>.</para>
|
||||
<para>When not present, Glance will calculate the image's
|
||||
size based on the size of the request body.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>x-image-meta-checksum</literal>
|
||||
</para>
|
||||
<para> This header is optional. When present it shall be the
|
||||
<para>This header is optional. When present it shall be the
|
||||
expected <emphasis role="strong">MD5</emphasis> checksum
|
||||
of the image file data. </para>
|
||||
<para> When present, Glance will verify the checksum
|
||||
of the image file data.</para>
|
||||
<para>When present, Glance will verify the checksum
|
||||
generated from the backend store when storing your image
|
||||
against this value and return a <emphasis role="strong"
|
||||
>400 Bad Request</emphasis> if the values do not match.
|
||||
@ -440,12 +440,12 @@ POST http://glance.example.com/images/
|
||||
<para>
|
||||
<literal>x-image-meta-is-public</literal>
|
||||
</para>
|
||||
<para> This header is optional. </para>
|
||||
<para> When Glance finds the string "true"
|
||||
<para>This header is optional.</para>
|
||||
<para>When Glance finds the string "true"
|
||||
(case-insensitive), the image is marked as a public image,
|
||||
meaning that any user may view its metadata and may read
|
||||
the disk image from Glance. </para>
|
||||
<para> When not present, the image is assumed to be
|
||||
the disk image from Glance.</para>
|
||||
<para>When not present, the image is assumed to be
|
||||
<emphasis>not public</emphasis> and specific to a user.
|
||||
</para>
|
||||
</listitem>
|
||||
@ -453,39 +453,39 @@ POST http://glance.example.com/images/
|
||||
<para>
|
||||
<literal>x-image-meta-owner</literal>
|
||||
</para>
|
||||
<para> This header is optional and only meaningful for
|
||||
admins. </para>
|
||||
<para> Glance normally sets the owner of an image to be the
|
||||
<para>This header is optional and only meaningful for
|
||||
admins.</para>
|
||||
<para>Glance normally sets the owner of an image to be the
|
||||
tenant or user (depending on the "owner_is_tenant"
|
||||
configuration option) of the authenticated user issuing
|
||||
the request. However, if the authenticated user has the
|
||||
Admin role, this default may be overridden by setting this
|
||||
header to null or to a string identifying the owner of the
|
||||
image. </para>
|
||||
image.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>x-image-meta-property-*</literal>
|
||||
</para>
|
||||
<para> When Glance receives any HTTP header whose key begins
|
||||
<para>When Glance receives any HTTP header whose key begins
|
||||
with the string prefix
|
||||
<literal>x-image-meta-property-</literal>, 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
|
||||
<literal>x-image-meta-property-</literal> with dashes
|
||||
and punctuation replaced with underscores. </para>
|
||||
<para> For example, if the following HTTP header were sent: </para>
|
||||
and punctuation replaced with underscores.</para>
|
||||
<para>For example, if the following HTTP header were sent:</para>
|
||||
<literallayout class="monospaced">
|
||||
x-image-meta-property-distro Ubuntu 10.10
|
||||
</literallayout>
|
||||
<para> Then a key/value pair of "distro"/"Ubuntu 10.10" will
|
||||
be stored with the image in Glance. </para>
|
||||
<para> There is no limit on the number of free-form
|
||||
<para>Then a key/value pair of "distro"/"Ubuntu 10.10" will
|
||||
be stored with the image in Glance.</para>
|
||||
<para>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. </para>
|
||||
number of image properties.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</section>
|
||||
@ -494,22 +494,22 @@ x-image-meta-property-distro Ubuntu 10.10
|
||||
<title>Updating an Image</title>
|
||||
</info>
|
||||
|
||||
<para> Glance will view as image metadata any HTTP header that
|
||||
it receives in a </para>
|
||||
<para>Glance will view as image metadata any HTTP header that
|
||||
it receives in a</para>
|
||||
<literallayout class="monospaced">
|
||||
``PUT`` request where the header key is prefixed with the strings
|
||||
``x-image-meta-`` and ``x-image-meta-property-``.
|
||||
</literallayout>
|
||||
<para> If an image was previously reserved, and thus is in the
|
||||
<para>If an image was previously reserved, and thus is in the
|
||||
<literal>queued</literal> 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
|
||||
<literal>queued</literal> state), then including a request
|
||||
body will result in a <emphasis role="strong">409
|
||||
Conflict</emphasis> exception. </para>
|
||||
<para> On success, the <literal>PUT</literal> request will
|
||||
return the image metadata encoded as HTTP headers. </para>
|
||||
<para> See more about image statuses here: :doc:`Image Statuses
|
||||
Conflict</emphasis> exception.</para>
|
||||
<para>On success, the <literal>PUT</literal> request will
|
||||
return the image metadata encoded as HTTP headers.</para>
|
||||
<para>See more about image statuses here: :doc:`Image Statuses
|
||||
<statuses>` </para>
|
||||
</section>
|
||||
</section>
|
||||
@ -518,100 +518,100 @@ x-image-meta-property-distro Ubuntu 10.10
|
||||
<title>Requesting Image Memberships</title>
|
||||
</info>
|
||||
|
||||
<para> We want to see a list of the other system tenants (or
|
||||
<para>We want to see a list of the other system tenants (or
|
||||
users, if "owner_is_tenant" is False) that may access a given
|
||||
virtual machine image that the Glance server knows about. We
|
||||
take the `uri` field of the image data, append
|
||||
<literal>/members</literal> to it, and issue a
|
||||
<literal>GET</literal> request on the resulting URL. </para>
|
||||
<para> Continuing from the example above, in order to get the
|
||||
<literal>GET</literal> request on the resulting URL.</para>
|
||||
<para>Continuing from the example above, in order to get the
|
||||
memberships for the first public image returned, we can issue a
|
||||
<literal>GET</literal> request to the Glance server for
|
||||
<literal>http://glance.example.com/images/1/members</literal>.
|
||||
What we will get back is JSON data such as the following: </para>
|
||||
What we will get back is JSON data such as the following:</para>
|
||||
<literallayout class="monospaced">
|
||||
{'members': [
|
||||
{'member_id': 'tenant1',
|
||||
'can_share': false}
|
||||
...]}
|
||||
</literallayout>
|
||||
<para> The `member_id` field identifies a tenant with which the
|
||||
<para>The `member_id` field identifies a tenant with which the
|
||||
image is shared. If that tenant is authorized to further share
|
||||
the image, the `can_share` field is `true`. </para>
|
||||
the image, the `can_share` field is `true`.</para>
|
||||
</section>
|
||||
<section xml:id="requesting-shared-images">
|
||||
<info>
|
||||
<title>Requesting Shared Images</title>
|
||||
</info>
|
||||
|
||||
<para> We want to see a list of images which are shared with a
|
||||
<para>We want to see a list of images which are shared with a
|
||||
given tenant. We issue a <literal>GET</literal> request to
|
||||
<literal>http://glance.example.com/shared-images/tenant1</literal>.
|
||||
We will get back JSON data such as the following: </para>
|
||||
We will get back JSON data such as the following:</para>
|
||||
<literallayout class="monospaced">
|
||||
{'shared_images': [
|
||||
{'image_id': 1,
|
||||
'can_share': false}
|
||||
...]}
|
||||
</literallayout>
|
||||
<para> The `image_id` field identifies an image shared with the
|
||||
<para>The `image_id` field identifies an image shared with the
|
||||
tenant named by <emphasis>member_id</emphasis>. If the tenant is
|
||||
authorized to further share the image, the `can_share` field is
|
||||
`true`. </para>
|
||||
`true`.</para>
|
||||
</section>
|
||||
<section xml:id="adding-a-member-to-an-image">
|
||||
<info>
|
||||
<title>Adding a Member to an Image</title>
|
||||
</info>
|
||||
|
||||
<para> We want to authorize a tenant to access a private image. We
|
||||
<para>We want to authorize a tenant to access a private image. We
|
||||
issue a <literal>PUT</literal> request to
|
||||
<literal>http://glance.example.com/images/1/members/tenant1</literal>.
|
||||
With no body, this will add the membership to the image, leaving
|
||||
existing memberships unmodified and defaulting new memberships
|
||||
to have `can_share` set to `false`. We may also optionally
|
||||
attach a body of the following form: </para>
|
||||
attach a body of the following form:</para>
|
||||
<literallayout class="monospaced">
|
||||
{'member':
|
||||
{'can_share': true}
|
||||
}
|
||||
</literallayout>
|
||||
<para> If such a body is provided, both existing and new
|
||||
<para>If such a body is provided, both existing and new
|
||||
memberships will have `can_share` set to the provided value
|
||||
(either `true` or `false`). This query will return a 204 ("No
|
||||
Content") status code. </para>
|
||||
Content") status code.</para>
|
||||
</section>
|
||||
<section xml:id="removing-a-member-from-an-image">
|
||||
<info>
|
||||
<title>Removing a Member from an Image</title>
|
||||
</info>
|
||||
|
||||
<para> We want to revoke a tenant's right to access a private
|
||||
<para>We want to revoke a tenant's right to access a private
|
||||
image. We issue a <literal>DELETE</literal> request to
|
||||
<literal>http://glance.example.com/images/1/members/tenant1</literal>.
|
||||
This query will return a 204 ("No Content") status code. </para>
|
||||
This query will return a 204 ("No Content") status code.</para>
|
||||
</section>
|
||||
<section xml:id="replacing-a-membership-list-for-an-image">
|
||||
<info>
|
||||
<title>Replacing a Membership List for an Image</title>
|
||||
</info>
|
||||
|
||||
<para> The full membership list for a given image may be replaced.
|
||||
<para>The full membership list for a given image may be replaced.
|
||||
We issue a <literal>PUT</literal> request to
|
||||
<literal>http://glance.example.com/images/1/members</literal>
|
||||
with a body of the following form: </para>
|
||||
with a body of the following form:</para>
|
||||
<literallayout class="monospaced">
|
||||
{'memberships': [
|
||||
{'member_id': 'tenant1',
|
||||
'can_share': false}
|
||||
...]}
|
||||
</literallayout>
|
||||
<para> All existing memberships which are not named in the
|
||||
<para>All existing memberships which are not named in the
|
||||
replacement body are removed, and those which are named have
|
||||
their `can_share` settings changed as specified. (The
|
||||
`can_share` setting may be omitted, which will cause that
|
||||
setting to remain unchanged in the existing memberships.) All
|
||||
new memberships will be created, with `can_share` defaulting to
|
||||
`false` if it is not specified. </para>
|
||||
`false` if it is not specified.</para>
|
||||
</section>
|
||||
</chapter>
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
<chapter xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
|
||||
xml:id="general-api-information-glance">
|
||||
<title>General API Information</title>
|
||||
<?dbhtml stop-chunking?>
|
||||
|
||||
@ -38,7 +38,7 @@
|
||||
<para>This document is for software developers who develop
|
||||
applications by using the OpenStack™ Image Service
|
||||
Application Programming Interface
|
||||
(<abbrev>API</abbrev>) v1. </para>
|
||||
(<abbrev>API</abbrev>) v1.</para>
|
||||
</abstract>
|
||||
<revhistory>
|
||||
<revision>
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user