Expose conductors: api-ref

This patch updates API reference to contain the changes made
by the feature of exposing conductors.

Story: 1724474
Task: 28064

Change-Id: I47dbea2cda1cc0ad73786fe3fe9b80850e1cf289

api-ref/source/baremetal-api-v1-conductors.inc

@@ -0,0 +1,97 @@
+.. -*- rst -*-
+
+=======================
+Conductors (conductors)
+=======================
+
+.. versionadded:: 1.49
+
+Listing Conductor resources is done through the ``conductors`` resource.
+
+Conductor resources are read-only, they can not be created, updated, or
+removed.
+
+
+List Conductors
+===============
+
+.. rest_method:: GET /v1/conductors
+
+Return a list of conductors known by the Bare Metal service.
+
+By default, this query will return the hostname, conductor group, and alive
+status for each Conductor. When ``detail`` is set to True in the query string,
+will return the full representation of the resource.
+
+Normal response code: 200
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+    - fields: fields_for_conductor
+    - limit: limit
+    - marker: marker
+    - sort_dir: sort_dir
+    - sort_key: sort_key
+    - detail: detail
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+    - hostname: hostname
+    - conductor_group: conductor_group
+    - alive: alive
+    - drivers: drivers
+    - links: links
+
+**Example Conductor list response:**
+
+.. literalinclude:: samples/conductor-list-response.json
+   :language: javascript
+
+**Example detailed Conductor list response:**
+
+.. literalinclude:: samples/conductor-list-details-response.json
+   :language: javascript
+
+
+Show Conductor Details
+======================
+
+.. rest_method::  GET /v1/conductors/{hostname}
+
+Shows details for a conductor. By default, this will return the full
+representation of the resource; an optional ``fields`` parameter can be
+supplied to return only the specified set.
+
+Normal response codes: 200
+
+Error codes: 400,403,404,406
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+    - hostname: hostname_ident
+    - fields: fields_for_conductor
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+    - hostname: hostname
+    - conductor_group: conductor_group
+    - alive: alive
+    - drivers: drivers
+    - links: links
+
+**Example JSON representation of a Conductor:**
+
+.. literalinclude:: samples/conductor-show-response.json
+   :language: javascript

api-ref/source/baremetal-api-v1-nodes.inc

@@ -196,6 +196,7 @@ microversion 1.48.
     - conductor_group: conductor_group
     - protected: protected
     - protected_reason: protected_reason
+    - conductor: conductor
     - owner: owner
     - description: n_description
 
@@ -245,6 +246,10 @@ provision state, and maintenance setting for each Node.
   Introduced the ``conductor_group`` request parameter, to allow filtering the
   list of returned nodes by conductor group.
 
+.. versionadded:: 1.49
+  Introduced the ``conductor`` request parameter, to allow filtering the
+  list of returned nodes by conductor.
+
 .. versionadded:: 1.50
   Introduced the ``owner`` field.
 
@@ -267,6 +272,7 @@ Request
    - driver: r_driver
    - resource_class: r_resource_class
    - conductor_group: r_conductor_group
+   - conductor: r_conductor
    - fault: r_fault
    - owner: owner
    - description_contains: r_description_contains
