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

11 files changed, 73 insertions, 2 deletions

diff --git a/api-ref/source/baremetal-api-v1-drivers.inc b/api-ref/source/baremetal-api-v1-drivers.inc
index 439a04316..d10335b0e 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 7e4c01e71..cf55a8fee 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 16c9765b8..34cf73b69 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 cb8f290d1..15e859ad5 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 fdf5ad3a0..552eb8a3d 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 05f23ae35..789b90a96 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 640f27cc0..64605e667 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 00eddfa5a..95e27c4ff 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 41f380396..36dadef97 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 edea40007..fd963647e 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 93f4faa44..7d17ce415 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": [