ee1b6dce3c
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 introduces (a) the tox environment to generate the api-ref, and (b) the content of the Images v1 API reference converted to RST. The content has been corrected where I noticed divergences with reality. Note to reviewers: The conversion project is ongoing, that is, the doc team is continuing to develop tools (for example, to display the response codes in a table) and converging on a style for these docs. So this isn't a final product, there will be more patches later. While this patch is not perfect, it is pareto-optimal with respect to content (it's at least as good as the current guide, and better in at least one place). Thus my advice, should you choose to take it, is that we should merge this patch to get these docs in-tree, and make improvements as additional patches that can focus on particular API calls rather than try to get everything perfect on this patch. Change-Id: I51dfaf1832108466f115ab183838c5f28e138312
250 lines
7.6 KiB
YAML
250 lines
7.6 KiB
YAML
# variables in header
|
|
location:
|
|
description: |
|
|
A URI location for the image record.
|
|
format: uri
|
|
in: header
|
|
required: true
|
|
type: string
|
|
x-image-meta-container_format:
|
|
description: |
|
|
The image ``container_format`` property. (Optional when only reserving
|
|
an image.)
|
|
|
|
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.
|
|
in: header
|
|
required: true
|
|
type: enum
|
|
x-image-meta-disk_format:
|
|
description: |
|
|
The image ``disk_format`` property. (Optional when only reserving
|
|
an image.)
|
|
|
|
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 hypervisors
|
|
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 hypervisors.
|
|
in: header
|
|
required: true
|
|
type: enum
|
|
x-image-meta-name:
|
|
description: |
|
|
The image ``name`` property. (Optional when only reserving
|
|
an image.)
|
|
|
|
An image name is not required to be unique, though of course it will be
|
|
easier to tell your images apart if you give them distinct descriptive
|
|
names. Names are limited to 255 chars.
|
|
in: header
|
|
required: true
|
|
type: string
|
|
x-openstack-request-id:
|
|
description: |
|
|
Request identifier passed through by the various OpenStack services.
|
|
in: header
|
|
required: false
|
|
type: string
|
|
|
|
# variables in path
|
|
image_id-in-path:
|
|
description: |
|
|
Image ID stored through the image API. Typically a UUID.
|
|
in: path
|
|
required: true
|
|
type: string
|
|
member_id-in-path:
|
|
description: |
|
|
The tenant ID of the tenant with whom an image is shared, that is, the
|
|
tenant ID of the image member.
|
|
in: path
|
|
required: true
|
|
type: string
|
|
owner_id-in-path:
|
|
description: |
|
|
Owner ID, which is the tenant ID.
|
|
in: path
|
|
required: true
|
|
type: string
|
|
|
|
# variables in query
|
|
changes-since:
|
|
description: |
|
|
Filters the image list to those images that have changed since a time
|
|
stamp value.
|
|
in: query
|
|
required: false
|
|
type: string
|
|
container_format-in-query:
|
|
description: |
|
|
Filters the image list by a container format. A
|
|
valid value is ``aki``, ``ami``, ``ari``, ``bare``, ``docker``,
|
|
``ova``, or ``ovf``.
|
|
in: query
|
|
required: false
|
|
type: string
|
|
disk_format-in-query:
|
|
description: |
|
|
Filters the image list by a disk format. A valid
|
|
value is ``aki``, ``ami``, ``ari``, ``iso``, ``qcow2``, ``raw``,
|
|
``vhd``, ``vdi``, or ``vmdk``.
|
|
in: query
|
|
required: false
|
|
type: string
|
|
name-in-query:
|
|
description: |
|
|
Filters the image list by an image name, in string format.
|
|
in: query
|
|
required: false
|
|
type: string
|
|
size_max:
|
|
description: |
|
|
Filters the image list by a maximum image size, in bytes.
|
|
in: query
|
|
required: false
|
|
type: int
|
|
size_min:
|
|
description: |
|
|
Filters the image list by a minimum image size, in bytes.
|
|
in: query
|
|
required: false
|
|
type: int
|
|
status-in-query:
|
|
description: |
|
|
Filters the image list by a status. A valid value is ``queued``,
|
|
``saving``, ``active``, ``killed``, ``deleted``, or ``pending_delete``.
|
|
in: query
|
|
required: false
|
|
type: string
|
|
|
|
# variables in body
|
|
can_share:
|
|
description: |
|
|
Indicates whether the image member whose tenant ID is ``member_id``
|
|
is authorized to share the image. If the member can share the image,
|
|
this value is ``true``. Otherwise, this value is ``false``.
|
|
in: body
|
|
required: false
|
|
type: boolean
|
|
createImage:
|
|
description: |
|
|
The virtual machine image data. Do not include this if you are only
|
|
reserving an image.
|
|
in: body
|
|
required: true
|
|
type: binary
|
|
image-object:
|
|
description: |
|
|
A JSON representation of the image. Includes all metadata fields.
|
|
in: body
|
|
required: true
|
|
type: object
|
|
images-detail-list:
|
|
description: |
|
|
A list of image objects.
|
|
|
|
Each object contains the following fields:
|
|
|
|
- ``checksum`` - The MD5 checksum of the image data.
|
|
- ``container_format`` - The container format.
|
|
- ``created_at`` - Timestamp of image record creation.
|
|
- ``deleted`` - ``true`` if the image is deleted, ``false``
|
|
otherwise.
|
|
- ``deleted_at`` - Timestamp when the image went to ``deleted``
|
|
status.
|
|
- ``disk_format`` - The disk format.
|
|
- ``id`` - The image ID, typically a UUID.
|
|
- ``is_public`` - This is ``true`` if the image is public,
|
|
``false`` otherwise.
|
|
- ``name`` - The name of the image.
|
|
- ``owner`` - The image owner, usually the tenant_id.
|
|
- ``properties`` - A dict of user-specified key:value pairs (that
|
|
is, custom image metadata).
|
|
- ``protected`` - A boolean value that must be ``false`` or the
|
|
image cannot be deleted. Default value is ``false``.
|
|
- ``size`` - The size of the stored image data in bytes.
|
|
- ``status`` - The image status.
|
|
- ``updated_at`` - Timestamp of when the image record was most
|
|
recently modified.
|
|
- ``virtual_size`` - The size of the virtual machine image (the
|
|
virtual disk itself, not the containing package, if any) in bytes.
|
|
in: body
|
|
required: true
|
|
type: array
|
|
images-list:
|
|
description: |
|
|
A list of image objects in a sparse representation.
|
|
|
|
Each object contains the following fields:
|
|
|
|
- ``checksum`` - The MD5 checksum of the image data.
|
|
- ``container_format`` - The container format.
|
|
- ``disk_format`` - The disk format.
|
|
- ``id`` - The image ID, typically a UUID.
|
|
- ``name`` - The name of the image.
|
|
- ``size`` - The size of the image in bytes.
|
|
in: body
|
|
required: true
|
|
type: array
|
|
member_id:
|
|
description: |
|
|
The tenant ID of the tenant with whom an image is shared, that is, the
|
|
tenant ID of the image member.
|
|
in: body
|
|
required: true
|
|
type: string
|
|
memberships:
|
|
description: |
|
|
List of image member objects.
|
|
in: body
|
|
required: true
|
|
type: array
|
|
next:
|
|
description: |
|
|
Show the next item in the list.
|
|
format: uri
|
|
in: body
|
|
required: false
|
|
type: string
|
|
previous:
|
|
description: |
|
|
Show the previous item in the list.
|
|
format: uri
|
|
in: body
|
|
required: false
|
|
type: string
|
|
shared_images:
|
|
description: |
|
|
A list of objects, each of which contains an ``image_id`` and a
|
|
``can_share`` field. If all the members of the image are such that
|
|
``can_share`` is ``true`` for each member, then the ``can_share``
|
|
value in this object will be ``true``, otherwise it will be ``false``.
|
|
in: body
|
|
required: true
|
|
type: array
|