openstack/glance
Code Issues Proposed changes

dev-docs: mark v1 as deprecated

Browse Source 
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 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
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
@ -56,22 +58,23 @@ Images v1 API
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
CURRENT to SUPPORTED. The Images v1 API is closed to further development, and
the Glance code implementing the v1 API accepts only serious bugfixes.
CURRENT to SUPPORTED. In the Newton release, the version 1 API is officially
declared DEPRECATED.
It's possible to deploy OpenStack without exposing the Images v1 API to end
users. The Compute v2 API contains image-related API calls allowing users to
list images, list images details, show image details for a specific image,
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.
During the deprecation period, the Images v1 API is closed to further
development. The Glance code implementing the v1 API accepts only serious
bugfixes.
Currently Nova uses the Images v1 API, but work is in progress to convert Nova
(and other OpenStack services that consume images) to using the Images v2 API.
Once that occurs, it will be possible to deploy OpenStack without deploying the
Images v1 API. At that point, the Images v1 API will be deprecated, following
the standard OpenStack deprecation policy.
Since Folsom, it has been possible to deploy OpenStack without exposing the
Images v1 API to end users. The Compute v2 API contains image-related API
calls allowing users to list images, list images details, show image details
for a specific image, 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.
In the Newton release, Nova (and other OpenStack services that consume images)
have been modified to use the Images v2 API by default.
**Reference**
@ -86,10 +89,8 @@ expose images-related functionality as a public-facing endpoint. It's the
version that's currently open to development.
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
external-facing nodes providing only the Images v2 API for public use. Thus,
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.
providing the Images APIs for internal consumers like Nova, and external-facing
nodes providing the Images v2 API for public use.
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
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
future holds. While it's evident that there's a need for an Artifact
Repository in OpenStack, whether it will be as ubiquitous as the need for an
Images Repository isn't clear. On the other hand, industry trends could go in
the opposite direction where everyone needs Artifacts and deployers view images
as simply another type of digital artifact. As Yogi Berra, an experienced
During the Newton development cycle, Glare became an independent OpenStack
project. While it's evident that there's a need for an Artifact Repository in
OpenStack, whether it will be as ubiquitous as the need for an Images
Repository isn't clear. On the other hand, industry trends could go in the
opposite direction where everyone needs Artifacts and deployers view images as
simply another type of digital artifact. As Yogi Berra, an experienced
manager, once said, "It's tough to make predictions, especially about the
future."
@ -126,6 +127,8 @@ See :doc:`authentication` for more information on integrating with Keystone.
Using v1.X
----------
.. include:: deprecation-note.inc
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.

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
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
locations from simple filesystems to object-storage systems like the
OpenStack Swift project.