8.7 KiB
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.
"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 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:
"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
Release Name | Description |
---|---|
Newton | Introduced |