openstack/glance
Code Issues Proposed changes

WADL to RST migration (part 2 - images)

Browse Source 
This brings the Images API Reference to the glance tree as part of the
effort described here:
https://wiki.openstack.org/wiki/Documentation/Migrate#API_Reference_Plan

This patch contains the content of the Images v2 API reference converted
to RST. The content has been corrected where I noticed divergences with
reality (which actually happened a lot, so this patch contains a lot of
revisions).

Tasks and metadefs are submitted as separate patches.

Change-Id: If69c469da7f28f090a2286ec0b115d9bcaac4fbf
Closes-Bug: #1550457
Closes-Bug: #1589264
Closes-Bug: #1592715
This commit is contained in:
bria4010 2016-06-22 14:04:32 -04:00
parent 514d10ad53
commit c028c2d23e
24 changed files with 2674 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

132
api-ref/source/v2/images-data.inc Normal file
View File

@ -0,0 +1,132 @@
.. -*- rst -*-
Image data
**********
Uploads and downloads raw image data.
*These operations may be restricted to administrators. Consult your cloud
operator's documentation for details.*
Upload binary image data
~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: PUT /v2/images/{image_id}/file
Uploads binary image data.
*(Since Image API v2.0)*
Set the ``Content-Type`` request header to ``application/octet-stream``.
Example call:
::
curl -i -X PUT -H "X-Auth-Token: $token" \
-H "Content-Type: application/octet-stream" \
-d @/home/glance/ubuntu-12.10.qcow2 \
$image_url/v2/images/{image_id}/file
**Preconditions**
Before you can store binary image data, you must meet the following
preconditions:
- The image must exist.
- You must set the disk and container formats in the image.
- The image status must be ``queued``.
- Your image storage quota must be sufficient.
- The size of the data that you want to store must not exceed the
size that the OpenStack Image service allows.
**Synchronous Postconditions**
- With correct permissions, you can see the image status as
``active`` through API calls.
- With correct access, you can see the stored data in the storage
system that the OpenStack Image Service manages.
**Troubleshooting**
- If you cannot store the data, either your request lacks required
information or you exceeded your allotted quota. Ensure that you
meet the preconditions and run the request again. If the request
fails again, review your API request.
- The storage back ends for storing the data must have enough free
storage space to accommodate the size of the data.
Normal response codes: 204
Error response codes: 400, 401, 403, 404, 409, 410, 413, 415, 503
Request
-------
.. rest_parameters:: images-parameters.yaml
- Content-type: Content-Type-data
- image_id: image_id-in-path
Download binary image data
~~~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: GET /v2/images/{image_id}/file
Downloads binary image data.
*(Since Image API v2.0)*
Example call: ``curl -i -X GET -H "X-Auth-Token: $token"
$image_url/v2/images/{image_id}/file``
The response body contains the raw binary data that represents the
actual virtual disk. The ``Content-Type`` header contains the
``application/octet-stream`` value. The ``Content-MD5`` header
contains an MD5 checksum of the image data. Use this checksum to
verify the integrity of the image data.
**Preconditions**
- The image must exist.
**Synchronous Postconditions**
- You can download the binary image data in your machine if the
image has image data.
- If image data exists, the call returns the HTTP ``200`` response code.
- If no image data exists, the call returns the HTTP ``204`` (No Content)
response code.
- If no image record exists, the call returns the HTTP ``404`` response code.
Normal response codes: 200, 204
Error response codes: 400, 403, 404
Request
-------
.. rest_parameters:: images-parameters.yaml
- image_id: image_id-in-path
- Content-Range: Content-Range
Response
--------
.. rest_parameters:: images-parameters.yaml
- Content-Type: Content-Type-data-response
- Content-Md5: Content-Md5
- Content-Length: Content-Length

645
api-ref/source/v2/images-images-v2.inc Normal file
View File

