Deprecate API Proxies
This describes how we should deprecate API proxies to make them less used in the wild. APIImpact Change-Id: Icca01fc8b2f24340a53feaf212a022e89096319a
This commit is contained in:
Sean Dague
304
specs/newton/approved/deprecate-api-proxies.rst
Normal file
304
specs/newton/approved/deprecate-api-proxies.rst
Normal file
@@ -0,0 +1,304 @@
|
||||
..
|
||||
This work is licensed under a Creative Commons Attribution 3.0 Unported
|
||||
License.
|
||||
|
||||
http://creativecommons.org/licenses/by/3.0/legalcode
|
||||
|
||||
=====================
|
||||
Deprecate API Proxies
|
||||
=====================
|
||||
|
||||
https://blueprints.launchpad.net/nova/+spec/deprecate-api-proxies
|
||||
|
||||
Deprecate the API Proxies that exist in Nova for services that are no
|
||||
longer a part of Nova. Also Deprecate Nova Network API so that all
|
||||
Network APIs are deprecated at the same time regardless of network
|
||||
backend.
|
||||
|
||||
Problem description
|
||||
===================
|
||||
|
||||
Many services originally existed in Nova (images, volumes, baremetal,
|
||||
networking) and were later spun out. At the time the ramifications for
|
||||
the Nova API remaining stable through this process weren't really
|
||||
considered.
|
||||
|
||||
Over time all of these services have evolved, and in many cases the
|
||||
API that is current in these services doesn't match the semantics of
|
||||
the original Nova API. Maintaining a proxy layer for these services
|
||||
gets increasingly difficult over time, and the validity of the data
|
||||
returned becomes more suspect.
|
||||
|
||||
As the Nova team we'd like to point API consumers to the native API
|
||||
whenever possible, and get out of the habit of being a pure proxy for
|
||||
other REST APIs.
|
||||
|
||||
Use Cases
|
||||
---------
|
||||
|
||||
End users should hit the native API for images, volumes, baremetal,
|
||||
and networking (when using Nova Network).
|
||||
|
||||
Proposed change
|
||||
===============
|
||||
|
||||
The API Ref site will be updated to state that all the following
|
||||
resources are deprecated:
|
||||
|
||||
* /images
|
||||
* /os-baremetal-nodes
|
||||
* /os-volumes
|
||||
* /os-snapshots
|
||||
* /os-fixed-ips
|
||||
* /os-floating-ips
|
||||
* /os-floating-ip-dns
|
||||
* /os-floating-ip-pools
|
||||
* /os-floating-ips-bulk
|
||||
* /os-fping - (this only really works with nova-net)
|
||||
* /os-networks
|
||||
* /os-security-group-default-rules
|
||||
* /os-security-group-rules
|
||||
* /os-security-groups
|
||||
* /os-tenant-networks
|
||||
|
||||
The documentation for all of these will be moved to the end of the API
|
||||
Ref site, and it will be visually clear this is part of the deprecated
|
||||
portion of the API.
|
||||
|
||||
There will also be links to the correct corresponding parts of the
|
||||
documentation for the relevant APIs.
|
||||
|
||||
Image Links
|
||||
-----------
|
||||
|
||||
The /images resource included HATEOS links for images, which has had
|
||||
an ``alternate`` field that points back to the glance server directly.
|
||||
|
||||
.. code::
|
||||
|
||||
"images": [
|
||||
{
|
||||
"id": "70a599e0-31e7-49b7-b260-868f441e862b",
|
||||
"links": [
|
||||
{
|
||||
"href": "http://openstack.example.com/v2/6f70656e737461636b20342065766572/images/70a599e0-31e7-49b7-b260-868f441e862b",
|
||||
"rel": "self"
|
||||
},
|
||||
{
|
||||
"href": "http://openstack.example.com/6f70656e737461636b20342065766572/images/70a599e0-31e7-49b7-b260-868f441e862b",
|
||||
"rel": "bookmark"
|
||||
},
|
||||
{
|
||||
"href": "http://glance.openstack.example.com/images/70a599e0-31e7-49b7-b260-868f441e862b",
|
||||
"rel": "alternate",
|
||||
"type": "application/vnd.openstack.image"
|
||||
}
|
||||
],
|
||||
"name": "fakeimage7"
|
||||
},
|
||||
|
||||
After we drop /images there will be no need for images references. The
|
||||
``imageRef`` field in ``servers`` is a UUID, which is valid against
|
||||
glance directly.
|
||||
|
||||
At the same time we will enforce that all our handling of ``imageRef``
|
||||
is a UUID. Today it accept a vast range of values and does some really
|
||||
`sloppy heuristics
|
||||
<https://github.com/openstack/nova/blob/cdfbb9a668fdcf289ffdfa5252d102e9d3e2ec35/nova/image/glance.py#L669-L671>`_
|
||||
to hope it is a valid image ref.
|
||||
|
||||
Networking API
|
||||
--------------
|
||||
|
||||
Nova Network is deprecated, as such the APIs around that networking
|
||||
will also be marked as deprecated, as is their use in talking to the
|
||||
proxy. A preamble will be written for this section to clarify the
|
||||
deprecation of the network API as well as the the proxy to Neutron
|
||||
functionality.
|
||||
|
||||
Users who wish to continue to use the Network API in Nova must just
|
||||
freeze their code to work at microversions before this change.
|
||||
|
||||
Limits and Quotas
|
||||
-----------------
|
||||
|
||||
Some of the limits and quotas presented to the user are for network
|
||||
resources. These never worked correctly when using Neutron.
|
||||
|
||||
The keys related to network resources (security groups, fixed ips,
|
||||
floating ips) will also be removed from limits in this microversion.
|
||||
|
||||
Maintenance Status
|
||||
------------------
|
||||
|
||||
The following rules will exist for all of these APIs.
|
||||
|
||||
* No new features will be added to them
|
||||
* The code behind these APIs will be in soft freeze, bug fixing kept
|
||||
to a minimum.
|
||||
* Bugs that do not cause a 500 error are likely to be unfixed.
|
||||
|
||||
Internal Representations Remain
|
||||
-------------------------------
|
||||
|
||||
The Nova server includes items such as:
|
||||
|
||||
.. code:: javascript
|
||||
|
||||
"accessIPv4": "1.2.3.4",
|
||||
"accessIPv6": "80fe::",
|
||||
"addresses": {
|
||||
"private": [
|
||||
{
|
||||
"addr": "192.168.0.3",
|
||||
"OS-EXT-IPS-MAC:mac_addr": "aa:bb:cc:dd:ee:ff",
|
||||
"OS-EXT-IPS:type": "fixed",
|
||||
"version": 4
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
This is network information, however it's really a part of our server
|
||||
model. In these cases we will continue to keep this representation in
|
||||
our server object, even though it comes from another service.
|
||||
|
||||
This can best be thought of as full paths in the REST API are being
|
||||
deprecated, resource definitions aren't changing (with the possible
|
||||
exception of link content changing).
|
||||
|
||||
Alternatives
|
||||
------------
|
||||
|
||||
Keep these proxies forever. This will increase the cost of the
|
||||
maintenance of Nova and slow down our ability to adapt to new features
|
||||
and requirements.
|
||||
|
||||
Data model impact
|
||||
-----------------
|
||||
|
||||
No immediate data model changes, however once the above APIs are
|
||||
actually removed from tree there is database cleanup that can be done.
|
||||
|
||||
REST API impact
|
||||
---------------
|
||||
|
||||
This change will be done in concert with an API microversion, after
|
||||
which all the following resources will return a ``404``.
|
||||
|
||||
This is a ``404`` because we are removing the whole resource in all of
|
||||
these cases. Other suggestions of ``400`` are not appropriate, because
|
||||
that's almost never appropriate for GET (because how did you malform
|
||||
that request), and ``405`` is not appropriate because the resource
|
||||
doesn't exist at all (``405`` is for a /resource that some verbs work
|
||||
on, but others do not).
|
||||
|
||||
* /images
|
||||
* /os-baremetal-nodes
|
||||
* /os-volumes
|
||||
* /os-snapshots
|
||||
* /os-fixed-ips
|
||||
* /os-floating-ips
|
||||
* /os-floating-ip-dns
|
||||
* /os-floating-ip-pools
|
||||
* /os-floating-ips-bulk
|
||||
* /os-fping - (this only really works with nova-net)
|
||||
* /os-networks
|
||||
* /os-security-group-default-rules
|
||||
* /os-security-group-rules
|
||||
* /os-security-groups
|
||||
* /os-tenant-networks
|
||||
|
||||
To users of ``nova-net`` based clouds, we'll recommend just using a
|
||||
max microversion of N-1 (where N is the change this lands in). This
|
||||
effectively means that nova-net users and clouds don't get new API
|
||||
features, which is appropriate for clouds using a deprecated backend.
|
||||
|
||||
Security impact
|
||||
---------------
|
||||
|
||||
None
|
||||
|
||||
Notifications impact
|
||||
--------------------
|
||||
|
||||
None
|
||||
|
||||
Other end user impact
|
||||
---------------------
|
||||
|
||||
The nova cli will make sure to deprecate all these features as well,
|
||||
and we'll plan to remove those in O.
|
||||
|
||||
Performance Impact
|
||||
------------------
|
||||
|
||||
This should reduce some load on Nova once these APIs are gone, as
|
||||
users will go and directly hit the APIs they need to access.
|
||||
|
||||
Other deployer impact
|
||||
---------------------
|
||||
|
||||
The value of ``glance.api_servers`` becomes more relevant than it was
|
||||
before.
|
||||
|
||||
Developer impact
|
||||
----------------
|
||||
|
||||
None
|
||||
|
||||
Implementation
|
||||
==============
|
||||
|
||||
Assignee(s)
|
||||
-----------
|
||||
|
||||
Primary assignee:
|
||||
sdague
|
||||
|
||||
Work Items
|
||||
----------
|
||||
|
||||
* Updated API Ref site with items as deprecated
|
||||
* Introduce microversion to trigger 404 on these resources
|
||||
* Remove limits keys in this microversion
|
||||
* Tighten up imageRef validation in this microversion
|
||||
* Create Tempest tests for items such as setting addresses on ports in
|
||||
neutron, then verifying they look correct in the server object via nova
|
||||
|
||||
Dependencies
|
||||
============
|
||||
|
||||
None
|
||||
|
||||
Testing
|
||||
=======
|
||||
|
||||
There will be in tree functional testing that these APIs do the right
|
||||
thing after this microversion and return 404s.
|
||||
|
||||
There exist many tempest tests which provide round trip on the APIs in
|
||||
question, but very few that actually attempt to set the resource data
|
||||
with the native API, then get it via the Nova API (such as IPs /
|
||||
Security groups that are embedded in the server representation).
|
||||
|
||||
This should be tested more fully, and the deprecation of the proxies
|
||||
will be a good opportunity for that.
|
||||
|
||||
Documentation Impact
|
||||
====================
|
||||
|
||||
API Reference will be updated as described above.
|
||||
|
||||
References
|
||||
==========
|
||||
|
||||
Newton Summit Session on API deprecations - https://etherpad.openstack.org/p/newton-nova-api
|
||||
|
||||
History
|
||||
=======
|
||||
|
||||
.. list-table:: Revisions
|
||||
:header-rows: 1
|
||||
|
||||
* - Newton
|
||||
- Introduced
|
||||
Reference in New Issue
Block a user