Image service API v1 (SUPPORTED)

Loads images for use at launch time by the Compute API. Also, assigns metadata to images.

Some cloud implementations do not expose this API and offer pretested images only.

Cloud providers can configure property protections that prevent non-administrative users from updating and deleting protected properties. For more information, see Image property protection in the OpenStack Cloud Administrator Guide .

API versions

GET
/
List API versions

Lists information about all Image service API versions.

 
Normal response codes
200, 300
{
    "versions": [
        {
            "status": "CURRENT",
            "id": "v2.2",
            "links": [
                {
                    "href": "http://23.253.228.211:9292/v2/",
                    "rel": "self"
                }
            ]
        },
        {
            "status": "SUPPORTED",
            "id": "v2.1",
            "links": [
                {
                    "href": "http://23.253.228.211:9292/v2/",
                    "rel": "self"
                }
            ]
        },
        {
            "status": "SUPPORTED",
            "id": "v2.0",
            "links": [
                {
                    "href": "http://23.253.228.211:9292/v2/",
                    "rel": "self"
                }
            ]
        },
        {
            "status": "SUPPORTED",
            "id": "v1.1",
            "links": [
                {
                    "href": "http://23.253.228.211:9292/v1/",
                    "rel": "self"
                }
            ]
        },
        {
            "status": "SUPPORTED",
            "id": "v1.0",
            "links": [
                {
                    "href": "http://23.253.228.211:9292/v1/",
                    "rel": "self"
                }
            ]
        }
    ]
}

This operation does not accept a request body.

Images

GET
/v1/images
List images

Lists public VM images.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
name (Optional) query xsd:string

Filters the image list by a specified image name, in string format.

container_format (Optional) query imageapi:ImageStatus

Filters the image list by a specified container format, such as ovf, bare, aki, ari, or ami.

disk_format (Optional) query imageapi:UUID

Filters the image list by a specified disk format. A valid value is aki, ari, ami, raw, iso, vhd, vdi, qcow2, or vmdk.

status (Optional) query xsd:int

Filters the image list by a specified status. A valid value is queued, saving, active, killed, deleted, or pending_delete.

size_min (Optional) query xsd:string

Filters the image list by a specified minimum image size, in bytes.

size_max (Optional) query xsd:string

Filters the image list by a specified maximum image size, in bytes.

changes-since (Optional) query xsd:dateTime

Filters the image list to those images that have changed since a specified time stamp value.

{
    "images": [
        {
            "uri": "http://glance.example.com/images/71c675ab-d94f-49cd-a114-e12490b328d9",
            "name": "Ubuntu 10.04 Plain",
            "disk_format": "vhd",
            "container_format": "ovf",
            "size": "5368709120"
        },
        {
            "...": "..."
        }
    ]
}
POST
/v1/images
Create image

Registers a virtual machine (VM) image.

 
Normal response codes
202
Request parameters
Parameter Style Type Description
name plain xsd:string

Name for the image. Note that the name of an image is not unique to a Glance node. The API cannot expect users to know the names of images owned by others.

disk_format plain xsd:string

A valid value is aki, ari, ami, raw, iso, vhd, vdi, qcow2, or vmdk.

The disk format of a VM image is the format of the underlying disk image. Virtual appliance vendors have different formats for laying out the information contained in a VM disk image.

You can set the container format for your image to one of the following values:

  • raw

    Unstructured disk image format.

  • vhd

    VHD disk format, a common disk format used by VM monitors from VMWare, Xen, Microsoft, VirtualBox, and others.

  • vmdk

    A common disk format that supported by many VM monitors.

  • vdi

    Supported by VirtualBox VM monitor and the QEMU emulator.

  • iso

    An archive format for the data contents of an optical disc, such as CDROM.

  • qcow2

    Supported by the QEMU emulator that can expand dynamically and supports Copy on Write.

  • aki

    An Amazon kernel image.

  • ari

    An Amazon ramdisk image.

  • ami

    An Amazon machine image.

container_format plain xsd:string

The container format refers to whether the VM image is in a file format that also contains metadata about the actual VM.

Container formats include OVF and Amazon AMI. In addition, a VM image might not have a container format. Instead, the image is a blob of unstructured data.

You can set the container format to one of the following formats:

  • ovf

    OVF container format.

  • bare

    No container or metadata envelope for the image.

  • aki

    Amazon kernel image.

  • ari

    Amazon ramdisk image.

  • ami

    Amazon machine image.

