openstack/ironic
Code Issues Proposed changes

Expose conductors: api-ref

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

Story: 1724474
Task: 28064

Change-Id: I47dbea2cda1cc0ad73786fe3fe9b80850e1cf289
This commit is contained in:
Kaifeng Wang 2018-12-05 15:00:05 +08:00 committed by Julia Kreger
parent 9741aed7be
commit d4233e52a9
11 changed files with 263 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

97
api-ref/source/baremetal-api-v1-conductors.inc Normal file
View File

@ -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

16
api-ref/source/baremetal-api-v1-nodes.inc
View File

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

1
api-ref/source/index.rst
View File

@ -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

47
api-ref/source/parameters.yaml
View File

@ -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.

44
api-ref/source/samples/conductor-list-details-response.json Normal file
View File

@ -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"
]
}
]
}

34
api-ref/source/samples/conductor-list-response.json Normal file
View File

@ -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
}
]
}

20
api-ref/source/samples/conductor-show-response.json Normal file
View File

@ -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"
]
}

1
api-ref/source/samples/node-show-response.json
View File

@ -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,

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

@ -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,

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

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

2
ironic/api/controllers/v1/versions.py
View File

@ -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.