diff --git a/doc/source/index.rst b/doc/source/index.rst index ada78256..77f06898 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -106,28 +106,6 @@ Image Service API v2 specs/api/v2/sharing-image-api-v2.rst specs/api/v2/http-patch-image-api-v2.rst -Image Service API v1 --------------------- - -.. include:: specs/api/v1/deprecation-note.inc - -.. toctree:: - :maxdepth: 1 - - specs/api/v1/image_service_v1_api - specs/api/v1/authentication - specs/api/v1/adding_a_new_virtual_machine_image - specs/api/v1/retrieving_a_virtual_machine_image - specs/api/v1/requesting_detailed_metadata_on_a_specific_image - specs/api/v1/requesting_detailed_metadata_on_public_vm_images - specs/api/v1/requesting_shared_images - specs/api/v1/requesting_image_memberships - specs/api/v1/adding_a_member_to_an_image - specs/api/v1/removing_a_member_from_an_image - specs/api/v1/replacing_a_membership_list_for_an_image - specs/api/v1/filtering_images_returned_via_get__images_and_get__images_detail - - ================== Indices and tables ================== diff --git a/specs/api/v1/adding_a_member_to_an_image.rst b/specs/api/v1/adding_a_member_to_an_image.rst deleted file mode 100644 index 3a8872bf..00000000 --- a/specs/api/v1/adding_a_member_to_an_image.rst +++ /dev/null @@ -1,23 +0,0 @@ -=========================== -Adding a Member to an Image -=========================== - -.. include:: deprecation-note.inc - -We want to authorize a tenant to access a private image. We issue a -``PUT`` request to -``http://glance.openstack.example.org/images/1/members/tenant1``. With no body, -this will add the membership to the image, leaving existing memberships -unmodified and defaulting new memberships to have \`can\_share\` set to -\`false\`. We may also optionally attach a body of the following form: - -.. code:: - - {'member': - {'can_share': true} - } - -If such a body is provided, both existing and new memberships will have -\`can\_share\` set to the provided value (either \`true\` or \`false\`). -This query will return a 204 ("No Content") status code. - diff --git a/specs/api/v1/adding_a_new_virtual_machine_image.rst b/specs/api/v1/adding_a_new_virtual_machine_image.rst deleted file mode 100644 index 59b950ff..00000000 --- a/specs/api/v1/adding_a_new_virtual_machine_image.rst +++ /dev/null @@ -1,175 +0,0 @@ -================================== -Adding a New Virtual Machine Image -================================== - -.. include:: deprecation-note.inc - -We have created a new virtual machine image in some way (created a -"golden image" or snapshotted/backed up an existing image) and we wish -to do two things: - -- Store the disk image data in Glance - -- Store metadata about this image in Glance - -We can do the above two activities in a single call to the Glance API. -Assuming, like in the examples above, that a Glance API server is -running at ``glance.openstack.example.org``, we issue a ``POST`` request to -add an image to Glance: - -.. code:: - - POST http://glance.openstack.example.org/images/ - -The metadata about the image is sent to Glance in HTTP headers. The body -of the HTTP request to the Glance API will be the MIME-encoded disk -image data. - -Adding Image Metadata in HTTP Headers -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Glance will view as image metadata any HTTP header that it receives in a - -.. code:: - - ``POST`` request where the header key is prefixed with the strings - ``x-image-meta-`` and ``x-image-meta-property-``. - -The list of metadata headers that Glance accepts are listed below. - -- ``x-image-meta-name`` - - This header is optional . Its value should be the name of the image. - - Note that the name of an image *is not unique to a Glance node*. It - would be an unrealistic expectation of users to know all the unique - names of all other user's images. - -- ``x-image-meta-id`` - - This header is optional. - - When present, Glance will use the supplied identifier for the image. - If the identifier already exists in that Glance node, then a **409 - Conflict** will be returned by Glance. - - When this header is *not* present, Glance will generate an identifier - for the image and return this identifier in the response (see below) - -- ``x-image-meta-store`` - - This header is optional. Valid values are one of ``file``, ``s3``, or - ``swift`` - - When present, Glance will attempt to store the disk image data in the - backing store indicated by the value of the header. If the Glance - node does not support the backing store, Glance will return a **400 - Bad Request**. - - When not present, Glance will store the disk image data in the - backing store that is marked default. See the configuration option - ``default_store`` for more information. - -- ``x-image-meta-disk-format`` - - This header is optional. Valid values are one of ``aki``, ``ari``, - ``ami``, ``raw``, ``iso``, ``vhd``, ``vdi``, ``qcow2``, or ``vmdk``. - - For more information, see :doc:\`About Disk and Container Formats - \` - -- ``x-image-meta-container-format`` - - This header is optional. Valid values are one of ``aki``, ``ari``, - ``ami``, ``bare``, or ``ovf``. - - For more information, see :doc:\`About Disk and Container Formats - \` - -- ``x-image-meta-size`` - - This header is optional. - - When present, Glance assumes that the expected size of the request - body will be the value of this header. If the length in bytes of the - request body *does not match* the value of this header, Glance will - return a **400 Bad Request**. - - When not present, Glance will calculate the image's size based on the - size of the request body. - -- ``x-image-meta-checksum`` - - This header is optional. When present it shall be the expected - **MD5** checksum of the image file data. - - When present, Glance will verify the checksum generated from the - backend store when storing your image against this value and return a - **400 Bad Request** if the values do not match. - -- ``x-image-meta-is-public`` - - This header is optional. - - When Glance finds the string "true" (case-insensitive), the image is - marked as a public image, meaning that any user may view its metadata - and may read the disk image from Glance. - - When not present, the image is assumed to be *not public* and - specific to a user. - -- ``x-image-meta-owner`` - - This header is optional and only meaningful for admins. - - Glance normally sets the owner of an image to be the tenant or user - (depending on the "owner\_is\_tenant" configuration option) of the - authenticated user issuing the request. However, if the authenticated - user has the Admin role, this default may be overridden by setting - this header to null or to a string identifying the owner of the - image. - -- ``x-image-meta-property-*`` - - When Glance receives any HTTP header whose key begins with the string - prefix ``x-image-meta-property-``, Glance adds the key and value to a - set of custom, free-form image properties stored with the image. The - key is the lower-cased string following the prefix - ``x-image-meta-property-`` with dashes and punctuation replaced with - underscores. - - For example, if the following HTTP header were sent: - - .. code:: - - x-image-meta-property-distro Ubuntu 10.10 - - Then a key/value pair of "distro"/"Ubuntu 10.10" will be stored with - the image in Glance. - - There is no limit on the number of free-form key/value attributes - that can be attached to the image. However, keep in mind that the 8K - limit on the size of all HTTP headers sent in a request will - effectively limit the number of image properties. - -Updating an Image -~~~~~~~~~~~~~~~~~ - -Glance will view as image metadata any HTTP header that it receives in a - -.. code:: - - ``PUT`` request where the header key is prefixed with the strings - ``x-image-meta-`` and ``x-image-meta-property-``. - -If an image was previously reserved, and thus is in the ``queued`` -state, then image data can be added by including it as the request body. -If the image already as data associated with it (e.g. not in the -``queued`` state), then including a request body will result in a **409 -Conflict** exception. - -On success, the ``PUT`` request will return the image metadata encoded -as HTTP headers. - -See more about image statuses here: :doc:\`Image Statuses \` - diff --git a/specs/api/v1/authentication.rst b/specs/api/v1/authentication.rst deleted file mode 100644 index de9ffd4c..00000000 --- a/specs/api/v1/authentication.rst +++ /dev/null @@ -1,32 +0,0 @@ -Authentication --------------- - -.. include:: deprecation-note.inc - -You can optionally integrate Glance with the OpenStack Identity Service -project. Setting this up is relatively straightforward: the Identity -Service distribution at http://github.com/openstack/keystone includes -the requisite middleware and examples of appropriately modified -glance-api.conf and glance-registry.conf configuration files in the -examples/paste directory. Once you have installed Keystone and edited -your configuration files, newly created images will have their owner -attribute set to the tenant of the authenticated users, and the -is\_public attribute will cause access to those images for which it is -false to be restricted to only the owner. - -The exception is those images for which owner is set to null, which may -only be done by those users having the Admin role. These images may -still be accessed by the public, but will not appear in the list of -public images. This allows the Glance Registry owner to publish images -for beta testing without allowing those images to show up in lists, -potentially confusing users. - -It is possible to allow a private image to be shared with one or more -alternate tenants. This is done through image memberships, which are -available via the members resource of images. (For more details, see the -next chapter.) Essentially, a membership is an association between an -image and a tenant which has permission to access that image. These -membership associations may also have a can\_share attribute, which, if -set to true, delegates the authority to share an image to the named -tenant. - diff --git a/specs/api/v1/deprecation-note.inc b/specs/api/v1/deprecation-note.inc deleted file mode 100644 index c3fe751a..00000000 --- a/specs/api/v1/deprecation-note.inc +++ /dev/null @@ -1,6 +0,0 @@ -.. note:: The Images API v1 has been DEPRECATED in the Newton release. The - migration path is to use the `Images API v2 - `_ instead of version 1 - of the API. The Images API v1 will ultimately be removed, following the - `OpenStack standard deprecation policy - `_. diff --git a/specs/api/v1/filtering_images_returned_via_get__images_and_get__images_detail.rst b/specs/api/v1/filtering_images_returned_via_get__images_and_get__images_detail.rst deleted file mode 100644 index 57e90054..00000000 --- a/specs/api/v1/filtering_images_returned_via_get__images_and_get__images_detail.rst +++ /dev/null @@ -1,59 +0,0 @@ -================================================================ -Filtering Images Returned via GET /images and GET /images/detail -================================================================ - -.. include:: deprecation-note.inc - -Both the ``GET /images`` and ``GET /images/detail`` requests -take query parameters that serve to filter the returned list of images. -The following list details these query parameters. - -- ``name=NAME`` - - Filters images having a ``name`` attribute matching ``NAME``. - -- ``container_format=FORMAT`` - - Filters images having a ``container_format`` attribute matching - ``FORMAT`` - - For more information, see :doc:\`About Disk and Container Formats - \` - -- ``disk_format=FORMAT`` - - Filters images having a ``disk_format`` attribute matching ``FORMAT`` - - For more information, see :doc:\`About Disk and Container Formats - \` - -- ``status=STATUS`` - - Filters images having a ``status`` attribute matching ``STATUS`` - - For more information, see :doc:\`About Image Statuses \` - -- ``size_min=BYTES`` - - Filters images having a ``size`` attribute greater than or equal to - ``BYTES`` - -- ``size_max=BYTES`` - - Filters images having a ``size`` attribute less than or equal to - ``BYTES`` - -These two resources also accept sort parameters: - -- ``sort_key=KEY`` - - Results will be ordered by the specified image attribute ``KEY``. - Accepted values include ``id``, ``name``, ``status``, - ``disk_format``, ``container_format``, ``size``, ``created_at`` - (default) and ``updated_at``. - -- ``sort_dir=DIR`` - - Results will be sorted in the direction ``DIR``. Accepted values are - ``asc`` for ascending or ``desc`` (default) for descending. - diff --git a/specs/api/v1/image_service_v1_api.rst b/specs/api/v1/image_service_v1_api.rst deleted file mode 100644 index 88bd9956..00000000 --- a/specs/api/v1/image_service_v1_api.rst +++ /dev/null @@ -1,69 +0,0 @@ -========================= -Image service v1 REST API -========================= - -.. include:: deprecation-note.inc - -The OpenStack Image service offers retrieval, storage, and metadata -assignment for your images that you want to run in your OpenStack cloud. -The project is code-named Glance. - -OpenStack Image service enables users to store and retrieve images -through a simple Web Service (ReST: Representational State Transfer) -interface. - -For more details on the OpenStack Image service, please refer to -`docs.openstack.org/developer/glance/ `__ - -We welcome feedback, comments, and bug reports at -`bugs.launchpad.net/glance `__. - -Intended Audience ------------------ - -This guide is intended to assist software developers who want to develop -applications using the OpenStack Image Service API. It fully documents -the ReST application programming interface (API) that allows developers -to interact with the storage components of the OpenStack Image system. -To use the information provided here, you should first have a general -understanding of the OpenStack Image Service and have access to an -installation of OpenStack Image Service. You should also be familiar -with: - -- ReSTful web services - -- HTTP/1.1 - -Glance has a RESTful API that exposes both metadata about registered -virtual machine images and the image data itself. - -A host that runs the ``bin/glance-api`` service is said to be a *Glance -API Server*. - -Assume there is a Glance API server running at the URL -``http://glance.openstack.example.org``. - -Let's walk through how a user might request information from this -server. - -Requesting a List of Public VM Images -------------------------------------- - -We want to see a list of available virtual machine images that the -Glance server knows about. - -We issue a ``GET`` request to ``http://glance.openstack.example.org/images/`` -to retrieve this list of available *public* images. The data is returned as -a JSON-encoded mapping in the following format: - -.. code:: - - {'images': [ - {'status: 'active', - 'name': 'Ubuntu 10.04 Plain', - 'disk_format': 'vhd', - 'container_format': 'ovf', - 'size': '5368709120'} - ...]} - -All images returned from the above `GET` request are public images diff --git a/specs/api/v1/removing_a_member_from_an_image.rst b/specs/api/v1/removing_a_member_from_an_image.rst deleted file mode 100644 index 203c8e84..00000000 --- a/specs/api/v1/removing_a_member_from_an_image.rst +++ /dev/null @@ -1,11 +0,0 @@ -=============================== -Removing a Member from an Image -=============================== - -.. include:: deprecation-note.inc - -We want to revoke a tenant's right to access a private image. We issue a -``DELETE`` request to -``http://glance.openstack.example.org/images/1/members/tenant1``. This query -will return a 204 ("No Content") status code. - diff --git a/specs/api/v1/replacing_a_membership_list_for_an_image.rst b/specs/api/v1/replacing_a_membership_list_for_an_image.rst deleted file mode 100644 index 145de7bc..00000000 --- a/specs/api/v1/replacing_a_membership_list_for_an_image.rst +++ /dev/null @@ -1,24 +0,0 @@ -======================================== -Replacing a Membership List for an Image -======================================== - -.. include:: deprecation-note.inc - -The full membership list for a given image may be replaced. We issue a -``PUT`` request to ``http://glance.openstack.example.org/images/1/members`` -with a body of the following form: - -.. code:: - - {'memberships': [ - {'member_id': 'tenant1', - 'can_share': false} - ...]} - -All existing memberships which are not named in the replacement body are -removed, and those which are named have their \`can\_share\` settings -changed as specified. (The \`can\_share\` setting may be omitted, which -will cause that setting to remain unchanged in the existing -memberships.) All new memberships will be created, with \`can\_share\` -defaulting to \`false\` if it is not specified. - diff --git a/specs/api/v1/requesting_detailed_metadata_on_a_specific_image.rst b/specs/api/v1/requesting_detailed_metadata_on_a_specific_image.rst deleted file mode 100644 index 5e28bd06..00000000 --- a/specs/api/v1/requesting_detailed_metadata_on_a_specific_image.rst +++ /dev/null @@ -1,54 +0,0 @@ -================================================ -Requesting Detailed Metadata on a Specific Image -================================================ - -.. include:: deprecation-note.inc - -We want to see detailed information for a specific virtual machine image -that the Glance server knows about. - -We have queried the Glance server for a list of public images and the -data returned includes the \`uri\` field for each available image. This -\`uri\` field value contains the exact location needed to get the -metadata for a specific image. - -Continuing the example from above, in order to get metadata about the -first public image returned, we can issue a ``HEAD`` request to the -Glance server for the image's URI. - -We issue a ``HEAD`` request to ``http://glance.openstack.example.org/images/1`` -to retrieve complete metadata for that image. The metadata is returned as a -set of HTTP headers that begin with the prefix ``x-image-meta-``. The -following shows an example of the HTTP headers returned from the above -``HEAD`` request: - -.. code:: - - x-image-meta-name Ubuntu 10.04 Plain 5GB - x-image-meta-disk-format vhd - x-image-meta-container-format ovf - x-image-meta-size 5368709120 - x-image-meta-checksum c2e5db72bd7fd153f53ede5da5a06de3 - x-image-meta-location swift://account:key/container/image.tar.gz.0 - x-image-meta-created_at 2010-02-03 09:34:01 - x-image-meta-updated_at 2010-02-03 09:34:01 - x-image-meta-deleted_at - x-image-meta-status available - x-image-meta-is-public true - x-image-meta-owner null - x-image-meta-property-distro Ubuntu 10.04 LTS - -All timestamps returned are in UTC The \`x-image-meta-updated\_at\` -timestamp is the timestamp when an image's metadata was last updated, -not its image data, as all image data is immutable once stored in Glance -There may be multiple headers that begin with the prefix -\`x-image-meta-property-\`. These headers are free-form key/value pairs -that have been saved with the image metadata. The key is the string -after \`x-image-meta-property-\` and the value is the value of the -header The response's \`ETag\` header will always be equal to the -\`x-image-meta-checksum\` value The response's -\`x-image-meta-is-public\` value is a boolean indicating whether the -image is publicly available The response's \`x-image-meta-owner\` value -is a string which may either be null or which will indicate the owner of -the image. - diff --git a/specs/api/v1/requesting_detailed_metadata_on_public_vm_images.rst b/specs/api/v1/requesting_detailed_metadata_on_public_vm_images.rst deleted file mode 100644 index 942f7bfa..00000000 --- a/specs/api/v1/requesting_detailed_metadata_on_public_vm_images.rst +++ /dev/null @@ -1,53 +0,0 @@ -================================================ -Requesting Detailed Metadata on Public VM Images -================================================ - -.. include:: deprecation-note.inc - -We want to see more detailed information on available virtual machine -images that the Glance server knows about. - -We issue a ``GET`` request to -``http://glance.openstack.example.org/images/detail`` to retrieve this list of -available *public* images. The data is returned as a JSON-encoded -mapping in the following format: - -.. code:: - - {'images': [ - {'name': 'Ubuntu 10.04 Plain 5GB', - 'disk_format': 'vhd', - 'container_format': 'ovf', - 'size': '5368709120', - 'checksum': 'c2e5db72bd7fd153f53ede5da5a06de3', - 'location': 'swift://account:key/container/image.tar.gz.0', - 'created_at': '2010-02-03 09:34:01', - 'updated_at': '2010-02-03 09:34:01', - 'deleted_at': '', - 'status': 'active', - 'is_public': true, - 'owner': null, - 'properties': {'distro': 'Ubuntu 10.04 LTS'}}, - ...]} - -.. code:: - - All images returned from the above `GET` request are public images - - All timestamps returned are in UTC - - The `updated_at` timestamp is the timestamp when an image's metadata - was last updated, not its image data, as all image data is immutable - once stored in Glance - - The `properties` field is a mapping of free-form key/value pairs that - have been saved with the image metadata - - The `checksum` field is an MD5 checksum of the image file data - - The `is_public` field is a boolean indicating whether the image is - publicly available - - The `owner` field is a string which may either be null or which will - indicate the owner of the image - diff --git a/specs/api/v1/requesting_image_memberships.rst b/specs/api/v1/requesting_image_memberships.rst deleted file mode 100644 index 6092e16a..00000000 --- a/specs/api/v1/requesting_image_memberships.rst +++ /dev/null @@ -1,28 +0,0 @@ -============================ -Requesting Image Memberships -============================ - -.. include:: deprecation-note.inc - -We want to see a list of the other system tenants (or users, if -"owner\_is\_tenant" is False) that may access a given virtual machine -image that the Glance server knows about. We take the \`uri\` field of -the image data, append ``/members`` to it, and issue a ``GET`` request -on the resulting URL. - -Continuing from the example above, in order to get the memberships for -the first public image returned, we can issue a ``GET`` request to the -Glance server for ``http://glance.openstack.example.org/images/1/members``. -What we will get back is JSON data such as the following: - -.. code:: - - {'members': [ - {'member_id': 'tenant1', - 'can_share': false} - ...]} - -The \`member\_id\` field identifies a tenant with which the image is -shared. If that tenant is authorized to further share the image, the -\`can\_share\` field is \`true\`. - diff --git a/specs/api/v1/requesting_shared_images.rst b/specs/api/v1/requesting_shared_images.rst deleted file mode 100644 index 7bb6fa18..00000000 --- a/specs/api/v1/requesting_shared_images.rst +++ /dev/null @@ -1,22 +0,0 @@ -======================== -Requesting Shared Images -======================== - -.. include:: deprecation-note.inc - -We want to see a list of images which are shared with a given tenant. We -issue a ``GET`` request to -``http://glance.openstack.example.org/shared-images/tenant1``. We will get back -JSON data such as the following: - -.. code:: - - {'shared_images': [ - {'image_id': 1, - 'can_share': false} - ...]} - -The \`image\_id\` field identifies an image shared with the tenant named -by *member\_id*. If the tenant is authorized to further share the image, -the \`can\_share\` field is \`true\`. - diff --git a/specs/api/v1/retrieving_a_virtual_machine_image.rst b/specs/api/v1/retrieving_a_virtual_machine_image.rst deleted file mode 100644 index 9088b1a8..00000000 --- a/specs/api/v1/retrieving_a_virtual_machine_image.rst +++ /dev/null @@ -1,71 +0,0 @@ -================================== -Retrieving a Virtual Machine Image -================================== - -.. include:: deprecation-note.inc - -We want to retrieve that actual raw data for a specific virtual machine -image that the Glance server knows about. - -We have queried the Glance server for a list of public images and the -data returned includes the \`uri\` field for each available image. This -\`uri\` field value contains the exact location needed to get the -metadata for a specific image. - -Continuing the example from above, in order to get metadata about the -first public image returned, we can issue a ``HEAD`` request to the -Glance server for the image's URI. - -We issue a ``GET`` request to ``http://glance.openstack.example.org/images/1`` -to retrieve metadata for that image as well as the image itself encoded -into the response body. - -The metadata is returned as a set of HTTP headers that begin with the -prefix ``x-image-meta-``. The following shows an example of the HTTP -headers returned from the above ``GET`` request: - -.. code:: - - x-image-meta-name Ubuntu 10.04 Plain 5GB - x-image-meta-disk-format vhd - x-image-meta-container-format ovf - x-image-meta-size 5368709120 - x-image-meta-checksum c2e5db72bd7fd153f53ede5da5a06de3 - x-image-meta-location swift://account:key/container/image.tar.gz.0 - x-image-meta-created_at 2010-02-03 09:34:01 - x-image-meta-updated_at 2010-02-03 09:34:01 - x-image-meta-deleted_at - x-image-meta-status available - x-image-meta-is-public true - x-image-meta-owner null - x-image-meta-property-distro Ubuntu 10.04 LTS - -.. code:: - - All timestamps returned are in UTC - - The `x-image-meta-updated_at` timestamp is the timestamp when an - image's metadata was last updated, not its image data, as all - image data is immutable once stored in Glance - - There may be multiple headers that begin with the prefix - `x-image-meta-property-`. These headers are free-form key/value pairs - that have been saved with the image metadata. The key is the string - after `x-image-meta-property-` and the value is the value of the header - - The response's `Content-Length` header shall be equal to the value of - the `x-image-meta-size` header - - The response's `ETag` header will always be equal to the - `x-image-meta-checksum` value - - The response's `x-image-meta-is-public` value is a boolean indicating - whether the image is publicly available - - The response's `x-image-meta-owner` value is a string which may either - be null or which will indicate the owner of the image - - The image data itself will be the body of the HTTP response returned - from the request, which will have content-type of - `application/octet-stream`. -