ironic-python-agent API Versioning and Negotiation¶
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.
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.
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:
# 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':
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¶
agent_version field will be stored in
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
Client (CLI) impact¶
“openstack baremetal” CLI¶
RPC API impact¶
Driver API impact¶
Nova driver impact¶
IPA will need updating to include its current version in the
field when it makes a heartbeat request.
Other end user impact¶
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.
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.
- Primary assignee:
Add code to IPA to send its version to ironic in the heartbeat request
Add code to ironic to accept and store the
agent_versionwhen 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.
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
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.