Jump to: navigation, search

Difference between revisions of "Obsolete:GlanceAPISpec"

m (Dan Smith moved page GlanceAPISpec to Obsolete:GlanceAPISpec)
 
(12 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
__NOTOC__
+
 
 
= Glance API Specification =
 
= Glance API Specification =
  
Line 7: Line 7:
 
** Parallax - Image Registry service
 
** Parallax - Image Registry service
 
** Teller - Image Delivery service
 
** Teller - Image Delivery service
−
* Nova Integration
+
* Client Classes
−
** `nova.image.service.[[GlanceImageService]]` - An adapter in Nova to use Glance for retrieving and querying for images
+
** `glance.client.[[GlanceClient]]` - A client used in Nova to query Glance about images
−
*** `nova.image.service.[[ParallaxClient]]` - A client tool for querying Parallax about available images
+
*** `glance.client.[[ParallaxClient]]` - A client tool for querying Parallax about available images
−
*** `nova.image.service.[[TellerClient]]` - A client tool for the chunked retrieval of an image
+
*** `glance.client.[[TellerClient]]` - A client tool for the chunked retrieval of an image
  
−
<<[[TableOfContents]]()>>
+
__TOC__
  
 
== Parallax API Commands ==
 
== Parallax API Commands ==
 +
 +
This section describes the Parallax REST API for creating, listing, modifying, and deleting image metadata.
 +
 
=== Fetch id/name basic information on all public images ===
 
=== Fetch id/name basic information on all public images ===
  
Line 58: Line 61:
 
     "image_type": "kernel"
 
     "image_type": "kernel"
 
     "is_public": true,
 
     "is_public": true,
−
     "metadata": { "mykey": "myvalue" },
+
     "properties": { "mykey": "myvalue" },
 
     "files": [ { "location": "swift://user:passwd@acct/container/obj.tar.gz.0",
 
     "files": [ { "location": "swift://user:passwd@acct/container/obj.tar.gz.0",
 
                 "size": 101 } ]
 
                 "size": 101 } ]
Line 69: Line 72:
 
==== Notes ====
 
==== Notes ====
  
−
The `metadata` element is a mapping of custom metadata the image may have saved with it.
+
The `properties` element is a mapping of custom key/value pairs the image may have saved with it.
  
 
The `files` element is a list of mappings containing the chunks comprising an image along with the chunk's size
 
The `files` element is a list of mappings containing the chunks comprising an image along with the chunk's size
Line 86: Line 89:
 
<pre><nowiki>
 
<pre><nowiki>
 
{
 
{
−
"id": 1,
+
"image":
−
"name": "My Image",
+
  {
−
"status": "available",
+
  "id": 1,
−
"image_type": "kernel"
+
  "name": "My Image",
−
"is_public": true,
+
  "status": "available",
−
"metadata": { "mykey": "myvalue" },
+
  "image_type": "kernel"
−
"files": [ { "location": "swift://user:passwd@acct/container/obj.tar.gz.0",
+
  "is_public": true,
 +
  "properties": { "mykey": "myvalue" },
 +
  "files": [ { "location": "swift://user:passwd@acct/container/obj.tar.gz.0",
 
             "size": 101 } ]
 
             "size": 101 } ]
 +
  }
 
}
 
}
 
</nowiki></pre>
 
</nowiki></pre>
Line 100: Line 106:
 
==== Notes ====
 
==== Notes ====
  
−
The `metadata` element is a mapping of custom metadata the image may have saved with it.
+
The reason the returned dict contains only a single element, 'image', is for XML conversion purposes, where the root element will be `<image>` and not the root XML namespace.
 +
 
 +
The `properties` element is a mapping of custom key/value pairs the image may have saved with it.
  
 
The `files` element is a list of mappings containing the chunks comprising an image along with the chunk's size
 
The `files` element is a list of mappings containing the chunks comprising an image along with the chunk's size
Line 121: Line 129:
 
<pre><nowiki>
 
<pre><nowiki>
 
{
 
{
 +
"image":
 +
  {
 
   "name": "My Image",
 
   "name": "My Image",
 
   "status": "available",
 
   "status": "available",
 
   "image_type": "kernel"
 
   "image_type": "kernel"
 
   "is_public": true,
 
   "is_public": true,
−
   "metadata": { "mykey": "myvalue" },
+
   "properties": { "mykey": "myvalue" },
 
   "files": [ { "location": "swift://user:passwd@acct/container/obj.tar.gz.0",
 
   "files": [ { "location": "swift://user:passwd@acct/container/obj.tar.gz.0",
−
              "size": 101 } ]
+
            "size": 101 } ]
 +
  }
 
}
 
}
 
</nowiki></pre>
 
</nowiki></pre>
Line 137: Line 148:
 
<pre><nowiki>
 
<pre><nowiki>
 
{
 
{
−
   "id": 2349823,
+
"image":
 +
  {
 +
   "id": 1,
 
   "name": "My Image",
 
   "name": "My Image",
 
   "status": "available",
 
   "status": "available",
 
   "image_type": "kernel"
 
   "image_type": "kernel"
 
   "is_public": true,
 
   "is_public": true,
−
   "metadata": { "mykey": "myvalue" },
+
   "properties": { "mykey": "myvalue" },
 
   "files": [ { "location": "swift://user:passwd@acct/container/obj.tar.gz.0",
 
   "files": [ { "location": "swift://user:passwd@acct/container/obj.tar.gz.0",
−
              "size": 101 } ]
+
            "size": 101 } ]
 +
  }
 
}
 
}
 
</nowiki></pre>
 
</nowiki></pre>
Line 151: Line 165:
 
==== Notes ====
 
==== Notes ====
  
−
The `metadata` element is a mapping of custom metadata the image may have saved with it.
+
The reason the body dict and result dict contains only a single element, 'image', is for XML conversion purposes, where the root element will be `<image>` and not the root XML namespace.
 +
 
 +
The `properties` element is a mapping of custom key/value pairs the image may have saved with it.
  
 
The `files` element is a list of mappings containing the chunks comprising an image along with the chunk's size
 
The `files` element is a list of mappings containing the chunks comprising an image along with the chunk's size
Line 168: Line 184:
 
<pre><nowiki>
 
<pre><nowiki>
 
{
 
{
 +
"image":
 +
  {
 
   "id": 2349823,
 
   "id": 2349823,
 
   "name": "My Image",
 
   "name": "My Image",
Line 173: Line 191:
 
   "image_type": "kernel"
 
   "image_type": "kernel"
 
   "is_public": true,
 
   "is_public": true,
−
   "metadata": { "mykey": "myvalue" },
+
   "properties": { "mykey": "myvalue" },
 
   "files": [ { "location": "swift://user:passwd@acct/container/obj.tar.gz.0",
 
   "files": [ { "location": "swift://user:passwd@acct/container/obj.tar.gz.0",
−
              "size": 101 } ]
+
            "size": 101 } ]
 +
  }
 
}
 
}
 
</nowiki></pre>
 
</nowiki></pre>
Line 185: Line 204:
 
<pre><nowiki>
 
<pre><nowiki>
 
{
 
{
 +
"image":
 +
  {
 
   "id": 2349823,
 
   "id": 2349823,
 
   "name": "My Image",
 
   "name": "My Image",
Line 192: Line 213:
 
   "metadata": { "mykey": "myvalue" },
 
   "metadata": { "mykey": "myvalue" },
 
   "files": [ { "location": "swift://user:passwd@acct/container/obj.tar.gz.0",
 
   "files": [ { "location": "swift://user:passwd@acct/container/obj.tar.gz.0",
−
              "size": 101 } ]
+
            "size": 101 } ]
 +
  }
 
}
 
}
 
</nowiki></pre>
 
</nowiki></pre>
Line 199: Line 221:
 
==== Notes ====
 
==== Notes ====
  
−
The `metadata` element is a mapping of custom metadata the image may have saved with it.
+
The reason the body dict and result dict contains only a single element, 'image', is for XML conversion purposes, where the root element will be `<image>` and not the root XML namespace.
 +
 
 +
The `properties` element is a mapping of custom key/value pairs the image may have saved with it.
  
 
The `files` element is a list of mappings containing the chunks comprising an image along with the chunk's size
 
The `files` element is a list of mappings containing the chunks comprising an image along with the chunk's size
Line 222: Line 246:
  
 
== Teller API Commands ==
 
== Teller API Commands ==
 +
 +
This section describes the Teller REST API.
  
 
=== Fetch an Image ===
 
=== Fetch an Image ===
Line 227: Line 253:
  
 
<pre><nowiki>
 
<pre><nowiki>
−
GET /images?uri=<Parallax URI for Image>
+
GET http://teller.openstack.org/images/<ID>
 
</nowiki></pre>
 
</nowiki></pre>
  
  
−
Returns
+
Returns the virtual machine image data as response body.
−
 
 
−
Image data as response body.
 
  
 
==== Exceptions ====
 
==== Exceptions ====
  
 
404:: Image was not found
 
404:: Image was not found
 +
 +
=== Store an Image ===
 +
 +
 +
<pre><nowiki>
 +
POST http://teller.openstack.org/images/<ID>
 +
</nowiki></pre>
 +
 +
 +
The body of the POST request shall be a mime-encoded blob of data representing the image to be stored.
 +
 +
Note: All this does is store the raw image data in Teller's backend.  If you are responsible for storing the metadata about the image, you should do that with a similar call to Parallax's API.
 +
 +
Immediately returns a mapping of image information indicating status of the image:
 +
 +
 +
<pre><nowiki>
 +
{
 +
'image':
 +
  {
 +
    'id': identifier for image,
 +
    'status': 'pending'
 +
  }
 +
}
 +
</nowiki></pre>
 +
 +
 +
=== Update an Image ===
 +
 +
There is no operation for updating an image.  All images are immutable once created.
 +
 +
=== Delete an Image ===
 +
 +
 +
<pre><nowiki>
 +
DELETE http://teller.openstack.org/images/<ID>
 +
</nowiki></pre>
 +
 +
 +
Returns 200 OK on success
 +
 +
Returns 404 when image with URI does not exist

Latest revision as of 19:06, 11 May 2016

Glance API Specification

Glance <=> Nova Integration requires these components:

  • Glance - VM Image Management Service
    • Parallax - Image Registry service
    • Teller - Image Delivery service
  • Client Classes
    • `glance.client.GlanceClient` - A client used in Nova to query Glance about images
      • `glance.client.ParallaxClient` - A client tool for querying Parallax about available images
      • `glance.client.TellerClient` - A client tool for the chunked retrieval of an image

Parallax API Commands

This section describes the Parallax REST API for creating, listing, modifying, and deleting image metadata.

Fetch id/name basic information on all public images

GET http://parallax.openstack.org/images


Returns a mapping containing a list of mappings containing details information about the public images encoded in JSON: 


{
"images":
  [
  {"id": 1, "name": "My Image 1"},
  {"id": 2, "name": "My Image 2"},
  ]
}


Fetch detailed information on all public images

GET http://parallax.openstack.org/images/detail


Returns a mapping containing a list of mappings containing details information about the public images encoded in JSON: 


{
"images":
  [
    {
    "id": 1,
    "name": "My Image",
    "status": "available",
    "image_type": "kernel"
    "is_public": true,
    "properties": { "mykey": "myvalue" },
    "files": [ { "location": "swift://user:passwd@acct/container/obj.tar.gz.0",
                 "size": 101 } ]
    }
  ]
}


Notes

The `properties` element is a mapping of custom key/value pairs the image may have saved with it.

The `files` element is a list of mappings containing the chunks comprising an image along with the chunk's size

Fetch a single image's metadata

GET http://parallax.openstack.org/images/<ID>


Returns the image's metadata encoded in JSON: 


{
"image":
  {
  "id": 1,
  "name": "My Image",
  "status": "available",
  "image_type": "kernel"
  "is_public": true,
  "properties": { "mykey": "myvalue" },
  "files": [ { "location": "swift://user:passwd@acct/container/obj.tar.gz.0",
             "size": 101 } ]
  }
}


Notes

The reason the returned dict contains only a single element, 'image', is for XML conversion purposes, where the root element will be `<image>` and not the root XML namespace.

The `properties` element is a mapping of custom key/value pairs the image may have saved with it.

The `files` element is a list of mappings containing the chunks comprising an image along with the chunk's size

Exceptions

404:: Image was not found

Register/create a new image

POST http://parallax.openstack.org/images


The body of the request shall be a JSON encoded mapping of the image's metadata: 


{
"image":
  {
  "name": "My Image",
  "status": "available",
  "image_type": "kernel"
  "is_public": true,
  "properties": { "mykey": "myvalue" },
  "files": [ { "location": "swift://user:passwd@acct/container/obj.tar.gz.0",
             "size": 101 } ]
  }
}


The returned response, is successful, will be a JSON encoded mapping of the newly-created image in Parallax, including a populated `id` column with the new image's internal identifier: 


{
"image":
  {
  "id": 1,
  "name": "My Image",
  "status": "available",
  "image_type": "kernel"
  "is_public": true,
  "properties": { "mykey": "myvalue" },
  "files": [ { "location": "swift://user:passwd@acct/container/obj.tar.gz.0",
             "size": 101 } ]
  }
}


Notes

The reason the body dict and result dict contains only a single element, 'image', is for XML conversion purposes, where the root element will be `<image>` and not the root XML namespace.

The `properties` element is a mapping of custom key/value pairs the image may have saved with it.

The `files` element is a list of mappings containing the chunks comprising an image along with the chunk's size

Update an existing image's metadata

PUT http://parallax.openstack.org/images/<ID>


The body of the request shall be a JSON encoded mapping of the image's metadata: 


{
"image":
  {
  "id": 2349823,
  "name": "My Image",
  "status": "disabled",
  "image_type": "kernel"
  "is_public": true,
  "properties": { "mykey": "myvalue" },
  "files": [ { "location": "swift://user:passwd@acct/container/obj.tar.gz.0",
             "size": 101 } ]
  }
}


The returned response, if successful, will be a JSON encoded mapping of the updated image metadata in Parallax: 


{
"image":
  {
  "id": 2349823,
  "name": "My Image",
  "status": "disabled",
  "image_type": "kernel"
  "is_public": true,
  "metadata": { "mykey": "myvalue" },
  "files": [ { "location": "swift://user:passwd@acct/container/obj.tar.gz.0",
             "size": 101 } ]
  }
}


Notes

The reason the body dict and result dict contains only a single element, 'image', is for XML conversion purposes, where the root element will be `<image>` and not the root XML namespace.

The `properties` element is a mapping of custom key/value pairs the image may have saved with it.

The `files` element is a list of mappings containing the chunks comprising an image along with the chunk's size

Exceptions

404:: Image was not found

Delete an existing image from the registry

DELETE http://parallax.openstack.org/images/<ID>


The body of the request will be ignored.

Exceptions

404:: Image was not found

Teller API Commands

This section describes the Teller REST API.

Fetch an Image

GET http://teller.openstack.org/images/<ID>


Returns the virtual machine image data as response body.

Exceptions

404:: Image was not found

Store an Image

POST http://teller.openstack.org/images/<ID>


The body of the POST request shall be a mime-encoded blob of data representing the image to be stored.

Note: All this does is store the raw image data in Teller's backend. If you are responsible for storing the metadata about the image, you should do that with a similar call to Parallax's API.

Immediately returns a mapping of image information indicating status of the image: 


{
'image':
  {
    'id': identifier for image,
    'status': 'pending'
  }
}


Update an Image

There is no operation for updating an image. All images are immutable once created.

Delete an Image

DELETE http://teller.openstack.org/images/<ID>


Returns 200 OK on success

Returns 404 when image with URI does not exist

Retrieved from "https://wiki.openstack.org/w/index.php?title=Obsolete:GlanceAPISpec&oldid=125135"