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
2018-12-05 15:00:05 +08:00 · 2018-12-05 15:00:05 +08:00 · d4233e52a9
parent 9741aed7be
commit d4233e52a9
11 changed files with 263 additions and 2 deletions
--- a/api-ref/source/baremetal-api-v1-conductors.inc
+++ b/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
--- a/api-ref/source/baremetal-api-v1-nodes.inc
+++ b/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:**

--- a/api-ref/source/index.rst
+++ b/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

--- a/api-ref/source/parameters.yaml
+++ b/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.
--- a/api-ref/source/samples/conductor-list-details-response.json
+++ b/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"
+      ]
+    }
+  ]
+}
--- a/api-ref/source/samples/conductor-list-response.json
+++ b/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
+    }
+  ]
+}
--- a/api-ref/source/samples/conductor-show-response.json
+++ b/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"
+  ]
+}
--- a/api-ref/source/samples/node-show-response.json
+++ b/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,
--- a/api-ref/source/samples/node-update-driver-info-response.json
+++ b/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,
--- a/api-ref/source/samples/nodes-list-details-response.json
+++ b/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",
--- a/ironic/api/controllers/v1/versions.py
+++ b/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.