createImage (Optional) ImageForCreate
Response parameters
Parameter Style Type Description
location plain xsd:anyURI

A location for the image identified by a URI.

GET
/v1/images/detail
List image details

Lists details for available images.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
name (Optional) query xsd:string

Filters the image list by a specified image name, in string format.

container_format (Optional) query imageapi:ImageStatus

Filters the image list by a specified container format, such as ovf, bare, aki, ari, or ami.

disk_format (Optional) query imageapi:UUID

Filters the image list by a specified disk format. A valid value is aki, ari, ami, raw, iso, vhd, vdi, qcow2, or vmdk.

status (Optional) query xsd:int

Filters the image list by a specified status. A valid value is queued, saving, active, killed, deleted, or pending_delete.

size_min (Optional) query xsd:string

Filters the image list by a specified minimum image size, in bytes.

size_max (Optional) query xsd:string

Filters the image list by a specified maximum image size, in bytes.

changes-since (Optional) query xsd:dateTime

Filters the image list to those images that have changed since a specified time stamp value.

Response parameters
Parameter Style Type Description
next (Optional) plain xsd:anyURI

Show the next item in the list.

previous (Optional) plain xsd:anyURI

Show the previous item in the list.

{
    "images": [
        {
            "uri": "http://glance.example.com/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"
            }
        },
        {
            "...": "..."
        }
    ]
}
GET
/v1/images/​{image_id}​
Show image details and image binary

Shows the image details as headers and the image binary in the body of the response.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
image_id URI xsd:string

Image ID stored through the image API. Typically a UUID.

{
    "images": [
        {
            "uri": "http://glance.example.com/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"
            }
        },
        {
            "...": "..."
        }
    ]
}

This operation does not accept a request body.

PUT
/v1/images/​{image_id}​
Update image

Updates an image, uploads an image file, or updates metadata for an image.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
image_id URI xsd:string

Image ID stored through the image API. Typically a UUID.

Response parameters
Parameter Style Type Description
location plain xsd:anyURI

This operation does not accept a request body.

DELETE
/v1/images/​{image_id}​
Delete image

Deletes the specified image.

 
Normal response codes
204
Request parameters
Parameter Style Type Description
image_id URI xsd:string

Image ID stored through the image API. Typically a UUID.

This operation does not accept a request body and does not return a response body.

Members

PUT
/v1/images/​{image_id}​/members
Replace member

Replaces a membership list for an image.

 
Normal response codes
204
Request parameters
Parameter Style Type Description
image_id URI xsd:string

Image ID stored through the image API. Typically a UUID.

memberships plain String
can_share plain ImageForCreate

This operation does not return a response body.

PUT
/v1/images/​{image_id}​/members/​{owner_id}​
Add member

Adds a member to an image.

 

If you omit the request body from this call, this request adds the membership to the image, leaves the existing memberships unmodified, and sets the can_share attribute to false for new memberships.

Normal response codes
204
Request parameters
Parameter Style Type Description
image_id URI xsd:string

Image ID stored through the image API. Typically a UUID.

owner_id URI xsd:string

Owner ID, which is the tenant ID.

can_share plain xsd:boolean

To give an owner access to a private image, set to true. The owner ID is the tenant ID.

{
    "members": [
        {
            "member_id": "tenant1",
            "can_share": false
        },
        {
            "member_id": "tenant2",
            "can_share": false
        }
    ]
}

This operation does not return a response body.

DELETE
/v1/images/​{image_id}​/members/​{owner_id}​
Remove member

Removes a member from an image.

 
Normal response codes
204
Request parameters
Parameter Style Type Description
image_id URI xsd:string

Image ID stored through the image API. Typically a UUID.

owner_id URI xsd:string

Owner ID, which is the tenant ID.

member_id plain csapi:uuid

ID of member with which an image is shared.

This operation does not return a response body.

Shared images

GET
/v1/shared-images/​{owner}​
List shared images

Lists the VM images shared with a specified owner. The owner ID is the tenant ID.

 
Normal response codes
200
Response parameters
Parameter Style Type Description
image_id plain xsd:anyURI

The ID of the image that is shared with the specified owner. The owner ID is the tenant ID.

can_share plain xsd:anyURI

If the owner is authorized to further share the image, the can_share field is set to true. The owner ID is the tenant ID.

{
    "shared_images": [
        {
            "image_id": "71c675ab-d94f-49cd-a114-e12490b328d9",
            "can_share": false
        },
        {
            "...": "..."
        }
    ]
}

This operation does not accept a request body.