From d3b392e679c4bc3d75db39839ff3c7f1d9f691c1 Mon Sep 17 00:00:00 2001 From: Sean Dague Date: Tue, 3 May 2016 15:12:52 -0400 Subject: [PATCH] Deprecate API Proxies This describes how we should deprecate API proxies to make them less used in the wild. APIImpact Change-Id: Icca01fc8b2f24340a53feaf212a022e89096319a --- .../newton/approved/deprecate-api-proxies.rst | 304 ++++++++++++++++++ 1 file changed, 304 insertions(+) create mode 100644 specs/newton/approved/deprecate-api-proxies.rst diff --git a/specs/newton/approved/deprecate-api-proxies.rst b/specs/newton/approved/deprecate-api-proxies.rst new file mode 100644 index 000000000..1a868eaac --- /dev/null +++ b/specs/newton/approved/deprecate-api-proxies.rst @@ -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 +`_ +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