<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Using Glance’s Public APIs — Glance 2012.2.4 documentation</title>
<link rel="stylesheet" href="_static/nature.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/tweaks.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '2012.2.4',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/jquery.tweet.js"></script>
<link rel="top" title="Glance 2012.2.4 documentation" href="index.html" />
<link rel="next" title="Using Glance’s Client Tools" href="glanceclient.html" />
<link rel="prev" title="Notifications" href="notifications.html" />
</head>
<body>
<div id="header">
<h1 id="logo"><a href="http://www.openstack.org/">OpenStack</a></h1>
<ul id="navigation">
<li><a href="http://www.openstack.org/" title="Go to the Home page" class="link">Home</a></li>
<li><a href="http://www.openstack.org/projects/" title="Go to the OpenStack Projects page">Projects</a></li>
<li><a href="http://www.openstack.org/user-stories/" title="Go to the User Stories page" class="link">User Stories</a></li>
<li><a href="http://www.openstack.org/community/" title="Go to the Community page" class="link">Community</a></li>
<li><a href="http://www.openstack.org/blog/" title="Go to the OpenStack Blog">Blog</a></li>
<li><a href="http://wiki.openstack.org/" title="Go to the OpenStack Wiki">Wiki</a></li>
<li><a href="http://docs.openstack.org/" title="Go to OpenStack Documentation" class="current">Documentation</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="using-glance-s-public-apis">
<h1>Using Glance’s Public APIs<a class="headerlink" href="#using-glance-s-public-apis" title="Permalink to this headline">¶</a></h1>
<p>Glance fully implements versions 1.0, 1.1 and 2.0 of the OpenStack Images API.
The Images API specification is developed alongside Glance, but is not
considered part of the Glance project.</p>
<div class="section" id="authentication">
<h2>Authentication<a class="headerlink" href="#authentication" title="Permalink to this headline">¶</a></h2>
<p>Glance depends on Keystone and the OpenStack Identity API to handle
authentication of clients. You must obtain an authentication token from
Keystone using and send it along with all API requests to Glance through
the <tt class="docutils literal"><span class="pre">X-Auth-Token</span></tt> header. Glance will communicate back to Keystone to
verify the token validity and obtain your identity credentials.</p>
<p>See <a class="reference internal" href="authentication.html"><em>Authentication With Keystone</em></a> for more information on integrating with Keystone.</p>
</div>
<div class="section" id="using-v1-x">
<h2>Using v1.X<a class="headerlink" href="#using-v1-x" title="Permalink to this headline">¶</a></h2>
<p>For the purpose of examples, assume there is a Glance API server running
at the URL <tt class="docutils literal"><span class="pre">http://glance.example.com</span></tt> on the default port 80.</p>
<div class="section" id="list-available-images">
<h3>List Available Images<a class="headerlink" href="#list-available-images" title="Permalink to this headline">¶</a></h3>
<p>We want to see a list of available images that the authenticated user has
access to. This includes images owned by the user, images shared with the user
and public images.</p>
<p>We issue a <tt class="docutils literal"><span class="pre">GET</span></tt> request to <tt class="docutils literal"><span class="pre">http://glance.example.com/v1/images</span></tt> to
retrieve this list of available images. The data is returned as a JSON-encoded
mapping in the following format:</p>
<div class="highlight-python"><pre>{'images': [
{'uri': 'http://glance.example.com/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9',
'name': 'Ubuntu 10.04 Plain',
'disk_format': 'vhd',
'container_format': 'ovf',
'size': '5368709120'}
...]}</pre>
</div>
</div>
<div class="section" id="list-available-images-in-more-detail">
<h3>List Available Images in More Detail<a class="headerlink" href="#list-available-images-in-more-detail" title="Permalink to this headline">¶</a></h3>
<p>We want to see a more detailed list of available images that the authenticated
user has access to. This includes images owned by the user, images shared with
the user and public images.</p>
<p>We issue a <tt class="docutils literal"><span class="pre">GET</span></tt> request to <tt class="docutils literal"><span class="pre">http://glance.example.com/v1/images/detail</span></tt> to
retrieve this list of available images. The data is returned as a
JSON-encoded mapping in the following format:</p>
<div class="highlight-python"><pre>{'images': [
{'uri': 'http://glance.example.com/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9',
'name': 'Ubuntu 10.04 Plain 5GB',
'disk_format': 'vhd',
'container_format': 'ovf',
'size': '5368709120',
'checksum': 'c2e5db72bd7fd153f53ede5da5a06de3',
'created_at': '2010-02-03 09:34:01',
'updated_at': '2010-02-03 09:34:01',
'deleted_at': '',
'status': 'active',
'is_public': true,
'min_ram': 256,
'min_disk': 5,
'owner': null,
'properties': {'distro': 'Ubuntu 10.04 LTS'}},
...]}</pre>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>All timestamps returned are in UTC</p>
<p>The <cite>updated_at</cite> 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</p>
<p>The <cite>properties</cite> field is a mapping of free-form key/value pairs that
have been saved with the image metadata</p>
<p>The <cite>checksum</cite> field is an MD5 checksum of the image file data</p>
<p>The <cite>is_public</cite> field is a boolean indicating whether the image is
publically available</p>
<p>The ‘min_ram’ field is an integer specifying the minimum amount of
ram needed to run this image on an instance, in megabytes</p>
<p>The ‘min_disk’ field is an integer specifying the minimum amount of
disk space needed to run this image on an instance, in gigabytes</p>
<p class="last">The <cite>owner</cite> field is a string which may either be null or which will
indicate the owner of the image</p>
</div>
</div>
<div class="section" id="filtering-images-lists">
<h3>Filtering Images Lists<a class="headerlink" href="#filtering-images-lists" title="Permalink to this headline">¶</a></h3>
<p>Both the <tt class="docutils literal"><span class="pre">GET</span> <span class="pre">/v1/images</span></tt> and <tt class="docutils literal"><span class="pre">GET</span> <span class="pre">/v1/images/detail</span></tt> requests take query
parameters that serve to filter the returned list of images. The following
list details these query parameters.</p>
<ul>
<li><p class="first"><tt class="docutils literal"><span class="pre">name=NAME</span></tt></p>
<p>Filters images having a <tt class="docutils literal"><span class="pre">name</span></tt> attribute matching <tt class="docutils literal"><span class="pre">NAME</span></tt>.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">container_format=FORMAT</span></tt></p>
<p>Filters images having a <tt class="docutils literal"><span class="pre">container_format</span></tt> attribute matching <tt class="docutils literal"><span class="pre">FORMAT</span></tt></p>
<p>For more information, see <a class="reference internal" href="formats.html"><em>About Disk and Container Formats</em></a></p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">disk_format=FORMAT</span></tt></p>
<p>Filters images having a <tt class="docutils literal"><span class="pre">disk_format</span></tt> attribute matching <tt class="docutils literal"><span class="pre">FORMAT</span></tt></p>
<p>For more information, see <a class="reference internal" href="formats.html"><em>About Disk and Container Formats</em></a></p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">status=STATUS</span></tt></p>
<p>Filters images having a <tt class="docutils literal"><span class="pre">status</span></tt> attribute matching <tt class="docutils literal"><span class="pre">STATUS</span></tt></p>
<p>For more information, see <a class="reference internal" href="statuses.html"><em>About Image Statuses</em></a></p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">size_min=BYTES</span></tt></p>
<p>Filters images having a <tt class="docutils literal"><span class="pre">size</span></tt> attribute greater than or equal to <tt class="docutils literal"><span class="pre">BYTES</span></tt></p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">size_max=BYTES</span></tt></p>
<p>Filters images having a <tt class="docutils literal"><span class="pre">size</span></tt> attribute less than or equal to <tt class="docutils literal"><span class="pre">BYTES</span></tt></p>
</li>
</ul>
<p>These two resources also accept sort parameters:</p>
<ul>
<li><p class="first"><tt class="docutils literal"><span class="pre">sort_key=KEY</span></tt></p>
<p>Results will be ordered by the specified image attribute <tt class="docutils literal"><span class="pre">KEY</span></tt>. Accepted
values include <tt class="docutils literal"><span class="pre">id</span></tt>, <tt class="docutils literal"><span class="pre">name</span></tt>, <tt class="docutils literal"><span class="pre">status</span></tt>, <tt class="docutils literal"><span class="pre">disk_format</span></tt>,
<tt class="docutils literal"><span class="pre">container_format</span></tt>, <tt class="docutils literal"><span class="pre">size</span></tt>, <tt class="docutils literal"><span class="pre">created_at</span></tt> (default) and <tt class="docutils literal"><span class="pre">updated_at</span></tt>.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">sort_dir=DIR</span></tt></p>
<p>Results will be sorted in the direction <tt class="docutils literal"><span class="pre">DIR</span></tt>. Accepted values are <tt class="docutils literal"><span class="pre">asc</span></tt>
for ascending or <tt class="docutils literal"><span class="pre">desc</span></tt> (default) for descending.</p>
</li>
</ul>
</div>
<div class="section" id="retrieve-image-metadata">
<h3>Retrieve Image Metadata<a class="headerlink" href="#retrieve-image-metadata" title="Permalink to this headline">¶</a></h3>
<p>We want to see detailed information for a specific virtual machine image
that the Glance server knows about.</p>
<p>We have queried the Glance server for a list of images and the
data returned includes the <cite>uri</cite> field for each available image. This
<cite>uri</cite> field value contains the exact location needed to get the metadata
for a specific image.</p>
<p>Continuing the example from above, in order to get metadata about the
first image returned, we can issue a <tt class="docutils literal"><span class="pre">HEAD</span></tt> request to the Glance
server for the image’s URI.</p>
<p>We issue a <tt class="docutils literal"><span class="pre">HEAD</span></tt> request to
<tt class="docutils literal"><span class="pre">http://glance.example.com/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9</span></tt> to
retrieve complete metadata for that image. The metadata is returned as a
set of HTTP headers that begin with the prefix <tt class="docutils literal"><span class="pre">x-image-meta-</span></tt>. The
following shows an example of the HTTP headers returned from the above
<tt class="docutils literal"><span class="pre">HEAD</span></tt> request:</p>
<div class="highlight-python"><pre>x-image-meta-uri http://glance.example.com/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9
x-image-meta-name Ubuntu 10.04 Plain 5GB
x-image-meta-disk_format vhd
x-image-meta-container_format ovf
x-image-meta-size 5368709120
x-image-meta-checksum c2e5db72bd7fd153f53ede5da5a06de3
x-image-meta-created_at 2010-02-03 09:34:01
x-image-meta-updated_at 2010-02-03 09:34:01
x-image-meta-deleted_at
x-image-meta-status available
x-image-meta-is-public true
x-image-meta-min-ram 256
x-image-meta-min-disk 0
x-image-meta-owner null
x-image-meta-property-distro Ubuntu 10.04 LTS</pre>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>All timestamps returned are in UTC</p>
<p>The <cite>x-image-meta-updated_at</cite> 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</p>
<p>There may be multiple headers that begin with the prefix
<cite>x-image-meta-property-</cite>. These headers are free-form key/value pairs
that have been saved with the image metadata. The key is the string
after <cite>x-image-meta-property-</cite> and the value is the value of the header</p>
<p>The response’s <cite>ETag</cite> header will always be equal to the
<cite>x-image-meta-checksum</cite> value</p>
<p>The response’s <cite>x-image-meta-is-public</cite> value is a boolean indicating
whether the image is publically available</p>
<p class="last">The response’s <cite>x-image-meta-owner</cite> value is a string which may either
be null or which will indicate the owner of the image</p>
</div>
</div>
<div class="section" id="retrieve-raw-image-data">
<h3>Retrieve Raw Image Data<a class="headerlink" href="#retrieve-raw-image-data" title="Permalink to this headline">¶</a></h3>
<p>We want to retrieve that actual raw data for a specific virtual machine image
that the Glance server knows about.</p>
<p>We have queried the Glance server for a list of images and the
data returned includes the <cite>uri</cite> field for each available image. This
<cite>uri</cite> field value contains the exact location needed to get the metadata
for a specific image.</p>
<p>Continuing the example from above, in order to get metadata about the
first image returned, we can issue a <tt class="docutils literal"><span class="pre">HEAD</span></tt> request to the Glance
server for the image’s URI.</p>
<p>We issue a <tt class="docutils literal"><span class="pre">GET</span></tt> request to
<tt class="docutils literal"><span class="pre">http://glance.example.com/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9</span></tt> to
retrieve metadata for that image as well as the image itself encoded
into the response body.</p>
<p>The metadata is returned as a set of HTTP headers that begin with the
prefix <tt class="docutils literal"><span class="pre">x-image-meta-</span></tt>. The following shows an example of the HTTP headers
returned from the above <tt class="docutils literal"><span class="pre">GET</span></tt> request:</p>
<div class="highlight-python"><pre>x-image-meta-uri http://glance.example.com/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9
x-image-meta-name Ubuntu 10.04 Plain 5GB
x-image-meta-disk_format vhd
x-image-meta-container_format ovf
x-image-meta-size 5368709120
x-image-meta-checksum c2e5db72bd7fd153f53ede5da5a06de3
x-image-meta-created_at 2010-02-03 09:34:01
x-image-meta-updated_at 2010-02-03 09:34:01
x-image-meta-deleted_at
x-image-meta-status available
x-image-meta-is-public true
x-image-meta-min-ram 256
x-image-meta-min-disk 5
x-image-meta-owner null
x-image-meta-property-distro Ubuntu 10.04 LTS</pre>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>All timestamps returned are in UTC</p>
<p>The <cite>x-image-meta-updated_at</cite> 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</p>
<p>There may be multiple headers that begin with the prefix
<cite>x-image-meta-property-</cite>. These headers are free-form key/value pairs
that have been saved with the image metadata. The key is the string
after <cite>x-image-meta-property-</cite> and the value is the value of the header</p>
<p>The response’s <cite>Content-Length</cite> header shall be equal to the value of
the <cite>x-image-meta-size</cite> header</p>
<p>The response’s <cite>ETag</cite> header will always be equal to the
<cite>x-image-meta-checksum</cite> value</p>
<p>The response’s <cite>x-image-meta-is-public</cite> value is a boolean indicating
whether the image is publically available</p>
<p>The response’s <cite>x-image-meta-owner</cite> value is a string which may either
be null or which will indicate the owner of the image</p>
<p class="last">The image data itself will be the body of the HTTP response returned
from the request, which will have content-type of
<cite>application/octet-stream</cite>.</p>
</div>
</div>
<div class="section" id="add-a-new-image">
<h3>Add a New Image<a class="headerlink" href="#add-a-new-image" title="Permalink to this headline">¶</a></h3>
<p>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:</p>
<blockquote>
<div><ul class="simple">
<li>Store the disk image data in Glance</li>
<li>Store metadata about this image in Glance</li>
</ul>
</div></blockquote>
<p>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 <tt class="docutils literal"><span class="pre">glance.example.com</span></tt>, we issue a <tt class="docutils literal"><span class="pre">POST</span></tt> request to add an image to
Glance:</p>
<div class="highlight-python"><pre>POST http://glance.example.com/v1/images</pre>
</div>
<p>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.</p>
<p><strong>Image Metadata in HTTP Headers</strong></p>
<p>Glance will view as image metadata any HTTP header that it receives in a
<tt class="docutils literal"><span class="pre">POST</span></tt> request where the header key is prefixed with the strings
<tt class="docutils literal"><span class="pre">x-image-meta-</span></tt> and <tt class="docutils literal"><span class="pre">x-image-meta-property-</span></tt>.</p>
<p>The list of metadata headers that Glance accepts are listed below.</p>
<ul>
<li><p class="first"><tt class="docutils literal"><span class="pre">x-image-meta-name</span></tt></p>
<p>This header is required. Its value should be the name of the image.</p>
<p>Note that the name of an image <em>is not unique to a Glance node</em>. It
would be an unrealistic expectation of users to know all the unique
names of all other user’s images.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">x-image-meta-id</span></tt></p>
<p>This header is optional.</p>
<p>When present, Glance will use the supplied identifier for the image.
If the identifier already exists in that Glance node, then a
<strong>409 Conflict</strong> will be returned by Glance. The value of the header
must be a uuid in hexadecimal string notation
(i.e. 71c675ab-d94f-49cd-a114-e12490b328d9).</p>
<p>When this header is <em>not</em> present, Glance will generate an identifier
for the image and return this identifier in the response (see below)</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">x-image-meta-store</span></tt></p>
<p>This header is optional. Valid values are one of <tt class="docutils literal"><span class="pre">file</span></tt>, <tt class="docutils literal"><span class="pre">s3</span></tt>, or
<tt class="docutils literal"><span class="pre">swift</span></tt></p>
<p>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 <strong>400 Bad Request</strong>.</p>
<p>When not present, Glance will store the disk image data in the backing
store that is marked default. See the configuration option <tt class="docutils literal"><span class="pre">default_store</span></tt>
for more information.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">x-image-meta-disk_format</span></tt></p>
<p>This header is optional. Valid values are one of <tt class="docutils literal"><span class="pre">aki</span></tt>, <tt class="docutils literal"><span class="pre">ari</span></tt>, <tt class="docutils literal"><span class="pre">ami</span></tt>,
<tt class="docutils literal"><span class="pre">raw</span></tt>, <tt class="docutils literal"><span class="pre">iso</span></tt>, <tt class="docutils literal"><span class="pre">vhd</span></tt>, <tt class="docutils literal"><span class="pre">vdi</span></tt>, <tt class="docutils literal"><span class="pre">qcow2</span></tt>, or <tt class="docutils literal"><span class="pre">vmdk</span></tt>.</p>
<p>For more information, see <a class="reference internal" href="formats.html"><em>About Disk and Container Formats</em></a></p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">x-image-meta-container_format</span></tt></p>
<p>This header is optional. Valid values are one of <tt class="docutils literal"><span class="pre">aki</span></tt>, <tt class="docutils literal"><span class="pre">ari</span></tt>, <tt class="docutils literal"><span class="pre">ami</span></tt>,
<tt class="docutils literal"><span class="pre">bare</span></tt>, or <tt class="docutils literal"><span class="pre">ovf</span></tt>.</p>
<p>For more information, see <a class="reference internal" href="formats.html"><em>About Disk and Container Formats</em></a></p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">x-image-meta-size</span></tt></p>
<p>This header is optional.</p>
<p>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 <em>does not match</em> the value of this header, Glance will return a
<strong>400 Bad Request</strong>.</p>
<p>When not present, Glance will calculate the image’s size based on the size
of the request body.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">x-image-meta-checksum</span></tt></p>
<p>This header is optional. When present it shall be the expected <strong>MD5</strong>
checksum of the image file data.</p>
<p>When present, Glance will verify the checksum generated from the backend
store when storing your image against this value and return a
<strong>400 Bad Request</strong> if the values do not match.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">x-image-meta-is-public</span></tt></p>
<p>This header is optional.</p>
<p>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.</p>
<p>When not present, the image is assumed to be <em>not public</em> and owned by
a user.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">x-image-meta-min-ram</span></tt></p>
<p>This header is optional. When present it shall be the expected minimum ram
required in megabytes to run this image on a server.</p>
<p>When not present, the image is assumed to have a minimum ram requirement of 0.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">x-image-meta-min-disk</span></tt></p>
<p>This header is optional. When present it shall be the expected minimum disk
space required in gigabytes to run this image on a server.</p>
<p>When not present, the image is assumed to have a minimum disk space requirement of 0.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">x-image-meta-owner</span></tt></p>
<p>This header is optional and only meaningful for admins.</p>
<p>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.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">x-image-meta-property-*</span></tt></p>
<p>When Glance receives any HTTP header whose key begins with the string prefix
<tt class="docutils literal"><span class="pre">x-image-meta-property-</span></tt>, 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 <tt class="docutils literal"><span class="pre">x-image-meta-property-</span></tt> with dashes
and punctuation replaced with underscores.</p>
<p>For example, if the following HTTP header were sent:</p>
<div class="highlight-python"><pre>x-image-meta-property-distro Ubuntu 10.10</pre>
</div>
<p>Then a key/value pair of “distro”/”Ubuntu 10.10” will be stored with the
image in Glance.</p>
<p>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.</p>
</li>
</ul>
</div>
<div class="section" id="update-an-image">
<h3>Update an Image<a class="headerlink" href="#update-an-image" title="Permalink to this headline">¶</a></h3>
<p>Glance will view as image metadata any HTTP header that it receives in a
<tt class="docutils literal"><span class="pre">PUT</span></tt> request where the header key is prefixed with the strings
<tt class="docutils literal"><span class="pre">x-image-meta-</span></tt> and <tt class="docutils literal"><span class="pre">x-image-meta-property-</span></tt>.</p>
<p>If an image was previously reserved, and thus is in the <tt class="docutils literal"><span class="pre">queued</span></tt> 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 <tt class="docutils literal"><span class="pre">queued</span></tt> state), then
including a request body will result in a <strong>409 Conflict</strong> exception.</p>
<p>On success, the <tt class="docutils literal"><span class="pre">PUT</span></tt> request will return the image metadata encoded as HTTP
headers.</p>
<p>See more about image statuses here: <a class="reference internal" href="statuses.html"><em>Image Statuses</em></a></p>
</div>
<div class="section" id="list-image-memberships">
<h3>List Image Memberships<a class="headerlink" href="#list-image-memberships" title="Permalink to this headline">¶</a></h3>
<p>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 <cite>uri</cite> field of the image data,
append <tt class="docutils literal"><span class="pre">/members</span></tt> to it, and issue a <tt class="docutils literal"><span class="pre">GET</span></tt> request on the resulting URL.</p>
<p>Continuing from the example above, in order to get the memberships for the
first image returned, we can issue a <tt class="docutils literal"><span class="pre">GET</span></tt> request to the Glance
server for
<tt class="docutils literal"><span class="pre">http://glance.example.com/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9/members</span></tt>
. What we will get back is JSON data such as the following:</p>
<div class="highlight-python"><pre>{'members': [
{'member_id': 'tenant1',
'can_share': false}
...]}</pre>
</div>
<p>The <cite>member_id</cite> field identifies a tenant with which the image is shared. If
that tenant is authorized to further share the image, the <cite>can_share</cite> field is
<cite>true</cite>.</p>
</div>
<div class="section" id="list-shared-images">
<h3>List Shared Images<a class="headerlink" href="#list-shared-images" title="Permalink to this headline">¶</a></h3>
<p>We want to see a list of images which are shared with a given tenant. We issue
a <tt class="docutils literal"><span class="pre">GET</span></tt> request to <tt class="docutils literal"><span class="pre">http://glance.example.com/v1/shared-images/tenant1</span></tt>. We
will get back JSON data such as the following:</p>
<div class="highlight-python"><pre>{'shared_images': [
{'image_id': '71c675ab-d94f-49cd-a114-e12490b328d9',
'can_share': false}
...]}</pre>
</div>
<p>The <cite>image_id</cite> field identifies an image shared with the tenant named by
<em>member_id</em>. If the tenant is authorized to further share the image, the
<cite>can_share</cite> field is <cite>true</cite>.</p>
</div>
<div class="section" id="add-a-member-to-an-image">
<h3>Add a Member to an Image<a class="headerlink" href="#add-a-member-to-an-image" title="Permalink to this headline">¶</a></h3>
<p>We want to authorize a tenant to access a private image. We issue a <tt class="docutils literal"><span class="pre">PUT</span></tt>
request to
<tt class="docutils literal"><span class="pre">http://glance.example.com/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9/members/tenant1</span></tt>
. With no body, this will add the membership to the image, leaving existing
memberships unmodified and defaulting new memberships to have <cite>can_share</cite>
set to <cite>false</cite>. We may also optionally attach a body of the following form:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="p">{</span><span class="s">'member'</span><span class="p">:</span>
<span class="p">{</span><span class="s">'can_share'</span><span class="p">:</span> <span class="n">true</span><span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
<p>If such a body is provided, both existing and new memberships will have
<cite>can_share</cite> set to the provided value (either <cite>true</cite> or <cite>false</cite>). This query
will return a 204 (“No Content”) status code.</p>
</div>
<div class="section" id="remove-a-member-from-an-image">
<h3>Remove a Member from an Image<a class="headerlink" href="#remove-a-member-from-an-image" title="Permalink to this headline">¶</a></h3>
<p>We want to revoke a tenant’s right to access a private image. We issue a
<tt class="docutils literal"><span class="pre">DELETE</span></tt> request to <tt class="docutils literal"><span class="pre">http://glance.example.com/v1/images/1/members/tenant1</span></tt>.
This query will return a 204 (“No Content”) status code.</p>
</div>
<div class="section" id="replace-a-membership-list-for-an-image">
<h3>Replace a Membership List for an Image<a class="headerlink" href="#replace-a-membership-list-for-an-image" title="Permalink to this headline">¶</a></h3>
<p>The full membership list for a given image may be replaced. We issue a <tt class="docutils literal"><span class="pre">PUT</span></tt>
request to
<tt class="docutils literal"><span class="pre">http://glance.example.com/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9/members</span></tt>
with a body of the following form:</p>
<div class="highlight-python"><pre>{'memberships': [
{'member_id': 'tenant1',
'can_share': false}
...]}</pre>
</div>
<p>All existing memberships which are not named in the replacement body are
removed, and those which are named have their <cite>can_share</cite> settings changed as
specified. (The <cite>can_share</cite> setting may be omitted, which will cause that
setting to remain unchanged in the existing memberships.) All new memberships
will be created, with <cite>can_share</cite> defaulting to <cite>false</cite> if it is not specified.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Using Glance’s Public APIs</a><ul>
<li><a class="reference internal" href="#authentication">Authentication</a></li>
<li><a class="reference internal" href="#using-v1-x">Using v1.X</a><ul>
<li><a class="reference internal" href="#list-available-images">List Available Images</a></li>
<li><a class="reference internal" href="#list-available-images-in-more-detail">List Available Images in More Detail</a></li>
<li><a class="reference internal" href="#filtering-images-lists">Filtering Images Lists</a></li>
<li><a class="reference internal" href="#retrieve-image-metadata">Retrieve Image Metadata</a></li>
<li><a class="reference internal" href="#retrieve-raw-image-data">Retrieve Raw Image Data</a></li>
<li><a class="reference internal" href="#add-a-new-image">Add a New Image</a></li>
<li><a class="reference internal" href="#update-an-image">Update an Image</a></li>
<li><a class="reference internal" href="#list-image-memberships">List Image Memberships</a></li>
<li><a class="reference internal" href="#list-shared-images">List Shared Images</a></li>
<li><a class="reference internal" href="#add-a-member-to-an-image">Add a Member to an Image</a></li>
<li><a class="reference internal" href="#remove-a-member-from-an-image">Remove a Member from an Image</a></li>
<li><a class="reference internal" href="#replace-a-membership-list-for-an-image">Replace a Membership List for an Image</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="notifications.html"
title="previous chapter">Notifications</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="glanceclient.html"
title="next chapter">Using Glance’s Client Tools</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/glanceapi.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="glanceclient.html" title="Using Glance’s Client Tools"
accesskey="N">next</a></li>
<li class="right" >
<a href="notifications.html" title="Notifications"
accesskey="P">previous</a> |</li>
<li><a href="index.html">Glance 2012.2.4 documentation</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2010-present, OpenStack, LLC..
Last updated on May 13, 2013.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>
