OpenStack API Documentation

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	xsd:string	Filters the image list by a specified container format, such as `ovf`, `bare`, `aki`, `ari`, or `ami`.
disk_format (Optional)	query	xsd:string	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:string	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	xsd:string	Filters the image list by a specified container format, such as `ovf`, `bare`, `aki`, `ari`, or `ami`.
disk_format (Optional)	query	xsd:string	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:string	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	xsd:boolean	Indicates whether the specified owner is authorized to share the specified image. If the owner can share the image, this value is `true`. Otherwise, this value is `false`. The owner ID, which is the tenant ID, is specified in the request URI.

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, this call 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	Indicates whether the specified owner is authorized to share the specified image. If the owner can share the image, this value is `true`. Otherwise, this value is `false`. The owner ID, which is the tenant ID, is specified in the request URI.

{
    "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_id}

List shared images

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

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
owner_id	URI	xsd:string	Owner ID, which is the tenant ID.

Response parameters

Parameter	Style	Type	Description
image_id	URI	xsd:string	Image ID stored through the image API. Typically a UUID.
can_share	plain	xsd:boolean	Indicates whether the specified owner is authorized to share the specified image. If the owner can share the image, this value is `true`. Otherwise, this value is `false`. The owner ID, which is the tenant ID, is specified in the request URI.

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

This operation does not accept a request body.