Merge "Add node traits to API reference"

api-ref/regenerate-samples.sh

@@ -11,7 +11,7 @@ fi
 OS_AUTH_TOKEN=$(openstack token issue | grep ' id ' | awk '{print $4}')
 IRONIC_URL="http://127.0.0.1:6385"
 
-IRONIC_API_VERSION="1.34"
+IRONIC_API_VERSION="1.37"
 
 export OS_AUTH_TOKEN IRONIC_URL
 
@@ -169,6 +169,10 @@ GET v1/nodes/$NID > node-show-response.json
 # Put the Node in maintenance mode, then continue doing everything else
 PUT v1/nodes/$NID/maintenance node-maintenance-request.json
 
+# Node traits
+PUT v1/nodes/$NID/traits node-set-traits-request.json
+GET v1/nodes/$NID/traits > node-traits-list-response.json
+
 ############
 # PORTGROUPS
 

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

@@ -0,0 +1,123 @@
+.. -*- rst -*-
+
+===================
+Node Traits (nodes)
+===================
+
+.. versionadded:: 1.37
+
+Node traits are used for scheduling in the Compute service, using qualitative
+attributes to influence the placement of instances to bare metal compute nodes.
+Traits specified for a node in the Bare Metal service will be registered on the
+corresponding resource provider in the Compute service's placement API.
+
+List Traits of a Node
+=====================
+
+.. rest_method:: GET /v1/nodes/{node_ident}/traits
+
+Return a list of traits for the node.
+
+Normal response code: 200
+
+Error codes: 400,401,403,404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+    - node_ident: node_ident
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+    - traits: n_traits
+
+**Example list of traits for the node:**
+
+.. literalinclude:: samples/node-traits-list-response.json
+   :language: javascript
+
+
+Set all traits of a node
+========================
+
+.. rest_method:: PUT /v1/nodes/{node_ident}/traits
+
+Set all traits of a node, replacing any existing traits.
+
+Normal response code: 204
+
+Error codes: 400,401,403,404,409
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+    - node_ident: node_ident
+    - traits: n_traits
+
+**Example request to set all traits of a Node:**
+
+.. literalinclude:: samples/node-set-traits-request.json
+
+
+Add a trait to a node
+=====================
+
+.. rest_method:: PUT /v1/nodes/{node_ident}/traits/{trait}
+
+Add a single trait to a node.
+
+Normal response code: 204
+
+Error codes: 400,401,403,404,409
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+    - node_ident: node_ident
+    - trait: trait
+
+
+Remove all traits from a node
+=============================
+
+.. rest_method:: DELETE /v1/nodes/{node_ident}/traits
+
+Normal response code: 204
+
+Error codes: 400,401,403,404,409
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+    - node_ident: node_ident
+
+
+Remove a trait from a node
+==========================
+
+Remove a single trait from a node.
+
+.. rest_method:: DELETE /v1/nodes/{node_ident}/traits/{trait}
+
+Normal response code: 204
+
+Error codes: 400,401,403,404,409
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+    - node_ident: node_ident
+    - trait: trait

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

@@ -111,7 +111,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.33.
+microversion 1.37.
 
 .. rest_parameters:: parameters.yaml
 
@@ -151,6 +151,7 @@ microversion 1.33.
     - power_interface: power_interface
     - raid_interface: raid_interface
     - storage_interface: storage_interface
+    - traits: n_traits
     - vendor_interface: vendor_interface
     - volume: n_volume
 
@@ -239,6 +240,9 @@ possible by passing in flags with the request.
 This method is particularly useful to locate the Node associated to a given
 Nova instance, eg. with a request to ``v1/nodes/detail?instance_uuid={NOVA INSTANCE UUID}``
 
+.. versionadded:: 1.37
+  Introduced the ``traits`` field.
+
 Normal response codes: 200
 
 .. TODO: add error codes
@@ -300,6 +304,7 @@ Response
     - power_interface: power_interface
     - raid_interface: raid_interface
     - storage_interface: storage_interface
+    - traits: n_traits
     - vendor_interface: vendor_interface
     - volume: n_volume
 
@@ -318,6 +323,9 @@ Shows details for a node. By default, this will return the full representation
 of the resource; an optional ``fields`` parameter can be supplied to return
 only the specified set.
 
