Add spec for IPA API versioning support
Change-Id: I7b4cbf19ae35c35d2938d27d9a1745cb949b13b5 Related-Bug: #1602265
This commit is contained in:
Sam Betts
parent
979899d10a
commit
c0ebaa2c7a
|
|
@ -0,0 +1,202 @@
|
|||
..
|
||||
This work is licensed under a Creative Commons Attribution 3.0 Unported
|
||||
License.
|
||||
|
||||
http://creativecommons.org/licenses/by/3.0/legalcode
|
||||
|
||||
==================================================
|
||||
ironic-python-agent API Versioning and Negotiation
|
||||
==================================================
|
||||
|
||||
https://bugs.launchpad.net/ironic/+bug/1602265
|
||||
|
||||
It was decided at the ironic newton midcycle that we need some form of API
|
||||
version negotiation between ironic and IPA. This is required to allow ironic to
|
||||
recognise that it is talking to an older ramdisk, and that newer features will
|
||||
not be available.
|
||||
|
||||
Problem description
|
||||
===================
|
||||
|
||||
During ironic upgrade it's possible that you will end up with node which uses
|
||||
an version of the ironic-python-agent (IPA) older than the version of ironic.
|
||||
In this case newer features that have been added to ironic and IPA will be
|
||||
expected to exist by ironic however because the ramdisk used on a node has not
|
||||
been upgraded yet, those features do not exist in that version of IPA. This
|
||||
leads to failures because ironic tries to use these features during
|
||||
deployment/cleaning and resulting in unexpected responses from IPA.
|
||||
|
||||
Proposed change
|
||||
===============
|
||||
|
||||
The proposed change is that when IPA does its heartbeat to ironic it will
|
||||
include an IPA version number that will be cached by ironic in the node's
|
||||
``driver_internal_info`` in the same way as the Agent URL is stored. ironic
|
||||
will then use this version information to gracefully degrade the feature set
|
||||
that it uses from the ironic-python-agent. For example::
|
||||
|
||||
def do_something_using_IPA(self)
|
||||
# Make sure to refresh the node object in case agent_version has changed
|
||||
# via a heartbeat since we first fetched the node.
|
||||
node = self.node.refresh()
|
||||
if node.driver_internal_info.get('agent_version', '0.0.0') >= '1.2':
|
||||
do_new_additional_thing_only_supported_in_1.2()
|
||||
do_thing_using_IPA()
|
||||
|
||||
Alternatives
|
||||
------------
|
||||
|
||||
A couple of alternatives exist:
|
||||
|
||||
* Require that operators update every node's ramdisk to the newer version of
|
||||
the ramdisk with the new features before upgrading their ironic installation.
|
||||
|
||||
* Handle the cases where IPA doesn't support a particular feature by catching a
|
||||
set of expected errors on a case by case basis and gracefully fall back to
|
||||
another method. However in cases where this occurs it will result in more
|
||||
complex error handling in Ironic and extra API calls to IPA.
|
||||
|
||||
Data model impact
|
||||
-----------------
|
||||
|
||||
New ``agent_version`` field will be be stored in ``node.driver_internal_info``
|
||||
on agent heartbeat.
|
||||
|
||||
State Machine Impact
|
||||
--------------------
|
||||
|
||||
In the existing code the cleaning step checks the IPA hardware manager version
|
||||
and if it changes for any reason during the cleaning process, then cleaning is
|
||||
aborted and will need to be restarted. The agent version being added by this
|
||||
spec should be treated in the same way to ensure the most stable environment
|
||||
for cleaning.
|
||||
|
||||
REST API impact
|
||||
---------------
|
||||
|
||||
A new field ``agent_version`` will we included in the body of the heartbeat API
|
||||
request alongside the existing ``agent_url`` field.
|
||||
|
||||
Client (CLI) impact
|
||||
-------------------
|
||||
|
||||
None
|
||||
|
||||
"ironic" CLI
|
||||
~~~~~~~~~~~~
|
||||
|
||||
None
|
||||
|
||||
"openstack baremetal" CLI
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
None
|
||||
|
||||
RPC API impact
|
||||
--------------
|
||||
|
||||
None
|
||||
|
||||
Driver API impact
|
||||
-----------------
|
||||
|
||||
None
|
||||
|
||||
Nova driver impact
|
||||
------------------
|
||||
|
||||
None
|
||||
|
||||
Ramdisk impact
|
||||
--------------
|
||||
|
||||
IPA will need updating to include its current version in the ``agent_version``
|
||||
field when it makes a heartbeat request.
|
||||
|
||||
Security impact
|
||||
---------------
|
||||
|
||||
None
|
||||
|
||||
Other end user impact
|
||||
---------------------
|
||||
|
||||
None
|
||||
|
||||
Scalability impact
|
||||
------------------
|
||||
|
||||
None
|
||||
|
||||
Performance Impact
|
||||
------------------
|
||||
|
||||
None
|
||||
|
||||
Other deployer impact
|
||||
---------------------
|
||||
|
||||
This change will allow for deployers upgrading their ironic installs to upgrade
|
||||
their node's ironic-python-agent ramdisk's asynchronously from the rest of
|
||||
ironic.
|
||||
|
||||
Developer impact
|
||||
----------------
|
||||
|
||||
Developers of ironic drivers that interact with the ironic-python-agent will
|
||||
need to ensure their code takes into account the agent version that they might
|
||||
be talking to. Making sure that if talking to an IPA that does not support a
|
||||
feature it disables that feature in ironic.
|
||||
|
||||
Implementation
|
||||
==============
|
||||
|
||||
Assignee(s)
|
||||
-----------
|
||||
|
||||
Primary assignee:
|
||||
sambetts
|
||||
|
||||
Work Items
|
||||
----------
|
||||
|
||||
- Add code to IPA to send its version to ironic in the heartbeat request
|
||||
- Add code to ironic to accept and store the ``agent_version`` when it receives
|
||||
a heartbeat
|
||||
- Add developer documentation on the correct way to add support for an IPA
|
||||
feature in ironic, such that it will gracefully degrade if it is not
|
||||
available.
|
||||
|
||||
Dependencies
|
||||
============
|
||||
|
||||
None
|
||||
|
||||
Testing
|
||||
=======
|
||||
|
||||
- ironic grenade tests already test ironic master with the last named release
|
||||
IPA
|
||||
- Normal ironic/IPA tests will test ironic master + IPA master builds
|
||||
- Need to add a grenade test to IPA to test last ironic named release + master
|
||||
IPA
|
||||
|
||||
Upgrades and Backwards Compatibility
|
||||
====================================
|
||||
|
||||
- This spec adds the ability to better support Ironic version N+1 with IPA
|
||||
version N or older as Ironic will gracefully degrade which features it will
|
||||
request if they aren't available
|
||||
- Ironic version N works with IPA version N+1 and should continue to work
|
||||
|
||||
Documentation Impact
|
||||
====================
|
||||
|
||||
- Need to add the developer documentation mention in the work items section
|
||||
- Need to document which versions of IPA are supported with which versions of
|
||||
ironic.
|
||||
|
||||
References
|
||||
==========
|
||||
|
||||
- https://etherpad.openstack.org/p/ironic-newton-midcycle
|
||||
|
|
@ -0,0 +1 @@
|
|||
../approved/ipa_api_versioning.rst
|
||||
Loading…
Reference in New Issue