From 9a6c62dd8e54bb07f4ca4da0b4c3c4e71ebf7971 Mon Sep 17 00:00:00 2001 From: Mario Villaplana Date: Thu, 12 Jan 2017 18:51:36 +0000 Subject: [PATCH] Add api-ref and ironic state documentation for rescue This patch adds following: - Updates ironic state documentation with rescue related states - Updates api-ref with rescue interface fields introduced in API version 1.38 Co-Authored-By: Mario Villaplana Co-Authored-By: Aparna Co-Authored-By: Shivanand Tendulker Partial-Bug: 1526449 Change-Id: Ifcfa52ede62894b1990aaa640944be3431ddfe8f --- api-ref/source/baremetal-api-v1-drivers.inc | 4 ++ .../baremetal-api-v1-node-management.inc | 6 ++ api-ref/source/baremetal-api-v1-nodes.inc | 10 +++- api-ref/source/parameters.yaml | 34 ++++++++++- .../source/samples/driver-get-response.json | 4 ++ .../samples/drivers-list-detail-response.json | 8 +++ .../source/samples/node-create-response.json | 1 + .../source/samples/node-show-response.json | 1 + .../node-update-driver-info-response.json | 1 + .../samples/node-validate-response.json | 4 ++ .../samples/nodes-list-details-response.json | 2 + doc/source/contributor/states.rst | 60 ++++++++++++++++++- 12 files changed, 132 insertions(+), 3 deletions(-) diff --git a/api-ref/source/baremetal-api-v1-drivers.inc b/api-ref/source/baremetal-api-v1-drivers.inc index 439a043160..d10335b0eb 100644 --- a/api-ref/source/baremetal-api-v1-drivers.inc +++ b/api-ref/source/baremetal-api-v1-drivers.inc @@ -88,6 +88,7 @@ drivers supported by this Ironic service. - default_network_interface: default_network_interface - default_power_interface: default_power_interface - default_raid_interface: default_raid_interface + - default_rescue_interface: default_rescue_interface - default_storage_interface: default_storage_interface - default_vendor_interface: default_vendor_interface - enabled_boot_interfaces: enabled_boot_interfaces @@ -97,6 +98,7 @@ drivers supported by this Ironic service. - enabled_management_interfaces: enabled_management_interfaces - enabled_network_interfaces: enabled_network_interfaces - enabled_power_interfaces: enabled_power_interfaces + - enabled_rescue_interfaces: enabled_rescue_interfaces - enabled_raid_interfaces: enabled_raid_interfaces - enabled_storage_interfaces: enabled_storage_interfaces - enabled_vendor_interfaces: enabled_vendor_interfaces @@ -146,6 +148,7 @@ Response Parameters - default_network_interface: default_network_interface - default_power_interface: default_power_interface - default_raid_interface: default_raid_interface + - default_rescue_interface: default_rescue_interface - default_storage_interface: default_storage_interface - default_vendor_interface: default_vendor_interface - enabled_boot_interfaces: enabled_boot_interfaces @@ -156,6 +159,7 @@ Response Parameters - enabled_network_interfaces: enabled_network_interfaces - enabled_power_interfaces: enabled_power_interfaces - enabled_raid_interfaces: enabled_raid_interfaces + - enabled_rescue_interfaces: enabled_rescue_interfaces - enabled_storage_interfaces: enabled_storage_interfaces - enabled_vendor_interfaces: enabled_vendor_interfaces - links: links diff --git a/api-ref/source/baremetal-api-v1-node-management.inc b/api-ref/source/baremetal-api-v1-node-management.inc index 7e4c01e716..cf55a8fee3 100644 --- a/api-ref/source/baremetal-api-v1-node-management.inc +++ b/api-ref/source/baremetal-api-v1-node-management.inc @@ -74,6 +74,7 @@ the Node's driver does not support that interface. - network: v_network - power: v_power - raid: v_raid + - rescue: v_rescue - storage: v_storage **Example node validation response:** @@ -347,6 +348,10 @@ detailed documentation of the Ironic State Machine is available .. versionadded:: 1.35 A ``configdrive`` can be provided when setting the node's provision target state to ``rebuild``. +.. versionadded:: 1.38 + A node can be rescued or unrescued by setting the node's provision target state to + ``rescue`` or ``unrescue`` respectively. + Normal response code: 202 Error codes: @@ -364,6 +369,7 @@ Request - target: requested_provision_state - configdrive: configdrive - clean_steps: clean_steps + - rescue_password: rescue_password **Example request to deploy a Node, using a configdrive served via local webserver:** diff --git a/api-ref/source/baremetal-api-v1-nodes.inc b/api-ref/source/baremetal-api-v1-nodes.inc index 16c9765b84..34cf73b69a 100644 --- a/api-ref/source/baremetal-api-v1-nodes.inc +++ b/api-ref/source/baremetal-api-v1-nodes.inc @@ -82,6 +82,10 @@ supplied when the Node is created, or the resource may be updated later. Introduced the ``storage_interface`` field. If this field is not supplied when creating the Node, the default value will be used. +.. versionadded:: 1.38 + Introduced the ``rescue_interface`` field. If this field is not supplied + when creating the Node, the default value will be used. + Normal response codes: 201 .. TODO: add error codes @@ -111,7 +115,7 @@ and any defaults added for non-specified fields. Most fields default to "null" or "". The list and example below are representative of the response as of API -microversion 1.37. +microversion 1.38. .. rest_parameters:: parameters.yaml @@ -150,6 +154,7 @@ microversion 1.37. - network_interface: network_interface - power_interface: power_interface - raid_interface: raid_interface + - rescue_interface: rescue_interface - storage_interface: storage_interface - traits: n_traits - vendor_interface: vendor_interface @@ -303,6 +308,7 @@ Response - network_interface: network_interface - power_interface: power_interface - raid_interface: raid_interface + - rescue_interface: rescue_interface - storage_interface: storage_interface - traits: n_traits - vendor_interface: vendor_interface @@ -378,6 +384,7 @@ Response - network_interface: network_interface - power_interface: power_interface - raid_interface: raid_interface + - rescue_interface: rescue_interface - storage_interface: storage_interface - traits: n_traits - vendor_interface: vendor_interface @@ -460,6 +467,7 @@ Response - network_interface: network_interface - power_interface: power_interface - raid_interface: raid_interface + - rescue_interface: rescue_interface - storage_interface: storage_interface - traits: n_traits - vendor_interface: vendor_interface diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index cb8f290d1a..15e859ad52 100644 --- a/api-ref/source/parameters.yaml +++ b/api-ref/source/parameters.yaml @@ -456,6 +456,13 @@ default_raid_interface: in: body required: true type: string +default_rescue_interface: + description: | + The default rescue interface used for a node with a dynamic driver, if + no rescue interface is specified for the node. + in: body + required: true + type: string default_storage_interface: description: | The default storage interface used for a node with a dynamic driver, if @@ -561,6 +568,12 @@ enabled_raid_interfaces: in: body required: true type: list +enabled_rescue_interfaces: + description: | + The enabled rescue interfaces for this driver. + in: body + required: true + type: list enabled_storage_interfaces: description: | The enabled storage interfaces for this driver. @@ -950,10 +963,23 @@ reason: requested_provision_state: description: | One of the provisioning verbs: manage, provide, inspect, clean, active, - rebuild, delete (deleted), abort, adopt. + rebuild, delete (deleted), abort, adopt, rescue, unrescue. in: body required: true type: string +rescue_interface: + description: | + The interface used for node rescue, e.g. "no-rescue". + in: body + required: true + type: string +rescue_password: + description: | + Non-empty password used to configure rescue ramdisk during node rescue + operation. + in: body + required: false + type: string reservation: description: | The ``name`` of an Ironic Conductor host which is holding a lock on this node, @@ -1085,6 +1111,12 @@ v_raid: in: body required: true type: object +v_rescue: + description: | + Status of the "rescue" interface + in: body + required: true + type: object v_storage: description: | Status of the "storage" interface diff --git a/api-ref/source/samples/driver-get-response.json b/api-ref/source/samples/driver-get-response.json index fdf5ad3a0c..552eb8a3d8 100644 --- a/api-ref/source/samples/driver-get-response.json +++ b/api-ref/source/samples/driver-get-response.json @@ -7,6 +7,7 @@ "default_network_interface": "flat", "default_power_interface": "ipmitool", "default_raid_interface": "no-raid", + "default_rescue_interface": "no-rescue", "default_storage_interface": "noop", "default_vendor_interface": "no-vendor", "enabled_boot_interfaces": [ @@ -36,6 +37,9 @@ "no-raid", "agent" ], + "enabled_rescue_interfaces": [ + "no-rescue" + ], "enabled_storage_interfaces": [ "noop" ], diff --git a/api-ref/source/samples/drivers-list-detail-response.json b/api-ref/source/samples/drivers-list-detail-response.json index 05f23ae35b..789b90a967 100644 --- a/api-ref/source/samples/drivers-list-detail-response.json +++ b/api-ref/source/samples/drivers-list-detail-response.json @@ -9,6 +9,7 @@ "default_network_interface": null, "default_power_interface": null, "default_raid_interface": null, + "default_rescue_interface": null, "default_storage_interface": null, "default_vendor_interface": null, "enabled_boot_interfaces": null, @@ -19,6 +20,7 @@ "enabled_network_interfaces": null, "enabled_power_interfaces": null, "enabled_raid_interfaces": null, + "enabled_rescue_interfaces": null, "enabled_storage_interfaces": null, "enabled_vendor_interfaces": null, "hosts": [ @@ -56,6 +58,7 @@ "default_network_interface": null, "default_power_interface": null, "default_raid_interface": null, + "default_rescue_interface": null, "default_storage_interface": null, "default_vendor_interface": null, "enabled_boot_interfaces": null, @@ -66,6 +69,7 @@ "enabled_network_interfaces": null, "enabled_power_interfaces": null, "enabled_raid_interfaces": null, + "enabled_rescue_interfaces": null, "enabled_storage_interfaces": null, "enabled_vendor_interfaces": null, "hosts": [ @@ -103,6 +107,7 @@ "default_network_interface": "flat", "default_power_interface": "ipmitool", "default_raid_interface": "no-raid", + "default_rescue_interface": "no-rescue", "default_storage_interface": "noop", "default_vendor_interface": "no-vendor", "enabled_boot_interfaces": [ @@ -132,6 +137,9 @@ "no-raid", "agent" ], + "enabled_rescue_interfaces": [ + "no-rescue" + ], "enabled_storage_interfaces": [ "noop" ], diff --git a/api-ref/source/samples/node-create-response.json b/api-ref/source/samples/node-create-response.json index 640f27cc0c..64605e6677 100644 --- a/api-ref/source/samples/node-create-response.json +++ b/api-ref/source/samples/node-create-response.json @@ -61,6 +61,7 @@ "provision_updated_at": null, "raid_config": {}, "raid_interface": null, + "rescue_interface": null, "reservation": null, "resource_class": null, "states": [ diff --git a/api-ref/source/samples/node-show-response.json b/api-ref/source/samples/node-show-response.json index 00eddfa5a5..95e27c4fff 100644 --- a/api-ref/source/samples/node-show-response.json +++ b/api-ref/source/samples/node-show-response.json @@ -63,6 +63,7 @@ "provision_updated_at": "2016-08-18T22:28:49.946416+00:00", "raid_config": {}, "raid_interface": null, + "rescue_interface": null, "reservation": null, "resource_class": null, "states": [ diff --git a/api-ref/source/samples/node-update-driver-info-response.json b/api-ref/source/samples/node-update-driver-info-response.json index 41f3803960..36dadef978 100644 --- a/api-ref/source/samples/node-update-driver-info-response.json +++ b/api-ref/source/samples/node-update-driver-info-response.json @@ -65,6 +65,7 @@ "provision_updated_at": "2016-08-18T22:28:49.946416+00:00", "raid_config": {}, "raid_interface": null, + "rescue_interface": null, "reservation": null, "resource_class": null, "states": [ diff --git a/api-ref/source/samples/node-validate-response.json b/api-ref/source/samples/node-validate-response.json index edea400071..fd963647e6 100644 --- a/api-ref/source/samples/node-validate-response.json +++ b/api-ref/source/samples/node-validate-response.json @@ -23,6 +23,10 @@ "raid": { "result": true }, + "rescue": { + "reason": "not supported", + "result": null + }, "storage": { "result": true } diff --git a/api-ref/source/samples/nodes-list-details-response.json b/api-ref/source/samples/nodes-list-details-response.json index 93f4faa44c..7d17ce415e 100644 --- a/api-ref/source/samples/nodes-list-details-response.json +++ b/api-ref/source/samples/nodes-list-details-response.json @@ -65,6 +65,7 @@ "provision_updated_at": "2016-08-18T22:28:49.946416+00:00", "raid_config": {}, "raid_interface": null, + "rescue_interface": null, "reservation": null, "resource_class": null, "states": [ @@ -159,6 +160,7 @@ "provision_updated_at": null, "raid_config": {}, "raid_interface": "no-raid", + "rescue_interface": "no-rescue", "reservation": null, "resource_class": null, "states": [ diff --git a/doc/source/contributor/states.rst b/doc/source/contributor/states.rst index 37b8ae537d..9209e119cc 100644 --- a/doc/source/contributor/states.rst +++ b/doc/source/contributor/states.rst @@ -147,11 +147,13 @@ active (stable state) provision state using the ``deleted`` verb. * ``active`` (through ``deploying``) by setting the node's provision state using the ``rebuild`` verb. + * ``rescue`` (through ``rescuing``) by setting the node's provision state + using the ``rescue`` verb. deleting Nodes in ``deleting`` state are being torn down from running an active workload. In ``deleting``, ironic tears down and removes any configuration and - resources it added in ``deploying``. + resources it added in ``deploying`` or ``rescuing``. error (stable state) This is the state a node will move into when deleting an active deployment @@ -168,3 +170,59 @@ adopting existing workload on them, do not need to be deployed or cleaned again, so this transition allows these nodes to move directly from ``manageable`` to ``active``. + +rescuing + Nodes in ``rescuing`` are being prepared to perform rescue operations. + This consists of running a series of tasks, such as: + + * Setting appropriate BIOS configurations. + * Creating any additional resources (node-specific network config, etc.) that + may be required by additional subsystems. + +rescue wait + Just like the ``rescuing`` state, the nodes in ``rescue wait`` are being + rescued. The difference is that in ``rescue wait`` the conductor is + waiting for the ramdisk to boot or execute parts of the rescue which + need to run in-band on the node (for example, setting the password for + user named ``rescue``). + + The rescue operation of a node in ``rescue wait`` can be aborted by + setting the node's provision state using the ``abort`` verb. + +rescue failed + This is the state a node will move into when a rescue operation fails, + for example a timeout waiting for the ramdisk to PXE boot. From here the + node can be transitioned to: + + * ``rescue`` (through ``rescuing``) by setting the node's provision state + using the ``rescue`` verb. + * ``active`` (through ``unrescuing``) by setting the node's provision state + using the ``unrescue`` verb. + * ``available`` (through ``deleting``) by setting the node's provision state + using the ``deleted`` verb. + +rescue (stable state) + Nodes in ``rescue`` have a rescue ramdisk running on them. Ironic may collect + out-of-band sensor information (including power state) on a regular basis. + Nodes in ``rescue`` can transition to: + + * ``active`` (through ``unrescuing``) by setting the node's provision state + using the ``unrescue`` verb. + * ``available`` (through ``deleting``) by setting the node's provision state + using the ``deleted`` verb. + +unrescuing + Nodes in ``unrescuing`` are being prepared to transition to ``active`` state + from ``rescue`` state. This consists of running a series of tasks, such as + setting appropriate BIOS configurations such as changing boot device. + +unrescue failed + This is the state a node will move into when an unrescue operation fails. + From here the node can be transitioned to: + + * ``rescue`` (through ``rescuing``) by setting the node's provision state + using the ``rescue`` verb. + * ``active`` (through ``unrescuing``) by setting the node's provision state + using the ``unrescue`` verb. + * ``available`` (through ``deleting``) by setting the node's provision state + using the ``deleted`` verb.