openstack
/
deb-glance
Code Issues Proposed changes

dev-docs: mark v1 as deprecated 

This patch consists of changes to the Glance developer docs to
indicate that the Images API v1 has been deprecated in Newton.

Change-Id: Idf62cf86cd402b2f39a7233f7159ba81dad02bb9
Partial-bug: #1618495
This commit is contained in:
Brian Rosmaita 2016-09-30 07:21:40 -04:00
parent 98147bc270
commit 0a9bbd33c0
3 changed files with 35 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
doc/source/deprecation-note.inc Normal file
View File

@ -0,0 +1,6 @@
.. note:: The Images API v1 has been DEPRECATED in the Newton release. The
migration path is to use the `Images API v2
<http://developer.openstack.org/api-ref/image/v2/>`_ instead of version 1
of the API. The Images API v1 will ultimately be removed, following the
`OpenStack standard deprecation policy
<https://governance.openstack.org/reference/tags/assert_follows-standard-deprecation.html>`_.

51
doc/source/glanceapi.rst
View File

@ -20,6 +20,8 @@ Using Glance's Image Public APIs
Glance is the reference implementation of the OpenStack Images API. As such, Glance is the reference implementation of the OpenStack Images API. As such,
Glance fully implements versions 1 and 2 of the Images API. Glance fully implements versions 1 and 2 of the Images API.
.. include:: deprecation-note.inc
There used to be a sentence here saying, "The Images API specification is There used to be a sentence here saying, "The Images API specification is
developed alongside Glance, but is not considered part of the Glance project." developed alongside Glance, but is not considered part of the Glance project."
That's only partially true (or completely false, depending upon how strict you That's only partially true (or completely false, depending upon how strict you
@ -56,22 +58,23 @@ Images v1 API
The v1 API was originally designed as a service API for use by Nova and other The v1 API was originally designed as a service API for use by Nova and other
OpenStack services. In the Kilo release, the v1.1 API was downgraded from OpenStack services. In the Kilo release, the v1.1 API was downgraded from
CURRENT to SUPPORTED. The Images v1 API is closed to further development, and CURRENT to SUPPORTED. In the Newton release, the version 1 API is officially
the Glance code implementing the v1 API accepts only serious bugfixes. declared DEPRECATED.
It's possible to deploy OpenStack without exposing the Images v1 API to end During the deprecation period, the Images v1 API is closed to further
users. The Compute v2 API contains image-related API calls allowing users to development. The Glance code implementing the v1 API accepts only serious
list images, list images details, show image details for a specific image, bugfixes.
delete images, and manipulate image metadata. Nova acts as a proxy to Glance
for these image-related calls. It's important to note that the image-related
calls in the Compute v2 API are a proper subset of the calls available in the
Images APIs.
Currently Nova uses the Images v1 API, but work is in progress to convert Nova Since Folsom, it has been possible to deploy OpenStack without exposing the
(and other OpenStack services that consume images) to using the Images v2 API. Images v1 API to end users. The Compute v2 API contains image-related API
Once that occurs, it will be possible to deploy OpenStack without deploying the calls allowing users to list images, list images details, show image details
Images v1 API. At that point, the Images v1 API will be deprecated, following for a specific image, delete images, and manipulate image metadata. Nova acts
the standard OpenStack deprecation policy. as a proxy to Glance for these image-related calls. It's important to note
that the image-related calls in the Compute v2 API are a proper subset of the
calls available in the Images APIs.
In the Newton release, Nova (and other OpenStack services that consume images)
have been modified to use the Images v2 API by default.
**Reference** **Reference**
@ -86,10 +89,8 @@ expose images-related functionality as a public-facing endpoint. It's the
version that's currently open to development. version that's currently open to development.
A common strategy is to deploy multiple Glance nodes: internal-facing nodes A common strategy is to deploy multiple Glance nodes: internal-facing nodes
providing both Images v1 and v2 APIs for internal consumers like Nova, and providing the Images APIs for internal consumers like Nova, and external-facing
external-facing nodes providing only the Images v2 API for public use. Thus, nodes providing the Images v2 API for public use.
there is no reason to rely solely on Nova's image-related calls in the Compute
API if one does not want to expose the Images v1 API to public endpoints.
The Future The Future
********** **********
@ -103,12 +104,12 @@ Images. Conceptually, a virtual machine image could be an Artifact, and the
Glare code has been designed to be compatible with the Images v2 API. But at Glare code has been designed to be compatible with the Images v2 API. But at
this time, there are no plans to implement an Images v3 API. this time, there are no plans to implement an Images v3 API.
As far as the Glance/Glare relationship goes, it's too early to say what the During the Newton development cycle, Glare became an independent OpenStack
future holds. While it's evident that there's a need for an Artifact project. While it's evident that there's a need for an Artifact Repository in
Repository in OpenStack, whether it will be as ubiquitous as the need for an OpenStack, whether it will be as ubiquitous as the need for an Images
Images Repository isn't clear. On the other hand, industry trends could go in Repository isn't clear. On the other hand, industry trends could go in the
the opposite direction where everyone needs Artifacts and deployers view images opposite direction where everyone needs Artifacts and deployers view images as
as simply another type of digital artifact. As Yogi Berra, an experienced simply another type of digital artifact. As Yogi Berra, an experienced
manager, once said, "It's tough to make predictions, especially about the manager, once said, "It's tough to make predictions, especially about the
future." future."
@ -126,6 +127,8 @@ See :doc:`authentication` for more information on integrating with Keystone.
Using v1.X Using v1.X
---------- ----------
.. include:: deprecation-note.inc
For the purpose of examples, assume there is a Glance API server running For the purpose of examples, assume there is a Glance API server running
at the URL ``http://glance.openstack.example.org`` on the default port 80. at the URL ``http://glance.openstack.example.org`` on the default port 80.

2
doc/source/index.rst
View File

@ -25,6 +25,8 @@ Glance image services include discovering, registering, and
retrieving virtual machine images. Glance has a RESTful API that allows retrieving virtual machine images. Glance has a RESTful API that allows
querying of VM image metadata as well as retrieval of the actual image. querying of VM image metadata as well as retrieval of the actual image.
.. include:: deprecation-note.inc
VM images made available through Glance can be stored in a variety of VM images made available through Glance can be stored in a variety of
locations from simple filesystems to object-storage systems like the locations from simple filesystems to object-storage systems like the
OpenStack Swift project. OpenStack Swift project.