@@ -325,6 +331,9 @@ Nova instance, eg. with a request to ``v1/nodes/detail?instance_uuid={NOVA INSTA
 .. versionadded:: 1.48
   Introduced the ``protected`` and ``protected_reason`` fields.
 
+.. versionadded:: 1.49
+  Introduced the ``conductor`` request parameter and ``conductor`` field.
+
 .. versionadded:: 1.50
   Introduced the ``owner`` field.
 
@@ -348,6 +357,7 @@ Request
    - driver: r_driver
    - resource_class: r_resource_class
    - conductor_group: r_conductor_group
+   - conductor: r_conductor
    - owner: owner
    - description_contains: r_description_contains
    - limit: limit
@@ -407,6 +417,7 @@ Response
     - protected_reason: protected_reason
     - owner: owner
     - description: n_description
+    - conductor: conductor
 
 **Example detailed list of Nodes:**
 
@@ -438,6 +449,9 @@ only the specified set.
 .. versionadded:: 1.48
   Introduced the ``protected`` and ``protected_reason`` fields.
 
+.. versionadded:: 1.49
+  Introduced the ``conductor`` field
+
 .. versionadded:: 1.50
   Introduced the ``owner`` field.
 
@@ -508,6 +522,7 @@ Response
     - protected_reason: protected_reason
     - owner: owner
     - description: n_description
+    - conductor: conductor
 
 **Example JSON representation of a Node:**
 
@@ -601,6 +616,7 @@ Response
     - protected_reason: protected_reason
     - owner: owner
     - description: n_description
+    - conductor: conductor
 
 **Example JSON representation of a Node:**
 

api-ref/source/index.rst

@@ -24,4 +24,5 @@
 .. include:: baremetal-api-v1-chassis.inc
 .. include:: baremetal-api-v1-misc.inc
 .. include:: baremetal-api-v1-nodes-bios.inc
+.. include:: baremetal-api-v1-conductors.inc
 

api-ref/source/parameters.yaml

@@ -56,6 +56,12 @@ driver_ident:
   in: path
   required: true
   type: string
+hostname_ident:
+  description: |
+    The hostname of the conductor.
+  in: path
+  required: true
+  type: string
 node_id:
   description: |
     The UUID of the node.
@@ -151,6 +157,19 @@ fields:
   in: query
   required: false
   type: array
+fields_for_conductor:
+  description: |
+    One or more fields to be returned in the response.
+
+    For example, the following request returns only the ``hostname``
+    and ``alive`` fields for each conductor:
+
+    ::
+
+       GET /v1/conductors?fields=hostname,alive
+  in: query
+  required: false
+  type: array
 limit:
   description: |
     Requests a page size of items. Returns a number of items up to a limit
@@ -197,6 +216,13 @@ r_associated:
   in: query
   required: false
   type: boolean
+r_conductor:
+  description: |
+    Filter the list of returned nodes, and only return those with the
+    specified ``conductor``.
+  in: query
+  required: false
+  type: string
 r_conductor_group:
   description: |
     Filter the list of returned nodes, and only return those with the
@@ -364,6 +390,13 @@ agent_node:
   type: JSON
 
 # variables in the API body
+alive:
+  description: |
+    The conductor status indicates whether a conductor is considered alive
+    or not.
+  in: body
+  required: true
+  type: boolean
 bios_setting_name:
   description: |
     The name of a Bios setting for a Node, eg. "virtualization".
@@ -422,12 +455,18 @@ clean_steps:
   in: body
   required: false
   type: array
+conductor:
+  description: |
+    The conductor currently servicing a node. This field is read-only.
+  in: body
+  required: false
+  type: string
 conductor_group:
   description: |
     The conductor group for a node. Case-insensitive string up to 255
     characters, containing ``a-z``, ``0-9``, ``_``, ``-``, and ``.``.
   in: body
-  required: false
+  required: true
   type: string
 configdrive:
   description: |
@@ -672,6 +711,12 @@ fault:
   in: body
   required: false
   type: string
+hostname:
+  description: |
+    The hostname of this conductor.
+  in: body
+  required: true
+  type: array
 hosts:
   description: |
     A list of active hosts that support this driver.

api-ref/source/samples/conductor-list-details-response.json

@@ -0,0 +1,44 @@
+{
+  "conductors": [
+    {
+      "links": [
+        {
+          "href": "http://127.0.0.1:6385/v1/conductors/compute1.localdomain",
+          "rel": "self"
+        },
+        {
+          "href": "http://127.0.0.1:6385/conductors/compute1.localdomain",
+          "rel": "bookmark"
+        }
+      ],
+      "created_at": "2018-08-07T08:39:21+00:00",
+      "hostname": "compute1.localdomain",
+      "conductor_group": "",
+      "updated_at": "2018-11-30T07:07:23+00:00",
+      "alive": false,
+      "drivers": [
+        "ipmi"
+      ]
+    },
+    {
+      "links": [
+        {
+          "href": "http://127.0.0.1:6385/v1/conductors/compute2.localdomain",
+          "rel": "self"
+        },
+        {
+          "href": "http://127.0.0.1:6385/conductors/compute2.localdomain",
+          "rel": "bookmark"
+        }
+      ],
+      "created_at": "2018-12-05T07:03:19+00:00",
+      "hostname": "compute2.localdomain",
+      "conductor_group": "",
+      "updated_at": "2018-12-05T07:03:21+00:00",
+      "alive": true,
+      "drivers": [
+        "ipmi"
+      ]
+    }
+  ]
+}

api-ref/source/samples/conductor-list-response.json

@@ -0,0 +1,34 @@
+{
+  "conductors": [
+    {
+      "hostname": "compute1.localdomain",
+      "conductor_group": "",
+      "links": [
+        {
+          "href": "http://127.0.0.1:6385/v1/conductors/compute1.localdomain",
+          "rel": "self"
+        },
+        {
+          "href": "http://127.0.0.1:6385/conductors/compute1.localdomain",
+          "rel": "bookmark"
+        }
+      ],
+      "alive": false
+    },
+    {
+      "hostname": "compute2.localdomain",
+      "conductor_group": "",
+      "links": [
+        {
+          "href": "http://127.0.0.1:6385/v1/conductors/compute2.localdomain",
+          "rel": "self"
+        },
+        {
+          "href": "http://127.0.0.1:6385/conductors/compute2.localdomain",
+          "rel": "bookmark"
+        }
+      ],
+      "alive": true
+    }
+  ]
+}

api-ref/source/samples/conductor-show-response.json

@@ -0,0 +1,20 @@
+{
+  "links": [
+    {
+      "href": "http://127.0.0.1:6385/v1/conductors/compute2.localdomain",
+      "rel": "self"
+    },
+    {
+      "href": "http://127.0.0.1:6385/conductors/compute2.localdomain",
+      "rel": "bookmark"
+    }
+  ],
+  "created_at": "2018-12-05T07:03:19+00:00",
+  "hostname": "compute2.localdomain",
+  "conductor_group": "",
+  "updated_at": "2018-12-05T07:03:21+00:00",
+  "alive": true,
+  "drivers": [
+    "ipmi"
+  ]
+}

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

@@ -2,6 +2,7 @@
   "boot_interface": null,
   "chassis_uuid": null,
   "clean_step": {},
+  "conductor": "compute1.localdomain",
   "conductor_group": "group-1",
   "console_enabled": false,
   "console_interface": null,

api-ref/source/samples/node-update-driver-info-response.json

@@ -2,6 +2,7 @@
   "boot_interface": null,
   "chassis_uuid": null,
   "clean_step": {},
+  "conductor": "compute1.localdomain",
   "conductor_group": "group-1",
   "console_enabled": false,
   "console_interface": null,

api-ref/source/samples/nodes-list-details-response.json

@@ -4,6 +4,7 @@
       "boot_interface": null,
       "chassis_uuid": null,
       "clean_step": {},
+      "conductor": "compute1.localdomain",
       "conductor_group": "group-1",
       "console_enabled": false,
       "console_interface": null,
@@ -107,6 +108,7 @@
       "boot_interface": "pxe",
       "chassis_uuid": null,
       "clean_step": {},
+      "conductor": "compute1.localdomain",
       "conductor_group": "",
       "console_enabled": false,
       "console_interface": "no-console",

ironic/api/controllers/v1/versions.py

@@ -86,7 +86,7 @@ BASE_VERSION = 1
 # v1.46: Add conductor_group to the node object.
 # v1.47: Add automated_clean to the node object.
 # v1.48: Add protected to the node object.
-# v1.49: Exposes current conductor on the node object.
+# v1.49: Add conductor to the node object and /v1/conductors.
 # v1.50: Add owner to the node object.
 # v1.51: Add description to the node object.
 # v1.52: Add allocation API.