+.. versionadded:: 1.37
+  Introduced the ``traits`` field.
+
 Normal response codes: 200
 
 .. TODO: add error codes
@@ -371,6 +379,7 @@ Response
     - power_interface: power_interface
     - raid_interface: raid_interface
     - storage_interface: storage_interface
+    - traits: n_traits
     - vendor_interface: vendor_interface
     - volume: n_volume
 
@@ -452,6 +461,7 @@ Response
     - power_interface: power_interface
     - raid_interface: raid_interface
     - storage_interface: storage_interface
+    - traits: n_traits
     - vendor_interface: vendor_interface
     - volume: n_volume
 

api-ref/source/index.rst

@@ -10,6 +10,7 @@
 .. include:: baremetal-api-v1-nodes.inc
 .. include:: baremetal-api-v1-node-management.inc
 .. include:: baremetal-api-v1-node-passthru.inc
+.. include:: baremetal-api-v1-nodes-traits.inc
 .. include:: baremetal-api-v1-nodes-vifs.inc
 .. include:: baremetal-api-v1-portgroups.inc
 .. include:: baremetal-api-v1-nodes-portgroups.inc

api-ref/source/parameters.yaml

@@ -74,6 +74,12 @@ portgroup_ident:
   in: path
   required: true
   type: string
+trait:
+  description: |
+    A single trait for this node.
+  in: path
+  required: true
+  type: string
 volume_connector_id:
   description: |
     The UUID of the Volume connector.
@@ -701,6 +707,12 @@ n_states:
   in: body
   required: true
   type: array
+n_traits:
+  description: |
+    List of traits for this node.
+  in: body
+  required: true
+  type: array
 n_vifs:
   description: |
     VIFs attached to this node.

api-ref/source/samples/api-root-response.json

@@ -9,7 +9,7 @@
     ],
     "min_version": "1.1",
     "status": "CURRENT",
-    "version": "1.33"
+    "version": "1.37"
   },
   "description": "Ironic is an OpenStack project which aims to provision baremetal machines.",
   "name": "OpenStack Ironic API",
@@ -24,7 +24,7 @@
       ],
       "min_version": "1.1",
       "status": "CURRENT",
-      "version": "1.33"
+      "version": "1.37"
     }
   ]
 }

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

@@ -77,6 +77,7 @@
   "target_power_state": null,
   "target_provision_state": null,
   "target_raid_config": {},
+  "traits": [],
   "updated_at": null,
   "uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
   "vendor_interface": null,

api-ref/source/samples/node-set-traits-request.json

@@ -0,0 +1,6 @@
+{
+  "traits": [
+    "CUSTOM_TRAIT1",
+    "HW_CPU_X86_VMX"
+  ]
+}

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

@@ -79,6 +79,7 @@
   "target_power_state": null,
   "target_provision_state": null,
   "target_raid_config": {},
+  "traits": [],
   "updated_at": "2016-08-18T22:28:49.653974+00:00",
   "uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
   "vendor_interface": null,

api-ref/source/samples/node-traits-list-response.json

@@ -0,0 +1,6 @@
+{
+  "traits": [
+    "CUSTOM_TRAIT1",
+    "HW_CPU_X86_VMX"
+  ]
+}

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

@@ -81,6 +81,10 @@
   "target_power_state": null,
   "target_provision_state": null,
   "target_raid_config": {},
+  "traits": [
+    "CUSTOM_TRAIT1",
+    "HW_CPU_X86_VMX"
+  ],
   "updated_at": "2016-08-18T22:28:49.653974+00:00",
   "uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
   "vendor_interface": null,

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

@@ -81,6 +81,7 @@
       "target_power_state": null,
       "target_provision_state": null,
       "target_raid_config": {},
+      "traits": [],
       "updated_at": "2016-08-18T22:28:49.653974+00:00",
       "uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
       "vendor_interface": null,
@@ -174,6 +175,7 @@
       "target_power_state": null,
       "target_provision_state": null,
       "target_raid_config": {},
+      "traits": [],
       "updated_at": null,
       "uuid": "2b045129-a906-46af-bc1a-092b294b3428",
       "vendor_interface": "no-vendor",