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 <mario.villaplana@gmail.com>
Co-Authored-By: Aparna <aparnavtce@gmail.com>
Co-Authored-By: Shivanand Tendulker <stendulker@gmail.com>

Partial-Bug: 1526449

Change-Id: Ifcfa52ede62894b1990aaa640944be3431ddfe8f

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

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:**
 

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

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

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"
   ],

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"
       ],

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": [

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": [

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": [

api-ref/source/samples/node-validate-response.json

@@ -23,6 +23,10 @@
   "raid": {
     "result": true
   },
+  "rescue": {
+    "reason": "not supported",
+    "result": null
+  },
   "storage": {
     "result": true
   }

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": [

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.