14
14
License for the specific language governing permissions and limitations
20
Glance has a RESTful API that exposes both metadata about registered virtual
21
machine images and the image data itself.
23
A host that runs the ``bin/glance-api`` service is said to be a *Glance API
26
Assume there is a Glance API server running at the URL
27
``http://glance.example.com``.
29
Let's walk through how a user might request information from this server.
31
Requesting a List of Public VM Images
32
-------------------------------------
34
We want to see a list of available virtual machine images that the Glance
37
We issue a ``GET`` request to ``http://glance.example.com/images/`` to retrieve
38
this list of available *public* images. The data is returned as a JSON-encoded
17
Using Glance's Public APIs
18
==========================
20
Glance fully implements versions 1.0, 1.1 and 2.0 of the OpenStack Images API.
21
The Images API specification is developed alongside Glance, but is not
22
considered part of the Glance project.
27
Glance depends on Keystone and the OpenStack Identity API to handle
28
authentication of clients. You must obtain an authentication token from
29
Keystone using and send it along with all API requests to Glance through
30
the ``X-Auth-Token`` header. Glance will communicate back to Keystone to
31
verify the token validity and obtain your identity credentials.
33
See :doc:`authentication` for more information on integrating with Keystone.
38
For the purpose of examples, assume there is a Glance API server running
39
at the URL ``http://glance.example.com`` on the default port 80.
44
We want to see a list of available images that the authenticated user has
45
access to. This includes images owned by the user, images shared with the user
48
We issue a ``GET`` request to ``http://glance.example.com/v1/images`` to
49
retrieve this list of available images. The data is returned as a JSON-encoded
39
50
mapping in the following format::
42
{'uri': 'http://glance.example.com/images/71c675ab-d94f-49cd-a114-e12490b328d9',
53
{'uri': 'http://glance.example.com/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9',
43
54
'name': 'Ubuntu 10.04 Plain',
44
55
'disk_format': 'vhd',
45
56
'container_format': 'ovf',
46
57
'size': '5368709120'}
51
All images returned from the above `GET` request are *public* images
54
Requesting Detailed Metadata on Public VM Images
55
------------------------------------------------
57
We want to see more detailed information on available virtual machine images
58
that the Glance server knows about.
60
We issue a ``GET`` request to ``http://glance.example.com/images/detail`` to
61
retrieve this list of available *public* images. The data is returned as a
61
List Available Images in More Detail
62
************************************
64
We want to see a more detailed list of available images that the authenticated
65
user has access to. This includes images owned by the user, images shared with
66
the user and public images.
68
We issue a ``GET`` request to ``http://glance.example.com/v1/images/detail`` to
69
retrieve this list of available images. The data is returned as a
62
70
JSON-encoded mapping in the following format::
65
{'uri': 'http://glance.example.com/images/71c675ab-d94f-49cd-a114-e12490b328d9',
73
{'uri': 'http://glance.example.com/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9',
66
74
'name': 'Ubuntu 10.04 Plain 5GB',
67
75
'disk_format': 'vhd',
68
76
'container_format': 'ovf',
156
162
Results will be sorted in the direction ``DIR``. Accepted values are ``asc``
157
163
for ascending or ``desc`` (default) for descending.
160
Requesting Detailed Metadata on a Specific Image
161
------------------------------------------------
165
Retrieve Image Metadata
166
***********************
163
168
We want to see detailed information for a specific virtual machine image
164
169
that the Glance server knows about.
166
We have queried the Glance server for a list of public images and the
171
We have queried the Glance server for a list of images and the
167
172
data returned includes the `uri` field for each available image. This
168
173
`uri` field value contains the exact location needed to get the metadata
169
174
for a specific image.
171
176
Continuing the example from above, in order to get metadata about the
172
first public image returned, we can issue a ``HEAD`` request to the Glance
177
first image returned, we can issue a ``HEAD`` request to the Glance
173
178
server for the image's URI.
175
180
We issue a ``HEAD`` request to
176
``http://glance.example.com/images/71c675ab-d94f-49cd-a114-e12490b328d9`` to
181
``http://glance.example.com/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9`` to
177
182
retrieve complete metadata for that image. The metadata is returned as a
178
183
set of HTTP headers that begin with the prefix ``x-image-meta-``. The
179
184
following shows an example of the HTTP headers returned from the above
180
185
``HEAD`` request::
182
x-image-meta-uri http://glance.example.com/images/71c675ab-d94f-49cd-a114-e12490b328d9
187
x-image-meta-uri http://glance.example.com/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9
183
188
x-image-meta-name Ubuntu 10.04 Plain 5GB
184
189
x-image-meta-disk_format vhd
185
190
x-image-meta-container_format ovf
218
223
be null or which will indicate the owner of the image
221
Retrieving a Virtual Machine Image
222
----------------------------------
226
Retrieve Raw Image Data
227
***********************
224
229
We want to retrieve that actual raw data for a specific virtual machine image
225
230
that the Glance server knows about.
227
We have queried the Glance server for a list of public images and the
232
We have queried the Glance server for a list of images and the
228
233
data returned includes the `uri` field for each available image. This
229
234
`uri` field value contains the exact location needed to get the metadata
230
235
for a specific image.
232
237
Continuing the example from above, in order to get metadata about the
233
first public image returned, we can issue a ``HEAD`` request to the Glance
238
first image returned, we can issue a ``HEAD`` request to the Glance
234
239
server for the image's URI.
236
241
We issue a ``GET`` request to
237
``http://glance.example.com/images/71c675ab-d94f-49cd-a114-e12490b328d9`` to
242
``http://glance.example.com/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9`` to
238
243
retrieve metadata for that image as well as the image itself encoded
239
244
into the response body.
303
308
at ``glance.example.com``, we issue a ``POST`` request to add an image to
306
POST http://glance.example.com/images/
311
POST http://glance.example.com/v1/images
308
313
The metadata about the image is sent to Glance in HTTP headers. The body
309
314
of the HTTP request to the Glance API will be the MIME-encoded disk
313
Adding Image Metadata in HTTP Headers
314
*************************************
318
**Image Metadata in HTTP Headers**
316
320
Glance will view as image metadata any HTTP header that it receives in a
317
321
``POST`` request where the header key is prefixed with the strings
471
475
append ``/members`` to it, and issue a ``GET`` request on the resulting URL.
473
477
Continuing from the example above, in order to get the memberships for the
474
first public image returned, we can issue a ``GET`` request to the Glance
478
first image returned, we can issue a ``GET`` request to the Glance
476
``http://glance.example.com/images/71c675ab-d94f-49cd-a114-e12490b328d9/members``
480
``http://glance.example.com/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9/members``
477
481
. What we will get back is JSON data such as the following::
503
507
`can_share` field is `true`.
506
Adding a Member to an Image
507
---------------------------
510
Add a Member to an Image
511
************************
509
513
We want to authorize a tenant to access a private image. We issue a ``PUT``
511
``http://glance.example.com/images/71c675ab-d94f-49cd-a114-e12490b328d9/members/tenant1``
515
``http://glance.example.com/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9/members/tenant1``
512
516
. With no body, this will add the membership to the image, leaving existing
513
517
memberships unmodified and defaulting new memberships to have `can_share`
514
518
set to `false`. We may also optionally attach a body of the following form::
522
526
will return a 204 ("No Content") status code.
525
Removing a Member from an Image
526
-------------------------------
529
Remove a Member from an Image
530
*****************************
528
532
We want to revoke a tenant's right to access a private image. We issue a
529
``DELETE`` request to ``http://glance.example.com/images/1/members/tenant1``.
533
``DELETE`` request to ``http://glance.example.com/v1/images/1/members/tenant1``.
530
534
This query will return a 204 ("No Content") status code.
533
Replacing a Membership List for an Image
534
----------------------------------------
537
Replace a Membership List for an Image
538
**************************************
536
540
The full membership list for a given image may be replaced. We issue a ``PUT``
538
``http://glance.example.com/images/71c675ab-d94f-49cd-a114-e12490b328d9/members``
542
``http://glance.example.com/v1/images/71c675ab-d94f-49cd-a114-e12490b328d9/members``
539
543
with a body of the following form::
541
545
{'memberships': [
added
removed
doc/source/glanceapi.rst
