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
300
{
    "versions": [
        {
            "status": "EXPERIMENTAL",
            "id": "v3.0",
            "links": [
                {
                    "href": "http://23.253.228.211:9292/v3/",
                    "rel": "self"
                }
            ]
        },
        {
            "status": "CURRENT",
            "id": "v2.3",
            "links": [
                {
                    "href": "http://23.253.228.211:9292/v2/",
                    "rel": "self"
                }
            ]
        },
        {
            "status": "SUPPORTED",
            "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 and does not return a response body.

GET
/versions
List API versions

Shows details for the Image service API v1.

 
Normal response codes
200
{
    "versions": [
        {
            "status": "EXPERIMENTAL",
            "id": "v3.0",
            "links": [
                {
                    "href": "http://23.253.228.211:9292/v3/",
                    "rel": "self"
                }
            ]
        },
        {
            "status": "CURRENT",
            "id": "v2.3",
            "links": [
                {
                    "href": "http://23.253.228.211:9292/v2/",
                    "rel": "self"
                }
            ]
        },
        {
            "status": "SUPPORTED",
            "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 all public VM images.

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

Filters the image list by an image name, in string format.

container_format (Optional) query xsd:string

Filters the image list by a container format. A valid value is aki, ami, ari, bare, docker, ova, or ovf.

disk_format (Optional) query xsd:string

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

status (Optional) query xsd:string

Filters the image list by a 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 minimum image size, in bytes.

size_max (Optional) query xsd:string

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

changes-since (Optional) query xsd:dateTime

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

Response parameters
Parameter Style Type Description
images plain xsd:list

A list of image objects.

uri plain xsd:string

The exact location needed to get the metadata for the image.

name plain xsd:string

The name of the image, in string format.

disk_format plain xsd:string

The disk format of the image.

container_format plain xsd:string

The container format of the image.

size plain xsd:string

The size of the image, in bytes.

{
    "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 an Image service node. The API cannot expect users to know the names of images that other users own.

disk_format plain xsd:string

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 disk format for your image to one of these values:

  • aki

    An Amazon kernel image.

  • ami

    An Amazon machine image.

  • ari

    An Amazon ramdisk image.

  • 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.

  • raw

    Unstructured disk image format.

  • vhd

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

  • vdi

    Supported by VirtualBox VM monitor and the QEMU emulator.

  • vmdk

    A common disk format that supported by many VM monitors.

container_format plain xsd:string

A container format defines the file format of the file that contains the image and metadata about the actual VM.

For a VM image with a bare container format, the image is a blob of unstructured data.

You can set the container format to one of these values:

  • aki

    Amazon kernel image.

  • ami

    Amazon machine image.

  • ari

    Amazon ramdisk image.

  • bare

    No container or metadata envelope for the image.

  • docker

    Docker tar archive of the container filesystem.

  • ova

    OVA container format.

  • ovf

    OVF container format.

createImage (Optional) plain ImageForCreate

Local file path where the image is stored.

Response parameters
Parameter Style Type Description
location plain xsd:anyURI

A URI location for the image.

GET
/v1/images/detail
List images with details

Lists all available images with details.

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

Filters the image list by an image name, in string format.

container_format (Optional) query xsd:string

Filters the image list by a container format. A valid value is aki, ami, ari, bare, docker, ova, or ovf.

disk_format (Optional) query xsd:string

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

status (Optional) query xsd:string

Filters the image list by a 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 minimum image size, in bytes.

size_max (Optional) query xsd:string

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

changes-since (Optional) query xsd:dateTime

Filters the image list to those images that have changed since a 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
Error response codes
forbidden (403)
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.

HEAD
/v1/images/​{image_id}​
Show image metadata

Shows the image metadata information in the body of the response.

 

The Image system does not return a response body for the HEAD operation.

Example requests and responses:

  • Show image metadata:

    http://glance.example.com/v1/images/03bc0a8b-659c-4de9-b6bd-13c6e86e6455
                          

    X-Image-Meta-Checksum → 8a40c862b5735975d82605c1dd395796
    X-Image-Meta-Container_format → aki
    X-Image-Meta-Created_at → 2016-01-06T03:22:20.000000
    X-Image-Meta-Deleted → false
    X-Image-Meta-Disk_format → aki
    X-Image-Meta-Id → 03bc0a8b-659c-4de9-b6bd-13c6e86e6455
    X-Image-Meta-Is_public → true
    X-Image-Meta-Min_disk → 0
    X-Image-Meta-Min_ram → 0
    X-Image-Meta-Name → cirros-0.3.4-x86_64-uec-kernel
    X-Image-Meta-Owner → 13cc6052265b41529e2fd0fc461fa8ef
    X-Image-Meta-Protected → false
    X-Image-Meta-Size → 4979632
    X-Image-Meta-Status → deactivated
    X-Image-Meta-Updated_at → 2016-02-25T03:02:05.000000
    X-Openstack-Request-Id → req-d5208320-28ed-4c22-b628-12dc6456d983
    

If the request succeeds, the operation returns the 200 response code.

If there is an image size mismatch detected with the X-Image-Meta-Size, the operation returns a 409 response code.

Normal response codes
200
Error response codes
itemNotFound (404), 409
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.

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 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.

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 owner is authorized to share the image.

If the owner can share the image, this value is true. Otherwise, this value is false.

Specify the owner ID, which is the tenant ID, is in the request URI.

This operation does not return a response body.

PUT
/v1/images/​{image_id}​/members/​{owner_id}​
Add members to image

Adds one or more members 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 owner is authorized to share the image.

If the owner can share the image, this value is true. Otherwise, this value is false.

Specify the owner ID, which is the tenant ID, is 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

The UUID of the 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 an owner shares. 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 owner is authorized to share the image.

If the owner can share the image, this value is true. Otherwise, this value is false.

Specify the owner ID, which is the tenant ID, is in the request URI.

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

This operation does not accept a request body.