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 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 heartbeatAdd 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.