Jump to: navigation, search

Difference between revisions of "Obsolete:GlanceAPISpec"

Line 9: Line 9:
 
* Nova Integration
 
* Nova Integration
 
** `nova.image.service.[[GlanceImageService]]` - An adapter in Nova to use Glance for retrieving and querying for images
 
** `nova.image.service.[[GlanceImageService]]` - An adapter in Nova to use Glance for retrieving and querying for images
−
*** `nova.image.service.[[ParallaxClient]]` - A client tool for querying Parallax about available images
+
*** `nova.image.service.[[ParallaxClient]]` - A client tool for querying Parallax about available images and for adding and updating image information
 
*** `nova.image.service.[[TellerClient]]` - A client tool for the chunked retrieval of an image
 
*** `nova.image.service.[[TellerClient]]` - A client tool for the chunked retrieval of an image
  
Line 16: Line 16:
 
== Parallax API Commands ==
 
== Parallax API Commands ==
  
−
This section describes the Parallax REST API for creating, listing, modifying, and deleting image metadata.
+
This section describes the Parallax REST API for creating, listing, modifying, and deleting images.
  
 
=== Fetch id/name basic information on all public images ===
 
=== Fetch id/name basic information on all public images ===
Line 117: Line 117:
  
 
=== Register/create a new image ===
 
=== Register/create a new image ===
 +
 +
In keeping with both the EC2 and Rackspace modus operandi, new images are created in the system by specifying an already-running instance and giving the new image a name.  A new image is created by looking at the existing instance and creating a snapshot of that instance.
  
  
Line 123: Line 125:
 
</nowiki></pre>
 
</nowiki></pre>
  
 +
 +
==== Request Elements ====
 +
 +
{| border="1" cellpadding="2" cellspacing="0"
 +
| '''Element Name'''
 +
| '''Required?'''
 +
| '''Type'''
 +
|-
 +
|  ''name''     
 +
|      Yes     
 +
|    String
 +
|-
 +
|  ''instanceId''
 +
|      Yes     
 +
|    String
 +
|-
 +
|  ''tags''     
 +
|      No       
 +
|    Mapping
 +
|}
 +
 +
==== Examples ====
 +
===== Request =====
  
 
The body of the request shall be a JSON encoded mapping of the image's metadata:
 
The body of the request shall be a JSON encoded mapping of the image's metadata:
Line 131: Line 156:
 
"image":
 
"image":
 
   {
 
   {
−
   "name": "My Image",
+
   "name": "Fedora 11 (database ops)",
−
   "status": "available",
+
   "instanceId": "i-10dflka",
−
   "image_type": "kernel"
+
   "tags": {"purpose": "database"},
−
  "is_public": true,
 
−
  "metadata": { "mykey": "myvalue" },
 
−
  "files": [ { "location": "swift://user:passwd@acct/container/obj.tar.gz.0",
 
−
            "size": 101 } ]
 
 
   }
 
   }
 
}
 
}
Line 143: Line 164:
  
  
−
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:
+
===== Response =====
 +
 
 +
The returned response, will be a JSON encoded mapping of information about the newly-created image in Parallax, including a populated `id` column with the new image's internal identifier and a status of the request:
  
  
 
<pre><nowiki>
 
<pre><nowiki>
 
{
 
{
 +
"request":
 +
  {
 +
  "requestId": "00e8da9b-9ae8-4bdd-af76-af89bed2262f"
 +
  },
 
"image":
 
"image":
 
   {
 
   {
−
   "id": 1,
+
   "id": 12345678,
−
   "name": "My Image",
+
   "name": "Fedora 11 (database ops)",
−
   "status": "available",
+
   "status": "pending",
−
   "image_type": "kernel"
+
   "tags": { "purpose": "database" },
−
  "is_public": true,
 
−
  "metadata": { "mykey": "myvalue" },
 
−
  "files": [ { "location": "swift://user:passwd@acct/container/obj.tar.gz.0",
 
−
            "size": 101 } ]
 
 
   }
 
   }
 
}
 
}
Line 165: Line 188:
 
==== Notes ====
 
==== 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 `tags` element is a mapping of custom metadata the image may have saved with it.
−
 
 
−
The `metadata` element is a mapping of custom metadata 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 ===
 
=== Update an existing image's metadata ===
Line 262: Line 281:
  
 
404:: Image was not found
 
404:: Image was not found
−
 
−
=== TODO -- Store an Image ===
 
−
 
−
 
−
<pre><nowiki>
 
−
POST /images?uri=<Parallax URI for Image>
 
−
</nowiki></pre>
 
−
 
−
 
−
Immediately returns a mapping of image information indicating status of the image:
 
−
 
−
 
−
<pre><nowiki>
 
−
{
 
−
'image':
 
−
  {
 
−
    'id': identifier for image,
 
−
    'status': 'pending',
 
−
    'job_id': an identifier for the asynchronous job that is storing the image?
 
−
  }
 
−
}
 
−
</nowiki></pre>
 

Revision as of 20:32, 18 November 2010

Glance API Specification

Glance <=> Nova Integration requires these components:

  • Glance - VM Image Management Service
    • Parallax - Image Registry service
    • Teller - Image Delivery service
  • Nova Integration
    • `nova.image.service.GlanceImageService` - An adapter in Nova to use Glance for retrieving and querying for images
      • `nova.image.service.ParallaxClient` - A client tool for querying Parallax about available images and for adding and updating image information
      • `nova.image.service.TellerClient` - A client tool for the chunked retrieval of an image

<<TableOfContents()>>

Parallax API Commands

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

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,
    "metadata": { "mykey": "myvalue" },
    "files": [ { "location": "swift://user:passwd@acct/container/obj.tar.gz.0",
                 "size": 101 } ]
    }
  ]
}


Notes

The `metadata` element is a mapping of custom metadata 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,
  "metadata": { "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 `metadata` element is a mapping of custom metadata 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

In keeping with both the EC2 and Rackspace modus operandi, new images are created in the system by specifying an already-running instance and giving the new image a name. A new image is created by looking at the existing instance and creating a snapshot of that instance. 


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


Request Elements

Element Name Required? Type
name Yes String
instanceId Yes String
tags No Mapping

Examples

Request

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


{
"image":
  {
  "name": "Fedora 11 (database ops)",
  "instanceId": "i-10dflka",
  "tags": {"purpose": "database"},
  }
}


Response

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


{
"request":
  {
  "requestId": "00e8da9b-9ae8-4bdd-af76-af89bed2262f"
  },
"image":
  {
  "id": 12345678,
  "name": "Fedora 11 (database ops)",
  "status": "pending",
  "tags": { "purpose": "database" },
  }
}


Notes

The `tags` element is a mapping of custom metadata the image may have saved with it.

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,
  "metadata": { "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 `metadata` element is a mapping of custom metadata 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 /images?uri=<Parallax URI for Image>


Returns the virtual machine image data as response body.

Exceptions

404:: Image was not found

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