Developing deploy and clean steps¶
Deploy steps basics¶
To support customized deployment step, implement a new method in an interface
class and use the decorator deploy_step defined in
ironic/drivers/base.py. For example, we will implement a do_nothing
deploy step in the AgentDeploy class.
from ironic.drivers.modules import agent
class AgentDeploy(agent.AgentDeploy):
@base.deploy_step(priority=200, argsinfo={
'test_arg': {
'description': (
"This is a test argument."
),
'required': True
}
})
def do_nothing(self, task, **kwargs):
return None
If you want to completely replace the deployment procedure, but still have the
agent up and running, inherit CustomAgentDeploy:
from ironic.drivers.modules import agent
class AgentDeploy(agent.CustomAgentDeploy):
def validate(self, task):
super().validate(task)
# ... custom validation
@base.deploy_step(priority=80)
def my_write_image(self, task, **kwargs):
pass # ... custom image writing
@base.deploy_step(priority=70)
def my_configure_bootloader(self, task, **kwargs):
pass # ... custom bootloader configuration
After deployment of the baremetal node, check the updated deploy steps:
baremetal node show $node_ident -f json -c driver_internal_info
The above command outputs the driver_internal_info as following:
{
"driver_internal_info": {
...
"deploy_steps": [
{
"priority": 200,
"interface": "deploy",
"step": "do_nothing",
"argsinfo":
{
"test_arg":
{
"required": True,
"description": "This is a test argument."
}
}
},
{
"priority": 100,
"interface": "deploy",
"step": "deploy",
"argsinfo": null
}
],
"deploy_step_index": 1
}
}
In-band deploy steps (deploy steps that are run inside the ramdisk) have to be implemented in a custom IPA hardware manager. All in-band deploy steps must have priorities between 41 and 99, see Agent steps for details.
Clean steps basics¶
Clean steps are written similarly to deploy steps, but are executed during cleaning. Steps with priority > 0 are executed during automated cleaning, all steps can be executed explicitly during manual cleaning. Unlike deploy steps, clean steps are commonly found in these interfaces:
biosSteps that apply BIOS settings, see Implementing BIOS settings.
deploySteps that undo the effect of deployment (e.g. erase disks).
managementAdditional steps that use the node’s BMC, such as out-of-band firmware update or BMC reset.
raidSteps that build or tear down RAID, see Implementing RAID.
Note
When designing a new step for your driver, try to make it consistent with existing steps on other drivers.
Just as deploy steps, in-band clean steps have to be implemented in a custom IPA hardware manager.
Asynchronous steps¶
If the step returns None, ironic assumes its execution is finished and
proceeds to the next step. Many steps are executed asynchronously; in this case
you need to inform ironic that the step is not finished. There are several
possibilities:
Combined in-band and out-of-band step¶
If your step starts as out-of-band and then proceeds as in-band (i.e. inside
the agent), you only need to return CLEANWAIT/DEPLOYWAIT from
the step.
from ironic.drivers import base
from ironic.drivers.modules import agent
from ironic.drivers.modules import agent_base
from ironic.drivers.modules import agent_client
from ironic.drivers.modules import deploy_utils
class MyDeploy(agent.CustomAgentDeploy):
...
@base.deploy_step(priority=80)
def my_deploy(self, task):
...
return deploy_utils.get_async_step_return_state(task.node)
# Usually you can use a more high-level pattern:
@base.deploy_step(priority=60)
def my_deploy2(self, task):
new_step = {'interface': 'deploy',
'step': 'my_deploy2',
'args': {...}}
client = agent_client.get_client(task)
return agent_base.execute_step(task, new_step, 'deploy',
client=client)
Warning
This approach only works for steps implemented on a deploy
interface that inherits agent deploy.
Warning
Steps generally should have a return value of None unless the a state is returned as part of an asyncrhonous workflow.
Please be mindful of this constraint when creating steps, as the step runner will error if a value aside from None is returned upon step completion.
Execution on reboot¶
Some steps are executed out-of-band, but require a reboot to complete. Use the following pattern:
from ironic.drivers import base
from ironic.drivers.modules import deploy_utils
class MyManagement(base.ManagementInterface):
...
@base.clean_step(priority=0)
def my_action(self, task):
...
# Tell ironic that...
deploy_utils.set_async_step_flags(
node,
# ... we're waiting for IPA to come back after reboot
reboot=True,
# ... the current step is done
skip_current_step=True)
return deploy_utils.reboot_to_finish_step(task)
Polling for completion¶
Finally, you may want to poll the BMC until the operation is complete. Often
enough, this also involves a reboot. In this case you can use the
ironic.conductor.periodics.node_periodic() decorator to create a
periodic task that operates on relevant nodes:
from ironic.common import states
from ironic.common import utils
from ironic.conductor import periodics
from ironic.drivers import base
from ironic.drivers.modules import deploy_utils
_STATUS_CHECK_INTERVAL = ... # better use a configuration option
class MyManagement(base.ManagementInterface):
...
@base.clean_step(priority=0)
def my_action(self, task):
...
reboot_required = ... # your step may or may not need rebooting
# Make this node as running my_action. Often enough you will store
# some useful data rather than a boolean flag.
utils.set_node_nested_field(task.node, 'driver_internal_info',
'in_my_action', True)
# Tell ironic that...
deploy_utils.set_async_step_flags(
node,
# ... we're waiting for IPA to come back after reboot
reboot=reboot_required,
# ... the current step shouldn't be entered again
skip_current_step=True,
# ... we'll be polling until the step is done
polling=True)
if reboot_required:
return deploy_utils.reboot_to_finish_step(task)
@periodics.node_periodic(
purpose='checking my action status',
spacing=_STATUS_CHECK_INTERVAL,
filters={
# Skip nodes that already have a lock
'reserved': False,
# Only consider nodes that are waiting for cleaning or failed
# on timeout.
'provision_state_in': [states.CLEANWAIT, states.CLEANFAIL],
},
# Load driver_internal_info from the database on listing
predicate_extra_fields=['driver_internal_info'],
# Only consider nodes with in_my_action
predicate=lambda n: n.driver_internal_info.get('in_my_action'),
)
def check_my_action(self, task, manager, context):
if not needs_actions(): # insert your checks here
return
task.upgrade_lock()
... # do any required updates
# Drop the flag so that this node is no longer considered
utils.pop_node_nested_field(task.node, 'driver_internal_info',
'in_my_action')
Note that creating a task involves an additional database query, so you
want to avoid creating them for too many nodes in your periodic tasks. Instead:
Try to use precise
filtersto filter out nodes on the database level. Usingreservedandprovision_state/provision_state_inare recommended in most cases. Seeironic.db.api.Connection.get_nodeinfo_list()for a list of possible filters.Use
predicateto filter on complex fields such asdriver_internal_info. Predicates are checked before tasks are created.
Implementing RAID¶
RAID is implemented via deploy and clean steps in the raid interfaces.
By convention they have the following signatures:
from ironic.drivers import base
class MyRAID(base.RAIDInterface):
@base.clean_step(priority=0, abortable=False, argsinfo={
'create_root_volume': {
'description': (
'This specifies whether to create the root volume. '
'Defaults to `True`.'
),
'required': False
},
'create_nonroot_volumes': {
'description': (
'This specifies whether to create the non-root volumes. '
'Defaults to `True`.'
),
'required': False
},
'delete_existing': {
'description': (
'Setting this to `True` indicates to delete existing RAID '
'configuration prior to creating the new configuration. '
'Default value is `False`.'
),
'required': False,
}
})
def create_configuration(self, task, create_root_volume=True,
create_nonroot_volumes=True,
delete_existing=False):
pass
@base.clean_step(priority=0)
@base.deploy_step(priority=0)
def delete_configuration(self, task):
pass
@base.deploy_step(priority=0,
argsinfo=base.RAID_APPLY_CONFIGURATION_ARGSINFO)
def apply_configuration(self, task, raid_config,
create_root_volume=True,
create_nonroot_volumes=False,
delete_existing=False):
pass
Notes:
create_configurationonly works as a clean step, during deploymentapply_configurationis used instead.apply_configurationaccepts the target RAID configuration explicitly, whilecreate_configurationuses the node’starget_raid_configfield.Priorities default to 0 since RAID should not be built by default.
Implementing BIOS settings¶
BIOS is implemented via deploy and clean steps in the raid interfaces.
By convention they have the following signatures:
from ironic.drivers import base
_APPLY_CONFIGURATION_ARGSINFO = {
'settings': {
'description': (
'A list of BIOS settings to be applied'
),
'required': True
}
}
class MyBIOS(base.BIOSInterface):
@base.clean_step(priority=0)
@base.deploy_step(priority=0)
@base.cache_bios_settings
def factory_reset(self, task):
pass
@base.clean_step(priority=0, argsinfo=_APPLY_CONFIGURATION_ARGSINFO)
@base.deploy_step(priority=0, argsinfo=_APPLY_CONFIGURATION_ARGSINFO)
@base.cache_bios_settings
def apply_configuration(self, task, settings):
pass
Notes:
Both
factory_resetandapply_configurationcan be used as deploy and clean steps.The
cache_bios_settingsdecorator is used to ensure that the settings cached in the ironic database is updated.Priorities default to 0 since BIOS settings should not be modified by default.