@ -0,0 +1,645 @@
.. -*- rst -*-
Images
******
Creates, lists, shows, updates, deletes, and performs other operations on
images.
General information
~~~~~~~~~~~~~~~~~~~
**Images**
An *image* is represented by a JSON Object, that is, as a set of key:value
pairs. Some of these keys are *base properties* that are managed by the
Image service. The remainder are properties put on the image by the operator
or the image owner.
Here's some important information about image properties:
* The base properties are always included in the image representation. A
base property that doesn't have a value is displayed with its value set
to ``null`` (that is, the JSON null data type).
* Additional properties, whose value is always a string data type, are
only included in the response if they have a value.
* Since version 2.2, the Images API allows an operator to configure
*property protections*, by which the create, read, update, and delete
operations on specific image properties may be restricted to particular
user roles. Consult the documentation of your cloud operator for details.
* Arguably the most important properties of an image are its *id*, which
uniquely identifies the image, its *status*, which indicates the current
situation of the image (which, in turn, indicates what you can do with the
image), and its *visibility*, which indicates who has access to the image.
**Image status**
The possible status values for images are presented in the following table.
.. list-table::
:header-rows: 1
* - Status
- Description
* - queued
- The Image service reserved an image ID for the image in the catalog
but did not yet upload any image data.
* - saving
- The Image service is is in the process of saving the the raw data for
the image into the backing store.
* - active
- The image is active and ready for consumption in the Image service.
* - killed
- An image data upload error occurred.
* - deleted
- The Image service retains information about the image but the image is
no longer available for use.
* - pending_delete
- Similar to the ``deleted`` status. An image in this state is not
recoverable.
* - deactivated
- The image data is not available for use.
**Image visibility**
The possible values for image visibility are presented in the following table.
.. list-table::
:header-rows: 1
* - Visibility
- Description
* - ``public``
- Any tenant may access the image. Additionally, the image appears in
the default image list of all tenants.
* - ``private``
- Only the tenant who owns the image, or any tenants the image has been
shared with, may access the image. Additionally, the image appears in
the default image list of the owning tenant.
Create an image
~~~~~~~~~~~~~~~
.. rest_method:: POST /v2/images
Creates a catalog record for an operating system disk image.
*(Since Image API v2.0)*
The ``Location`` response header contains the URI for the image.
The response body contains the new image entity.
Synchronous Postconditions
- With correct permissions, you can see the image status as
``queued`` through API calls.
Normal response codes: 201
Error response codes: 400, 401, 403, 409, 413, 415
Request
-------
.. rest_parameters:: images-parameters.yaml
- container_format: container_format-in-request
- disk_format: disk_format-in-request
- id: id-in-request
- min_disk: min_disk-in-request
- min_ram: min_ram-in-request
- name: name-in-request
- protected: protected-in-request
- tags: tags-in-request
- visibility: visibility-in-request
Additionally, you may include additional properties specified as key:value
pairs, where the value must be a string data type. Keys and values are limited
to 255 chars in length. Available key names may be limited by the cloud's
property protection configuration.
Request Example
---------------
.. literalinclude:: samples/image-create-request.json
:language: json
Response Parameters
-------------------
.. rest_parameters:: images-parameters.yaml
- Location: Location
- checksum: checksum
- container_format: container_format
- created_at: created_at
- disk_format: disk_format
- file: file
- id: id
- min_disk: min_disk
- min_ram: min_ram
- name: name
- owner: owner
- protected: protected
- schema: schema-image
- self: self
- size: size
- status: status
- tags: tags
- updated_at: updated_at
- virtual_size: virtual_size
- visibility: visibility
- direct_url: direct_url
- locations: locations
The response may also include additional properties specified as key:value
pairs if additional properties were specified in the request.
Response Example
----------------
.. literalinclude:: samples/image-create-response.json
:language: json
Show image details
~~~~~~~~~~~~~~~~~~
.. rest_method:: GET /v2/images/{image_id}
Shows details for an image.
*(Since Image API v2.0)*
The response body contains a single image entity.
Preconditions
- The image must exist.
Normal response codes: 200
Error response codes: 400, 401, 403, 404
Request
-------
.. rest_parameters:: images-parameters.yaml
- image_id: image_id-in-path
Response Parameters
-------------------
.. rest_parameters:: images-parameters.yaml
- checksum: checksum
- container_format: container_format
- created_at: created_at
- disk_format: disk_format
- file: file
- id: id
- min_disk: min_disk
- min_ram: min_ram
- name: name
- owner: owner
- protected: protected
- schema: schema-image
- self: self
- size: size
- status: status
- tags: tags
- updated_at: updated_at
- virtual_size: virtual_size
- visibility: visibility
- direct_url: direct_url
- locations: locations
The response may also include additional properties specified as key:value
pairs if such properties have been added to the image by the owner or an
administrator.
Response Example
----------------
.. literalinclude:: samples/image-show-response.json
:language: json
Show images
~~~~~~~~~~~
.. rest_method:: GET /v2/images
Lists public virtual machine (VM) images.
*(Since Image API v2.0)*
**Pagination**
Returns a subset of the larger collection of images and a link that you can use
to get the next set of images. You should always check for the presence of a
``next`` link and use it as the URI in a subsequent HTTP GET request. You
should follow this pattern until a ``next`` link is no longer provided.
The ``next`` link preserves any query parameters that you send in your initial
request. You can use the ``first`` link to jump back to the first page of the
collection. If you prefer to paginate through images manually, use the
``limit`` and ``marker`` parameters.
**Query Filters**
The list operation accepts query parameters to filter the response.
A client can provide direct comparison filters by using most image attributes,
such as ``name=Ubuntu``, ``visibility=public``, and so on.
To filter using image tags, use the filter ``tag`` (note the singular). To
filter on multiple tags, include each tag separately in the query. For
example, to find images with the tag **ready**, include ``tag=ready`` in your
query string. To find images tagged with **ready** and **approved**, include
``tag=ready&tag=approved`` in your query string. (Note that only images
containing *both* tags will be included in the response.)
A client cannot use any ``link`` in the json-schema, such as self, file, or
schema, to filter the response.
You can list VM images that have a status of ``active``, ``queued``, or
``saving``.
**The** ``in`` **Operator**
As a convenience, you may specify several values for any of the following
fields by using the ``in`` operator:
* container_format
* disk_format
* id
* name
* status
For most of these, usage is straight forward. For example, to list images
in queued or saving status, use:
``GET /v2/images?status=in:saving,queued``
To find images in a particular list of image IDs, use:
``GET /v2/images?id=in:3afb79c1-131a-4c38-a87c-bc4b801d14e6,2e011209-660f-44b5-baf2-2eb4babae53d``
Using the ``in`` operator with the ``name`` property of images can be a bit
trickier, depending upon how creatively you have named your images. The
general rule is that if an image name contains a comma (``,``), you must
enclose the entire name in quotation marks (``"``). As usual, you must URL
encode any characters that require it.
For example, to find images named ``glass, darkly`` or ``share me``, you would
use the following filter specification:
``GET v2/images?name=in:"glass,%20darkly",share%20me``
As with regular filtering by name, you must specify the complete name you are
looking for. Thus, for example, the query string ``name=in:glass,share`` will
only match images with the exact name ``glass`` or the exact name ``share``.
It will not find an image named ``glass, darkly`` or an image named ``share
me``.
**Size Comparison Filters**
You can use the ``size_min`` and ``size_max`` query parameters to filter images
that are greater than or less than the image size. The size, in bytes, is the
size of an image on disk.
For example, to filter the container to include only images that are from 1 to
4 MB, set the ``size_min`` query parameter to ``1048576`` and the ``size_max``
query parameter to ``4194304``.
.. _v2-comparison-ops:
**Time Comparison Filters**
You can use a *comparison operator* along with the ``created_at`` or
``updated_at`` fields to filter your results. Specify the operator first, a
colon (``:``) as a separator, and then the time in `ISO 8601 Format
<https://en.wikipedia.org/wiki/ISO_8601>`_. Available comparison operators
are:
.. list-table::
:header-rows: 1
* - Operator
- Description
* - ``gt``
- Return results more recent than the specified time.
* - ``gte``
- Return any results matching the specified time and also any more recent
results.
* - ``eq``
- Return any results matching the specified time exactly.
* - ``neq``
- Return any results that do not match the specified time.
* - ``lt``
- Return results older than the specified time.
* - ``lte``
- Return any results matching the specified time and also any older
results.
For example:
.. code-block:: console
GET v2/images?created_at=gt:2016-04-18T21:38:54Z
**Sorting**
You can use query parameters to sort the results of this operation.
- ``sort_key``. Sorts by an image attribute. Sorts in the natural
sorting direction of the image attribute.
- ``sort_dir``. Sorts in a sort direction.
- ``sort``. Sorts by one or more sets of attribute and sort
direction combinations. If you omit the sort direction in a set,
the default is ``desc``.
To sort the response, use the ``sort_key`` and ``sort_dir`` query
parameters:
.. code-block:: console
GET /v2/images?sort_key=name&sort_dir=asc&sort_key=status&sort_dir=desc
Alternatively, specify the ``sort`` query parameter:
.. code-block:: console
GET /v2/images?sort=name:asc,status:desc
.. note::
Although this call has been available since verison 2.0 of this API,
it has been enhanced from release to release. The filtering and
sorting functionality and syntax described above apply to the most
recent release (Newton). Not everything described above will be
available in prior releases.
Normal response codes: 200
Error response codes: 400, 401, 403
Request
-------
.. rest_parameters:: images-parameters.yaml
- limit: limit
- marker: marker
- name: name-in-query
- owner: owner-in-query
- status: status-in-query
- tag: tag-in-query
- visibility: visibility-in-query
- member_status: member_status-in-query
- size_max: size_max
- size_min: size_min
- created_at: created_at-in-query
- updated_at: updated_at-in-query
- sort_dir: sort_dir
- sort_key: sort_key
- sort: sort
Response Parameters
-------------------
.. rest_parameters:: images-parameters.yaml
- images: images
- first: first
- next: next
- schema: schema-images
Response Example
----------------
.. literalinclude:: samples/images-list-response.json
:language: json
.. _v2-image-update:
Update an image
~~~~~~~~~~~~~~~
.. rest_method:: PATCH /v2/images/{image_id}
Updates an image.
*(Since Image API v2.0)*
Conceptually, you update an image record by patching the JSON representation of
the image, passing a request body conforming to one of the following media
types:
- ``application/openstack-images-v2.0-json-patch`` *(deprecated)*
- ``application/openstack-images-v2.1-json-patch`` *(since Image API v2.1)*
Attempting to make a PATCH call using some other media type will provoke a
response code of 415 (Unsupported media type).
The ``application/openstack-images-v2.1-json-patch`` media type provides a
useful and compatible subset of the functionality defined in JavaScript Object
Notation (JSON) Patch `RFC6902 <http://tools.ietf.org/html/rfc6902>`_, which
defines the ``application/json-patch+json`` media type.
.. note::
The ``application/openstack-images-v2.0-json-patch`` media type is based on
draft 4 of the standard. Its use is deprecated.
For information about the PATCH method and the available media types, see
`Image API v2 HTTP PATCH media types
<http://specs.openstack.org/openstack/glance-specs/specs/api/v2
/http-patch-image-api-v2.html>`_.
Attempting to modify some image properties will cause the entire request to
fail with a 403 (Forbidden) response code:
- An attempt to modify any of the "base" image properties that are managed by
the Image Service. These are the properties specified as read only in the
:ref:`Image Schema <image-schema>`.
- An attempt to create or modify image properties for which you do not have
permission to do so. This depends upon how property protections are
configured in the OpenStack cloud in which you are making the call. Consult
your cloud's documentation for details.
Normal response codes: 200
Error response codes: 400, 401, 403, 404, 413, 415
Request
-------
.. rest_parameters:: images-parameters.yaml
- Content-Type: Content-Type-patch
- image_id: image_id-in-path
The request body must conform to the
``application/openstack-images-v2.1-json-patch`` media type definition (see
above).
Request Example
---------------
.. literalinclude:: samples/image-update-request.json
:language: json
Response Parameters
-------------------
.. rest_parameters:: images-parameters.yaml
- checksum: checksum
- container_format: container_format
- created_at: created_at
- disk_format: disk_format
- file: file
- id: id
- min_disk: min_disk
- min_ram: min_ram
- owner: owner
- name: name
- protected: protected
- schema: schema-image
- self: self
- size: size
- status: status
- tags: tags
- updated_at: updated_at
- visibility: visibility
- direct_url: direct_url
- locations: locations
Response Example
----------------
.. literalinclude:: samples/image-update-response.json
:language: json
Delete an image
~~~~~~~~~~~~~~~
.. rest_method:: DELETE /v2/images/{image_id}
(Since Image API v2.0) Deletes an image.
You cannot delete images with the ``protected`` attribute set to
``true`` (boolean).
Preconditions
- You can delete an image in any status except ``deleted``.
- The ``protected`` attribute of the image cannot be ``true``.
- You have permission to perform image deletion under the configured image
deletion policy.
Synchronous Postconditions
- The response is empty and returns the HTTP ``204`` response code.
- The API deletes the image from the images index.
- If the image has associated binary image data in the storage backend, the
OpenStack Image service deletes the data.
Normal response codes: 204
Error response codes: 400, 401, 403, 404, 409
Request
-------
.. rest_parameters:: images-parameters.yaml
- image_id: image_id-in-path
Deactivate image
~~~~~~~~~~~~~~~~
.. rest_method:: POST /v2/images/{image_id}/actions/deactivate
Deactivates an image.
*(Since Image API v2.3)*
By default, this operation is restricted to administrators only.
If you try to download a deactivated image, you will receive a 403 (Forbidden)
response code. Additionally, only administrative users can view image
locations for deactivated images.
The deactivate operation returns an error if the image status is
not ``active`` or ``deactivated``.
Preconditions
- The image must exist.
Normal response codes: 204
Error response codes: 400, 403, 404
Request
-------
.. rest_parameters:: images-parameters.yaml
- image_id: image_id-in-path
Reactivate image
~~~~~~~~~~~~~~~~
.. rest_method:: POST /v2/images/{image_id}/actions/reactivate
Reactivates an image.
*(Since Image API v2.3)*
By default, this operation is restricted to administrators only.
The reactivate operation returns an error if the image status is
not ``active`` or ``deactivated``.
Preconditions
- The image must exist.
Normal response codes: 204
Error response codes: 400, 403, 404
Request
-------
.. rest_parameters:: images-parameters.yaml
- image_id: image_id-in-path

587
api-ref/source/v2/images-parameters.yaml Normal file
View File

@ -0,0 +1,587 @@
# variables in header
Content-Length:
description: |
The length of the body in octets (8-bit bytes)
in: header
required: true
type: string
Content-Md5:
description: |
The MD5 checksum of the body.
in: header
required: true
type: string
Content-Range:
description: |
The content range of image data. For details, see
`Hypertext Transfer Protocol (HTTP/1.1): Range Requests
<http://tools.ietf.org/html/rfc7233>`_.
in: header
required: false
type: string
Content-Type-data:
description: |
The media type descriptor for the request body. Use
``application/octet-stream``
in: header
required: true
type: string
Content-Type-data-response:
description: |
The media type descriptor of the response body, namely
``application/octet-stream``
in: header
required: true
type: string
Content-Type-json:
description: |
The media type descriptor for the request body. Use
``application/json``.
in: header
required: true
type: string
Content-Type-patch:
description: |
The media type descriptor for the request body. Use
``application/openstack-images-v2.1-json-patch``. (You can also use
``application/openstack-images-v2.0-json-patch``, but keep in mind that
it's deprecated.)
in: header
required: true
type: string
Location:
description: |
The URL to access the image file from the
external store.
in: header
required: true
type: string
# variables in path
image_id-in-path:
description: |
The UUID of the image.
in: path
required: true
type: string
member_id-in-path:
description: |
The ID of the image member. An image member is usually the project (also
called the "tenant") with whom the image is shared.
in: path
required: true
type: string
tag-in-path:
description: |
The image tag. A tag is limited to 255 chars in length. You may wish
to use characters that can easily be written in a URL.
in: path
required: true
type: string
# variables in query
created_at-in-query:
description: |
Specify a *comparison filter* based on the date and time when the resource
was created. (See :ref:`Time Comparison Filters <v2-comparison-ops>`).
The date and time stamp format is `ISO 8601
<https://en.wikipedia.org/wiki/ISO_8601>`_:
::
CCYY-MM-DDThh:mm:ss±hh:mm
The ``±hh:mm`` value, if included, is the time zone as an offset
from UTC.
For example, ``2015-08-27T09:49:58-05:00``.
If you omit the time zone, the UTC time zone is assumed.
in: query
required: false
type: string
limit:
description: |
Requests a page size of items. Returns a number of items up to a limit
value. Use the ``limit`` parameter to make an initial limited request and
use the ID of the last-seen item from the response as the ``marker``
parameter value in a subsequent limited request.
in: query
required: false
type: integer
marker:
description: |
The ID of the last-seen item. Use the ``limit`` parameter to make an
initial limited request and use the ID of the last-seen item from the
response as the ``marker`` parameter value in a subsequent limited request.
in: query
required: false
type: string
member_status-in-query:
description: |
Filters the response by a member status. A valid value is ``accepted``,
``pending``, ``rejected``, or ``all``. Default is ``accepted``.
in: query
required: false
type: string
name-in-query:
description: |
Filters the response by a name, as a string. A valid value is the name of
an image.
in: query
required: false
type: string
owner-in-query:
description: |
Filters the response by a project (also called a "tenant") ID. Shows only
images that are shared with you by the specified owner.
in: query
required: false
type: string
size_max:
description: |
Filters the response by a maximum image size, in
bytes.
in: query
required: false
type: string
size_min:
description: |
Filters the response by a minimum image size, in
bytes.
in: query
required: false
type: string
sort:
description: |
Sorts the response by one or more attribute and sort direction
combinations. You can also set multiple sort keys and directions.
Default direction is ``desc``.
Use the comma (``,``) character to separate multiple values. For
example:
.. code-block:: json
GET /v2/images?sort=name:asc,status:desc
in: query
required: false
type: string
sort_dir:
description: |
Sorts the response by a set of one or more sort
direction and attribute (``sort_key``) combinations. A valid value
for the sort direction is ``asc`` (ascending) or ``desc``
(descending). If you omit the sort direction in a set, the default
is ``desc``.
in: query
required: false
type: string
sort_key:
description: |
Sorts the response by an attribute, such as
``name``, ``id``, or ``updated_at``. Default is ``created_at``.
The API uses the natural sorting direction of the ``sort_key``
image attribute.
in: query
required: false
type: string
status-in-query:
description: |
Filters the response by an image status.
in: query
required: false
type: integer
tag-in-query:
description: |
Filters the response by the specified tag value. May be repeated, but keep
in mind that you're making a conjunctive query, so only images containing
*all* the tags specified will appear in the response.
in: query
required: false
type: string
updated_at-in-query:
description: |
Specify a *comparison filter* based on the date and time when the resource
was most recently modified. (See :ref:`Time Comparison Filters
<v2-comparison-ops>`).
The date and time stamp format is `ISO 8601
<https://en.wikipedia.org/wiki/ISO_8601>`_:
::
CCYY-MM-DDThh:mm:ss±hh:mm
The ``±hh:mm`` value, if included, is the time zone as an offset
from UTC.
For example, ``2015-08-27T09:49:58-05:00``.
If you omit the time zone, the UTC time zone is assumed.
in: query
required: false
type: string
visibility-in-query:
description: |
Filters the response by an image visibility value. A valid value is
``public``, ``private``, or ``shared``. (Note that if you filter on
``shared``, the images included in the response will only be those where
your member status is ``accepted`` unless you explicitly include a
``member_status`` filter in the request.) If you omit this parameter, the
response shows ``public``, ``private``, and those ``shared`` images with a
member status of ``accepted``.
in: query
required: false
type: string
# variables in body
checksum:
description: |
Hash that is used over the image data. The Image
service uses this value for verification. The value might be
``null`` (JSON null data type).
in: body
required: true
type: string
container_format:
description: |
Format of the image container. A valid value is one of
``ami``, ``ari``, ``aki``, ``bare``, ``ovf``, ``ova``, or
``docker``. The value might be ``null`` (JSON null data type).
in: body
required: true
type: enum
container_format-in-request:
description: |
Format of the image container. A valid value is one of
``ami``, ``ari``, ``aki``, ``bare``, ``ovf``, ``ova``, or
``docker``.
in: body
required: false
type: enum
created_at:
description: |
The date and time when the resource was created.
The date and time stamp format is `ISO 8601
<https://en.wikipedia.org/wiki/ISO_8601>`_:
::
CCYY-MM-DDThh:mm:ss±hh:mm
For example, ``2015-08-27T09:49:58-05:00``.
The ``±hh:mm`` value, if included, is the time zone as an offset
from UTC.
in: body
required: true
type: string
direct_url:
description: |
The URL to access the image file kept in external store. *It is present
only if the* ``show_image_direct_url`` *option is* ``true`` *in the Image
service's configuration file.* **Because it presents a security risk, this
option is disabled by default.**
in: body
required: false
type: string
disk_format:
description: |
The format of the disk. A valid value is ``ami``, ``ari``, ``aki``,
``vhd``, ``vmdk``, ``raw``, ``qcow2``, ``vdi``, or ``iso``. The value
might be ``null`` (JSON null data type).
in: body
required: true
type: enum
disk_format-in-request:
description: |
The format of the disk. A valid value is ``ami``, ``ari``, ``aki``,
``vhd``, ``vmdk``, ``raw``, ``qcow2``, ``vdi``, or ``iso``.
in: body
required: false
type: enum
file:
description: |
The URL for the virtual machine image file.
in: body
required: true
type: string
first:
description: |
The URI for the first page of response.
in: body
required: true
type: string
id:
description: |
A unique, user-defined image UUID, in the format:
::
nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn
Where **n** is a hexadecimal digit from 0 to f, or F.
For example:
::
b2173dd3-7ad6-4362-baa6-a68bce3565cb
If you omit this value, the API generates a UUID for the image.
in: body
required: true
type: string
id-in-request:
description: |
A unique, user-defined image UUID, in the format:
::
nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn
Where **n** is a hexadecimal digit from 0 to f, or F.
For example:
::
b2173dd3-7ad6-4362-baa6-a68bce3565cb
If you omit this value, the API generates a UUID for the image. If you
specify a value that has already been assigned, the request fails with
a ``409`` response code.
in: body
required: false
type: string
image_id-in-body:
description: |
The UUID of the image.
in: body
required: true
type: string
images:
description: |
A list of *image* objects, as described by the :ref:`Images Schema
<images-schema>`.
in: body
required: true
type: array
locations:
description: |
A list of objects, each of which describes an image location. Each object
contains a ``url`` key, whose value is a URL specifying a location, and a
``metadata`` key, whose value is a dict of key:value pairs containing
information appropriate to the use of whatever external store is indicated
by the URL. *This list appears only if the* ``show_multiple_locations``
*option is set to* ``true`` *in the Image service's configuration file.*
**Because it presents a security risk, this option is disabled by
default.**
in: body
required: false
type: array
member_id:
description: |
The ID of the image member. An image member is usually a project (also
called the "tenant") with whom the image is shared.
in: body
required: true
type: string
member_status:
description: |
The status of this image member. Value is one of ``pending``,
``accepted``, ``rejected``.
in: body
required: true
type: string
members:
description: |
A list of *member* objects, as described by the :ref:`Image Members Schema
<image-members-schema>`. Each *member* object describes a member with whom
this image is being shared.
in: body
required: true
type: array
min_disk:
description: |
Amount of disk space in GB that is required to boot the image.
The value might be ``null`` (JSON null data type).
in: body
required: true
type: integer
min_disk-in-request:
description: |
Amount of disk space in GB that is required to boot the image.
in: body
required: false
type: integer
min_ram:
description: |
Amount of RAM in MB that is required to boot the image.
The value might be ``null`` (JSON null data type).
in: body
required: true
type: integer
min_ram-in-request:
description: |
Amount of RAM in MB that is required to boot the image.
in: body
required: false
type: integer
name:
description: |
The name of the image. Value might be ``null`` (JSON null data type).
in: body
required: true
type: string
name-in-request:
description: |
The name of the image.
in: body
required: false
type: string
next:
description: |
The URI for the next page of response. Will not be present on the last
page of the response.
in: body
required: true
type: string
owner:
description: |
An identifier for the owner of the image, usually the project (also
called the "tenant") ID.
The value might be ``null`` (JSON null data type).
in: body
required: true
type: string
protected:
description: |
A boolean value that must be ``false`` or the image cannot be deleted.
in: body
required: true
type: boolean
protected-in-request:
description: |
Image protection for deletion. Valid value is ``true`` or ``false``.
Default is ``false``.
in: body
required: false
type: boolean
schema-image:
description: |
The URL for the schema describing a virtual machine image.
in: body
required: true
type: string
schema-images:
description: |
The URL for the schema describing a list of images.
in: body
required: true
type: string
schema-member:
description: |
The URL for the schema describing an image member.
in: body
required: true
type: string
schema-members:
description: |
The URL for the schema describing an image member list.
in: body
required: true
type: string
self:
description: |
The URL for the virtual machine image.
in: body
required: true
type: string
size:
description: |
The size of the image data, in bytes. The value
might be ``null`` (JSON null data type).
in: body
required: true
type: integer
status:
description: |
The image status.
in: body
required: true
type: string
tags:
description: |
List of tags for this image, possibly an empty list.
in: body
required: true
type: array
tags-in-request:
description: |
List of tags for this image. Each tag is a string of at most 255 chars.
The maximum number of tags allowed on an image is set by the operator.
in: body
required: false
type: array
updated_at:
description: |
The date and time when the resource was updated.
The date and time stamp format is `ISO 8601
<https://en.wikipedia.org/wiki/ISO_8601>`_:
::
CCYY-MM-DDThh:mm:ss±hh:mm
For example, ``2015-08-27T09:49:58-05:00``.
The ``±hh:mm`` value, if included, is the time zone as an offset
from UTC. In the previous example, the offset value is ``-05:00``.
If the ``updated_at`` date and time stamp is not set, its value is
``null``.
in: body
required: true
type: string
url:
description: |
The URL to access the image file kept in external
store.
in: body
required: true
type: string
value:
description: |
Value of image property used in add or replace
operations expressed in JSON notation. For example, you must
enclose strings in quotation marks, and you do not enclose numeric
values in quotation marks.
in: body
required: true
type: string
virtual_size:
description: |
The virtual size of the image. The value might
be ``null`` (JSON null data type).
in: body
required: true
type: integer
visibility:
description: |
Image visibility, that is, the access permission for the image.
in: body
required: true
type: string
visibility-in-request:
description: |
Visibility for this image. Valid value is ``public`` or ``private``.
At most sites, only an administrator can make an image public.
Default is ``private``.
in: body
required: false
type: string

138
api-ref/source/v2/images-schemas.inc Normal file
View File

@ -0,0 +1,138 @@
.. -*- rst -*-
.. note: You can get a 400 on a GET if you pass a request body
(see router.py)
Image Schemas
*************
Gets a JSON-schema document that represents the various entities talked
about by the Images v2 API.
.. _images-schema:
Show images schema
~~~~~~~~~~~~~~~~~~
.. rest_method:: GET /v2/schemas/images
*(Since Images v2.0)*
Shows a JSON schema document that represents an *images* entity.
An images entity is a container of image entities.
The following schema is solely an example. Consider only the
response to the API call as authoritative.
Normal response codes: 200
Error response codes: 400, 401
Request
-------
This operation has no request parameters and does not accept a request body.
Response Example
----------------
.. literalinclude:: samples/schemas-images-list-response.json
:language: json
.. _image-schema:
Show image schema
~~~~~~~~~~~~~~~~~
.. rest_method:: GET /v2/schemas/image
*(Since Images v2.0)*
Shows a JSON schema document that represents an *image* entity.
The following schema is solely an example. Consider only the
response to the API call as authoritative.
Normal response codes: 200
Error response codes: 400, 401
Request
-------
This operation has no request parameters and does not accept a request body.
Response Example
----------------
.. literalinclude:: samples/schemas-image-show-response.json
:language: json
.. _image-members-schema:
Show image members schema
~~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: GET /v2/schemas/members
*(Since Images v2.1)*
Shows a JSON schema document that represents an *image members* entity.
An image members entity is a container of image member entities.
The following schema is solely an example. Consider only the
response to the API call as authoritative.
Normal response codes: 200
Error response codes: 400, 401
Request
-------
This operation has no request parameters and does not accept a request body.
Response Example
----------------
.. literalinclude:: samples/schemas-image-members-list-response.json
:language: json
.. _image-member-schema:
Show image member schema
~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: GET /v2/schemas/member
*(Since Images v2.1)*
Shows a JSON schema document that represents an *image member* entity.
The following schema is solely an example. Consider only the
response to the API call as authoritative.
Normal response codes: 200
Error response codes: 400, 401
Request
-------
This operation has no request parameters and does not accept a request body.
Response Example
----------------
.. literalinclude:: samples/schemas-image-member-show-response.json
:language: json

360
api-ref/source/v2/images-sharing-v2.inc Normal file
View File

@ -0,0 +1,360 @@
.. -*- rst -*-
Sharing
*******
Images may be shared among projects by creating *members* on the image. The
following calls allow you to create, list, update, and delete image members.
.. note::
An image member is an identifier for a consumer with whom the image is
shared. In most OpenStack clouds, where the value of the ``owner`` property
of an image is a project ID, the appropriate identifier to use for the
``member_id`` is the consumer's project ID (also known as the "tenant ID").
In these clouds, image sharing is project-to-project, and all the individual
users in the consuming project have access to the image.
* Some deployments may choose instead to have the identifier of the user who
created the image as the value of the ``owner`` property. In such clouds,
the appropriate identifier to use for the ``member_id`` is the user ID of
the person with whom you want to share the image. In these clouds, image
sharing is user-to-user.
* Note that you, as an image owner, do not have a choice about what value to
use for the ``member_id``. If, like most OpenStack clouds, your cloud
uses the tenant ID for the image ``owner``, sharing will not work if you
use a user ID as the ``member_id`` of an image (and vice-versa).
* Please consult your cloud's local documentation for details.
When an image is shared, the member is given immediate access to the image.
In order to prevent spamming other users' image lists, a shared image does not
appear in a member's image list until the member "accepts" the image.
Only the image owner may create members. Only an image member may modify his
or her member status.
.. TODO(rosmaita): update the following reference when the "narrative" API
docs have a final resting place
For a conceptual overview of image sharing, including a suggested workflow,
please consult `Image API v2 Sharing`_.
.. _Image API v2 Sharing:
http://specs.openstack.org/openstack/glance-specs/specs/api/v2/sharing-image-api-v2.html
Create image member
~~~~~~~~~~~~~~~~~~~
.. rest_method:: POST /v2/images/{image_id}/members
Adds a tenant ID as an image member.
*(Since Image API v2.1)*
Preconditions
- The image must exist.
- The image cannot be a public image.
- You must be the owner of the image.
Synchronous Postconditions
- With correct permissions, you can see the member status of the
image member as ``pending`` through API calls.
Troubleshooting
- Even if you have correct permissions, if the ``visibility``
attribute is set to ``public``, the request returns the HTTP
``403`` response code. Ensure that you meet the preconditions and
run the request again. If the request fails again, review your
API request.
- If the member is already a member for the image, the service
returns the ``Conflict (409)`` response code. If you meant to
specify a different member, run the request again.
Normal response codes: 200
Error response codes: 400, 401, 403, 404, 409, 413
Request
-------
.. rest_parameters:: images-parameters.yaml
- image_id: image_id-in-path
- member: member_id
Request Example
---------------
.. literalinclude:: samples/image-member-create-request.json
:language: json
Response Parameters
-------------------
.. rest_parameters:: images-parameters.yaml
- created_at: created_at
- image_id: image_id-in-body
- member_id: member_id
- schema: schema-member
- status: member_status
- updated_at: updated_at
Response Example
----------------
.. literalinclude:: samples/image-member-create-response.json
:language: json
Show image member details
~~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: GET /v2/images/{image_id}/members/{member_id}
Shows image member details.
*(Since Image API v2.1)*
Response body is a single image member entity.
Preconditions
- The image must exist.
- You must be the owner or the member of the image who's referenced in the
call.
Normal response codes: 200
Error response codes: 400, 401, 404
Request
-------
.. rest_parameters:: images-parameters.yaml
- image_id: image_id-in-path
- member_id: member_id-in-path
Response Parameters
-------------------
.. rest_parameters:: images-parameters.yaml
- created_at: created_at
- image_id: image_id-in-body
- member_id: member_id
- schema: schema-member
- status: member_status
- updated_at: updated_at
Response Example
----------------
.. literalinclude:: samples/image-member-details-response.json
:language: json
List image members
~~~~~~~~~~~~~~~~~~
.. rest_method:: GET /v2/images/{image_id}/members
Lists the tenants that share this image.
*(Since Image API v2.1)*
If the image owner makes this call, the complete member list is
returned.
If a user who is an image member makes this call, the member list
contains only information for that user.
If a user who is not an image member makes this call, the call
returns the HTTP ``404`` response code.
Preconditions
- The image must exist.
- You must be the owner or a member of the image.
Normal response codes: 200
Error response codes: 400, 401, 404
Request
-------
.. rest_parameters:: images-parameters.yaml
- image_id: image_id-in-path
Response Parameters
-------------------
.. rest_parameters:: images-parameters.yaml
- members: members
- schema: schema-members
Response Example
----------------
.. literalinclude:: samples/image-members-list-response.json
:language: json
Update image member
~~~~~~~~~~~~~~~~~~~
.. rest_method:: PUT /v2/images/{image_id}/members/{member_id}
Sets the status for an image member.
*(Since Image API v2.1)*
This call allows an image member to change his or her *member status*.
When an image is shared with you, you have immediate access to the image. What
updating your member status on the image does for you is that it affects
whether the image will appear in your image list response.
- When an image is shared with you, your member_status is ``pending``. You
won't see the image unless you go looking for it, either by making a show
image detail request using the image's ID, or by making an image list call
specifically looking for a shared image in member status ``pending``. This
way, other users cannot "spam" your image list with images you may not want
to see.
- If you want to see a particular shared image in your image list, then you
must use this call to change your member status on the image to ``accepted``.
- The image owner can see what your member status is on an image, but the owner
*cannot* change the status. Only you (or an administrator) can do that.
- There are three member status values: ``pending``, ``accepted``, and
``rejected``. The ``pending`` and ``rejected`` statuses are functionally
identical. The difference is that ``pending`` indicates to the owner that
you haven't updated the image, so perhaps you aren't aware that it's been
shared with you. The ``rejected`` status indicates that you are aware that
the image exists and you specifically decided that you don't want to see it
in your image list response.
For a more detailed discussion of image sharing, please consult `Image API v2
Sharing`_.
Preconditions
- The image must exist.
- You must be the member of the image referenced in the call.
Synchronous Postconditions
- If you update the member status to ``accepted`` and have the
correct permissions, you see the image in list images responses.
- With correct permissions, you can make API calls to see the
updated member status of the image.
Normal response codes: 200
Error response codes: 400, 401, 404, 403
Request
-------
.. rest_parameters:: images-parameters.yaml
- image_id: image_id-in-path
- member_id: member_id-in-path
- status: member_status
Request Example
---------------
.. literalinclude:: samples/image-member-update-request.json
:language: json
Response Parameters
-------------------
.. rest_parameters:: images-parameters.yaml
- created_at: created_at
- image_id: image_id-in-body
- member_id: member_id
- schema: schema-member
- status: member_status
- updated_at: updated_at
Response Example
----------------
.. literalinclude:: samples/image-member-update-response.json
:language: json
Delete image member
~~~~~~~~~~~~~~~~~~~
.. rest_method:: DELETE /v2/images/{image_id}/members/{member_id}
Deletes a tenant ID from the member list of an image.
*(Since Image API v2.1)*
Preconditions
- The image must exist.
- You must be the owner of the image.
Synchronous Postconditions
- The API removes the member from the image members.
Troubleshooting
- Even if you have correct permissions, if you are not the owner of
the image or you specify an incorrect image ID or member ID, the
call returns the HTTP ``403`` or ``404`` response code. Ensure
that you meet the preconditions and run the request again. If the
request fails again, review your API request URI.
Normal response codes: 204
Error response codes: 400, 401, 403, 404
Request
-------
.. rest_parameters:: images-parameters.yaml
- image_id: image_id-in-path
- member_id: member_id-in-path

52
api-ref/source/v2/images-tags.inc Normal file
View File

@ -0,0 +1,52 @@
.. -*- rst -*-
Image tags
**********
Adds and deletes image tags.
Image tags may also be modfied by the :ref:`v2-image-update` call.
Add image tag
~~~~~~~~~~~~~
.. rest_method:: PUT /v2/images/{image_id}/tags/{tag}
Adds a tag to an image.
*(Since Image API v2.0)*
Normal response codes: 204
Error response codes: 400, 401, 403, 404, 413
Request
-------
.. rest_parameters:: images-parameters.yaml
- image_id: image_id-in-path
- tag: tag-in-path
Delete image tag
~~~~~~~~~~~~~~~~
.. rest_method:: DELETE /v2/images/{image_id}/tags/{tag}
Deletes a tag from an image.
*(Since Image API v2.0)*
Normal response codes: 204
Error response codes: 400, 401, 403, 404
Request
-------
.. rest_parameters:: images-parameters.yaml
- image_id: image_id-in-path
- tag: tag-in-path

5
api-ref/source/v2/index.rst
View File

@ -22,5 +22,10 @@ Image Service API v2 (CURRENT)
.. rest_expand_all::
.. include:: images-images-v2.inc
.. include:: images-sharing-v2.inc
.. include:: images-tags.inc
.. include:: images-schemas.inc
.. include:: images-data.inc
.. include:: tasks.inc
.. include:: tasks-schemas.inc

6
api-ref/source/v2/samples/image-create-request.json Normal file
View File

@ -0,0 +1,6 @@
{
"container_format": "bare",
"disk_format": "raw",
"name": "Ubuntu",
"id": "b2173dd3-7ad6-4362-baa6-a68bce3565cb"
}

22
api-ref/source/v2/samples/image-create-response.json Normal file
View File

@ -0,0 +1,22 @@
{
"status": "queued",
"name": "Ubuntu",
"tags": [],
"container_format": "bare",
"created_at": "2015-11-29T22:21:42Z",
"size": null,
"disk_format": "raw",
"updated_at": "2015-11-29T22:21:42Z",
"visibility": "private",
"locations": [],
"self": "/v2/images/b2173dd3-7ad6-4362-baa6-a68bce3565cb",
"min_disk": 0,
"protected": false,
"id": "b2173dd3-7ad6-4362-baa6-a68bce3565cb",
"file": "/v2/images/b2173dd3-7ad6-4362-baa6-a68bce3565cb/file",
"checksum": null,
"owner": "bab7d5c60cd041a0a36f7c4b6e1dd978",
"virtual_size": null,
"min_ram": 0,
"schema": "/v2/schemas/image"
}

21
api-ref/source/v2/samples/image-details-deactivate-response.json Normal file
View File

@ -0,0 +1,21 @@
{
"status": "deactivated",
"name": "cirros-0.3.2-x86_64-disk",
"tags": [],
"container_format": "bare",
"created_at": "2014-05-05T17:15:10Z",
"disk_format": "qcow2",
"updated_at": "2014-05-05T17:15:11Z",
"visibility": "public",
"self": "/v2/images/1bea47ed-f6a9-463b-b423-14b9cca9ad27",
"min_disk": 0,
"protected": false,
"id": "1bea47ed-f6a9-463b-b423-14b9cca9ad27",
"file": "/v2/images/1bea47ed-f6a9-463b-b423-14b9cca9ad27/file",
"checksum": "64d7c1cd2b6f60c92c14662941cb7913",
"owner": "5ef70662f8b34079a6eddb8da9d75fe8",
"size": 13167616,
"min_ram": 0,
"schema": "/v2/schemas/image",
"virtual_size": null
}

3
api-ref/source/v2/samples/image-member-create-request.json Normal file
View File

@ -0,0 +1,3 @@
{
"member": "8989447062e04a818baf9e073fd04fa7"
}

8
api-ref/source/v2/samples/image-member-create-response.json Normal file
View File

@ -0,0 +1,8 @@
{
"created_at": "2013-09-20T19:22:19Z",
"image_id": "a96be11e-8536-4910-92cb-de50aa19dfe6",
"member_id": "8989447062e04a818baf9e073fd04fa7",
"schema": "/v2/schemas/member",
"status": "pending",
"updated_at": "2013-09-20T19:25:31Z"
}

8
api-ref/source/v2/samples/image-member-details-response.json Normal file
View File

@ -0,0 +1,8 @@
{
"status": "pending",
"created_at": "2013-11-26T07:21:21Z",
"updated_at": "2013-11-26T07:21:21Z",
"image_id": "0ae74cc5-5147-4239-9ce2-b0c580f7067e",
"member_id": "8989447062e04a818baf9e073fd04fa7",
"schema": "/v2/schemas/member"
}

3
api-ref/source/v2/samples/image-member-update-request.json Normal file
View File

@ -0,0 +1,3 @@
{
"status": "accepted"
}

8
api-ref/source/v2/samples/image-member-update-response.json Normal file
View File

@ -0,0 +1,8 @@
{
"created_at": "2013-09-20T19:22:19Z",
"image_id": "a96be11e-8536-4910-92cb-de50aa19dfe6",
"member_id": "8989447062e04a818baf9e073fd04fa7",
"schema": "/v2/schemas/member",
"status": "accepted",
"updated_at": "2013-09-20T20:15:31Z"
}

21
api-ref/source/v2/samples/image-members-list-response.json Normal file
View File

@ -0,0 +1,21 @@
{
"members": [
{
"created_at": "2013-10-07T17:58:03Z",
"image_id": "dbc999e3-c52f-4200-bedd-3b18fe7f87fe",
"member_id": "123456789",
"schema": "/v2/schemas/member",
"status": "pending",
"updated_at": "2013-10-07T17:58:03Z"
},
{
"created_at": "2013-10-07T17:58:55Z",
"image_id": "dbc999e3-c52f-4200-bedd-3b18fe7f87fe",
"member_id": "987654321",
"schema": "/v2/schemas/member",
"status": "accepted",
"updated_at": "2013-10-08T12:08:55Z"
}
],
"schema": "/v2/schemas/members"
}

21
api-ref/source/v2/samples/image-show-response.json Normal file
View File

@ -0,0 +1,21 @@
{
"status": "active",
"name": "cirros-0.3.2-x86_64-disk",
"tags": [],
"container_format": "bare",
"created_at": "2014-05-05T17:15:10Z",
"disk_format": "qcow2",
"updated_at": "2014-05-05T17:15:11Z",
"visibility": "public",
"self": "/v2/images/1bea47ed-f6a9-463b-b423-14b9cca9ad27",
"min_disk": 0,
"protected": false,
"id": "1bea47ed-f6a9-463b-b423-14b9cca9ad27",
"file": "/v2/images/1bea47ed-f6a9-463b-b423-14b9cca9ad27/file",
"checksum": "64d7c1cd2b6f60c92c14662941cb7913",
"owner": "5ef70662f8b34079a6eddb8da9d75fe8",
"size": 13167616,
"min_ram": 0,
"schema": "/v2/schemas/image",
"virtual_size": null
}

15
api-ref/source/v2/samples/image-update-request.json Normal file
View File

@ -0,0 +1,15 @@
[
{
"op": "replace",
"path": "/name",
"value": "Fedora 17"
},
{
"op": "replace",
"path": "/tags",
"value": [
"fedora",
"beefy"
]
}
]

23
api-ref/source/v2/samples/image-update-response.json Normal file
View File

@ -0,0 +1,23 @@
{
"id": "da3b75d9-3f4a-40e7-8a2c-bfab23927dea",
"name": "Fedora 17",
"status": "active",
"visibility": "public",
"size": 2254249,
"checksum": "2cec138d7dae2aa59038ef8c9aec2390",
"tags": [
"fedora",
"beefy"
],
"created_at": "2012-08-10T19:23:50Z",
"updated_at": "2012-08-12T11:11:33Z",
"self": "/v2/images/da3b75d9-3f4a-40e7-8a2c-bfab23927dea",
"file": "/v2/images/da3b75d9-3f4a-40e7-8a2c-bfab23927dea/file",
"schema": "/v2/schemas/image",
"owner": null,
"min_ram": null,
"min_disk": null,
"disk_format": null,
"virtual_size": null,
"container_format": null
}

48
api-ref/source/v2/samples/images-list-response.json Normal file
View File

@ -0,0 +1,48 @@
{
"images": [
{
"status": "active",
"name": "cirros-0.3.2-x86_64-disk",
"tags": [],
"container_format": "bare",
"created_at": "2014-11-07T17:07:06Z",
"disk_format": "qcow2",
"updated_at": "2014-11-07T17:19:09Z",
"visibility": "public",
"self": "/v2/images/1bea47ed-f6a9-463b-b423-14b9cca9ad27",
"min_disk": 0,
"protected": false,
"id": "1bea47ed-f6a9-463b-b423-14b9cca9ad27",
"file": "/v2/images/1bea47ed-f6a9-463b-b423-14b9cca9ad27/file",
"checksum": "64d7c1cd2b6f60c92c14662941cb7913",
"owner": "5ef70662f8b34079a6eddb8da9d75fe8",
"size": 13167616,
"min_ram": 0,
"schema": "/v2/schemas/image",
"virtual_size": null
},
{
"status": "active",
"name": "F17-x86_64-cfntools",
"tags": [],
"container_format": "bare",
"created_at": "2014-10-30T08:23:39Z",
"disk_format": "qcow2",
"updated_at": "2014-11-03T16:40:10Z",
"visibility": "public",
"self": "/v2/images/781b3762-9469-4cec-b58d-3349e5de4e9c",
"min_disk": 0,
"protected": false,
"id": "781b3762-9469-4cec-b58d-3349e5de4e9c",
"file": "/v2/images/781b3762-9469-4cec-b58d-3349e5de4e9c/file",
"checksum": "afab0f79bac770d61d24b4d0560b5f70",
"owner": "5ef70662f8b34079a6eddb8da9d75fe8",
"size": 476704768,
"min_ram": 0,
"schema": "/v2/schemas/image",
"virtual_size": null
}
],
"schema": "/v2/schemas/images",
"first": "/v2/images"
}

34
api-ref/source/v2/samples/schemas-image-member-show-response.json Normal file
View File

@ -0,0 +1,34 @@
{
"name": "member",
"properties": {
"created_at": {
"description": "Date and time of image member creation",
"type": "string"
},
"image_id": {
"description": "An identifier for the image",
"pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$",
"type": "string"
},
"member_id": {
"description": "An identifier for the image member (tenantId)",
"type": "string"
},
"schema": {
"type": "string"
},
"status": {
"description": "The status of this image member",
"enum": [
"pending",
"accepted",
"rejected"
],
"type": "string"
},
"updated_at": {
"description": "Date and time of last modification of image member",
"type": "string"
}
}
}

51
api-ref/source/v2/samples/schemas-image-members-list-response.json Normal file
View File

@ -0,0 +1,51 @@
{
"links": [
{
"href": "{schema}",
"rel": "describedby"
}
],
"name": "members",
"properties": {
"members": {
"items": {
"name": "member",
"properties": {
"created_at": {
"description": "Date and time of image member creation",
"type": "string"
},
"image_id": {
"description": "An identifier for the image",
"pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$",
"type": "string"
},
"member_id": {
"description": "An identifier for the image member (tenantId)",
"type": "string"
},
"schema": {
"type": "string"
},
"status": {
"description": "The status of this image member",
"enum": [
"pending",
"accepted",
"rejected"
],
"type": "string"
},
"updated_at": {
"description": "Date and time of last modification of image member",
"type": "string"
}
}
},
"type": "array"
},
"schema": {
"type": "string"
}
}
}

216
api-ref/source/v2/samples/schemas-image-show-response.json Normal file
View File

@ -0,0 +1,216 @@
{
"additionalProperties": {
"type": "string"
},
"links": [
{
"href": "{self}",
"rel": "self"
},
{
"href": "{file}",
"rel": "enclosure"
},
{
"href": "{schema}",
"rel": "describedby"
}
],
"name": "image",
"properties": {
"architecture": {
"description": "Operating system architecture as specified in http://docs.openstack.org/trunk/openstack-compute/admin/content/adding-images.html",
"is_base": false,
"type": "string"
},
"checksum": {
"description": "md5 hash of image contents. (READ-ONLY)",
"maxLength": 32,
"type": [
"null",
"string"
]
},
"container_format": {
"description": "Format of the container",
"enum": [
null,
"ami",
"ari",
"aki",
"bare",
"ovf",
"ova"
],
"type": [
"null",
"string"
]
},
"created_at": {
"description": "Date and time of image registration (READ-ONLY)",
"type": "string"
},
"direct_url": {
"description": "URL to access the image file kept in external store (READ-ONLY)",
"type": "string"
},
"disk_format": {
"description": "Format of the disk",
"enum": [
null,
"ami",
"ari",
"aki",
"vhd",
"vmdk",
"raw",
"qcow2",
"vdi",
"iso"
],
"type": [
"null",
"string"
]
},
"file": {
"description": "(READ-ONLY)",
"type": "string"
},
"id": {
"description": "An identifier for the image",
"pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$",
"type": "string"
},
"instance_uuid": {
"description": "ID of instance used to create this image.",
"is_base": false,
"type": "string"
},
"kernel_id": {
"description": "ID of image stored in Glance that should be used as the kernel when booting an AMI-style image.",
"is_base": false,
"pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$",
"type": "string"
},
"locations": {
"description": "A set of URLs to access the image file kept in external store",
"items": {
"properties": {
"metadata": {
"type": "object"
},
"url": {
"maxLength": 255,
"type": "string"
}
},
"required": [
"url",
"metadata"
],
"type": "object"
},
"type": "array"
},
"min_disk": {
"description": "Amount of disk space (in GB) required to boot image.",
"type": "integer"
},
"min_ram": {
"description": "Amount of ram (in MB) required to boot image.",
"type": "integer"
},
"name": {
"description": "Descriptive name for the image",
"maxLength": 255,
"type": [
"null",
"string"
]
},
"os_distro": {
"description": "Common name of operating system distribution as specified in http://docs.openstack.org/trunk/openstack-compute/admin/content/adding-images.html",
"is_base": false,
"type": "string"
},
"os_version": {
"description": "Operating system version as specified by the distributor",
"is_base": false,
"type": "string"
},
"owner": {
"description": "Owner of the image",
"maxLength": 255,
"type": [
"null",
"string"
]
},
"protected": {
"description": "If true, image will not be deletable.",
"type": "boolean"
},
"ramdisk_id": {
"description": "ID of image stored in Glance that should be used as the ramdisk when booting an AMI-style image.",
"is_base": false,
"pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$",
"type": "string"
},
"schema": {
"description": "(READ-ONLY)",
"type": "string"
},
"self": {
"description": "(READ-ONLY)",
"type": "string"
},
"size": {
"description": "Size of image file in bytes (READ-ONLY)",
"type": [
"null",
"integer"
]
},
"status": {
"description": "Status of the image (READ-ONLY)",
"enum": [
"queued",
"saving",
"active",
"killed",
"deleted",
"pending_delete"
],
"type": "string"
},
"tags": {
"description": "List of strings related to the image",
"items": {
"maxLength": 255,
"type": "string"
},
"type": "array"
},
"updated_at": {
"description": "Date and time of the last image modification (READ-ONLY)",
"type": "string"
},
"virtual_size": {
"description": "Virtual size of image in bytes (READ-ONLY)",
"type": [
"null",
"integer"
]
},
"visibility": {
"description": "Scope of image accessibility",
"enum": [
"public",
"private"
],
"type": "string"
}
}
}

247
api-ref/source/v2/samples/schemas-images-list-response.json Normal file
View File

@ -0,0 +1,247 @@
{
"links": [
{
"href": "{first}",
"rel": "first"
},
{
"href": "{next}",
"rel": "next"
},
{
"href": "{schema}",
"rel": "describedby"
}
],
"name": "images",
"properties": {
"first": {
"type": "string"
},
"images": {
"items": {
"additionalProperties": {
"type": "string"
},
"links": [
{
"href": "{self}",
"rel": "self"
},
{
"href": "{file}",
"rel": "enclosure"
},
{
"href": "{schema}",
"rel": "describedby"
}
],
"name": "image",
"properties": {
"architecture": {
"description": "Operating system architecture as specified in http://docs.openstack.org/trunk/openstack-compute/admin/content/adding-images.html",
"is_base": false,
"type": "string"
},
"checksum": {
"description": "md5 hash of image contents. (READ-ONLY)",
"maxLength": 32,
"type": [
"null",
"string"
]
},
"container_format": {
"description": "Format of the container",
"enum": [
null,
"ami",
"ari",
"aki",
"bare",
"ovf",
"ova"
],
"type": [
"null",
"string"
]
},
"created_at": {
"description": "Date and time of image registration (READ-ONLY)",
"type": "string"
},
"direct_url": {
"description": "URL to access the image file kept in external store (READ-ONLY)",
"type": "string"
},
"disk_format": {
"description": "Format of the disk",
"enum": [
null,
"ami",
"ari",
"aki",
"vhd",
"vmdk",
"raw",
"qcow2",
"vdi",
"iso"
],
"type": [
"null",
"string"
]
},
"file": {
"description": "(READ-ONLY)",
"type": "string"
},
"id": {
"description": "An identifier for the image",
"pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$",
"type": "string"
},
"instance_uuid": {
"description": "ID of instance used to create this image.",
"is_base": false,
"type": "string"
},
"kernel_id": {
"description": "ID of image stored in Glance that should be used as the kernel when booting an AMI-style image.",
"is_base": false,
"pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$",
"type": "string"
},
"locations": {
"description": "A set of URLs to access the image file kept in external store",
"items": {
"properties": {
"metadata": {
"type": "object"
},
"url": {
"maxLength": 255,
"type": "string"
}
},
"required": [
"url",
"metadata"
],
"type": "object"
},
"type": "array"
},
"min_disk": {
"description": "Amount of disk space (in GB) required to boot image.",
"type": "integer"
},
"min_ram": {
"description": "Amount of ram (in MB) required to boot image.",
"type": "integer"
},
"name": {
"description": "Descriptive name for the image",
"maxLength": 255,
"type": [
"null",
"string"
]
},
"os_distro": {
"description": "Common name of operating system distribution as specified in http://docs.openstack.org/trunk/openstack-compute/admin/content/adding-images.html",
"is_base": false,
"type": "string"
},
"os_version": {
"description": "Operating system version as specified by the distributor",
"is_base": false,
"type": "string"
},
"owner": {
"description": "Owner of the image",
"maxLength": 255,
"type": [
"null",
"string"
]
},
"protected": {
"description": "If true, image will not be deletable.",
"type": "boolean"
},
"ramdisk_id": {
"description": "ID of image stored in Glance that should be used as the ramdisk when booting an AMI-style image.",
"is_base": false,
"pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$",
"type": "string"
},
"schema": {
"description": "(READ-ONLY)",
"type": "string"
},
"self": {
"description": "(READ-ONLY)",
"type": "string"
},
"size": {
"description": "Size of image file in bytes (READ-ONLY)",
"type": [
"null",
"integer"
]
},
"status": {
"description": "Status of the image (READ-ONLY)",
"enum": [
"queued",
"saving",
"active",
"killed",
"deleted",
"pending_delete"
],
"type": "string"
},
"tags": {
"description": "List of strings related to the image",
"items": {
"maxLength": 255,
"type": "string"
},
"type": "array"
},
"updated_at": {
"description": "Date and time of the last image modification (READ-ONLY)",
"type": "string"
},
"virtual_size": {
"description": "Virtual size of image in bytes (READ-ONLY)",
"type": [
"null",
"integer"
]
},
"visibility": {
"description": "Scope of image accessibility",
"enum": [
"public",
"private"
],
"type": "string"
}
}
},
"type": "array"
},
"next": {
"type": "string"
},
"schema": {
"type": "string"
}
}
}