Deploy Templates: API reference

Change-Id: I14716e6023dd09096e17e60c7d02230ecb3e7150
Story: 1722275
Task: 28680

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.53"
+IRONIC_API_VERSION="1.55"
 
 export OS_AUTH_TOKEN IRONIC_URL
 
@@ -28,6 +28,7 @@ DOC_CREATED_AT="2016-08-18T22:28:48.643434+11:11"
 DOC_UPDATED_AT="2016-08-18T22:28:49.653974+00:00"
 DOC_IRONIC_CONDUCTOR_HOSTNAME="897ab1dad809"
 DOC_ALLOCATION_UUID="3bf138ba-6d71-44e7-b6a1-ca9cac17103e"
+DOC_DEPLOY_TEMPLATE_UUID="bbb45f41-d4bc-4307-8d1d-32f95ce1e920"
 
 function GET {
     # GET $RESOURCE
@@ -326,6 +327,21 @@ GET v1/nodes/$NID/volume/connectors?detail=True > node-volume-connector-detail-r
 GET v1/nodes/$NID/volume/targets > node-volume-target-list-response.json
 GET v1/nodes/$NID/volume/targets?detail=True > node-volume-target-detail-response.json
 
+##################
+# DEPLOY TEMPLATES
+
+POST v1/deploy_templates deploy-template-create-request.json > deploy-template-create-response.json
+DTID=$(cat deploy-template-create-response.json | grep '"uuid"' | sed 's/.*"\([0-9a-f\-]*\)",*/\1/')
+if [ "$DTID" == "" ]; then
+    exit 1
+else
+    echo "Deploy template created. UUID: $DTID"
+fi
+
+GET v1/deploy_templates > deploy-template-list-response.json
+GET v1/deploy_templates?detail=True > deploy-template-detail-response.json
+GET v1/deploy_templates/$DTID > deploy-template-show-response.json
+PATCH v1/deploy_templates/$DTID deploy-template-update-request.json > deploy-template-update-response.json
 
 #####################
 # Replace automatically generated UUIDs by already used in documentation
@@ -338,6 +354,7 @@ sed -i "s/$PGID/$DOC_PORTGROUP_UUID/" *.json
 sed -i "s/$VCID/$DOC_VOL_CONNECTOR_UUID/" *.json
 sed -i "s/$VTID/$DOC_VOL_TARGET_UUID/" *.json
 sed -i "s/$AID/$DOC_ALLOCATION_UUID/" *.json
+sed -i "s/$DTID/$DOC_DEPLOY_TEMPLATE_UUID/" *.json
 sed -i "s/$(hostname)/$DOC_IRONIC_CONDUCTOR_HOSTNAME/" *.json
 sed -i "s/created_at\": \".*\"/created_at\": \"$DOC_CREATED_AT\"/" *.json
 sed -i "s/updated_at\": \".*\"/updated_at\": \"$DOC_UPDATED_AT\"/" *.json

api-ref/source/baremetal-api-v1-deploy-templates.inc

@@ -0,0 +1,222 @@
+.. -*- rst -*-
+
+===================================
+Deploy Templates (deploy_templates)
+===================================
+
+The Deploy Template resource represents a collection of Deploy Steps that may
+be executed during deployment of a node. A deploy template is matched for a
+node if at the time of deployment, the template's name matches a trait in the
+node's ``instance_info.traits``.
+
+.. versionadded:: 1.55
+    Deploy Template API was introduced.
+
+Create Deploy Template
+======================
+
+.. rest_method::  POST /v1/deploy_templates
+
+Creates a deploy template.
+
+.. versionadded:: 1.55
+    Deploy Template API was introduced.
+
+Normal response codes: 201
+
+Error response codes: 400, 401, 403, 409
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - name: deploy_template_name
+   - steps: deploy_template_steps
+   - uuid: req_uuid
+   - extra: req_extra
+
+Request Example
+---------------
+
+.. literalinclude:: samples/deploy-template-create-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - uuid: uuid
+   - name: deploy_template_name
+   - steps: deploy_template_steps
+   - extra: extra
+   - created_at: created_at
+   - updated_at: updated_at
+   - links: links
+
+Response Example
+----------------
+
+.. literalinclude:: samples/deploy-template-create-response.json
+   :language: javascript
+
+List Deploy Templates
+=====================
+
+.. rest_method::  GET /v1/deploy_templates
+
+Lists all deploy templates.
+
+.. versionadded:: 1.55
+    Deploy Template API was introduced.
+
+Normal response codes: 200
+
+Error response codes: 400, 401, 403, 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - fields: fields
+   - limit: limit
+   - marker: marker
+   - sort_dir: sort_dir
+   - sort_key: sort_key
+   - detail: detail
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - uuid: uuid
+   - name: deploy_template_name
+   - steps: deploy_template_steps
+   - extra: extra
+   - created_at: created_at
+   - updated_at: updated_at
+   - links: links
+
+Response Example
+----------------
+
+**Example deploy template list response:**
+
+.. literalinclude:: samples/deploy-template-list-response.json
+   :language: javascript
+
+**Example detailed deploy template list response:**
+
+.. literalinclude:: samples/deploy-template-detail-response.json
+   :language: javascript
+
+Show Deploy Template Details
+============================
+
+.. rest_method::  GET /v1/deploy_templates/{deploy_template_id}
+
+Shows details for a deploy template.
+
+.. versionadded:: 1.55
+    Deploy Template API was introduced.
+
+Normal response codes: 200
+
+Error response codes: 400, 401, 403, 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - fields: fields
+   - deploy_template_id: deploy_template_ident
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - uuid: uuid
+   - name: deploy_template_name
+   - steps: deploy_template_steps
+   - extra: extra
+   - created_at: created_at
+   - updated_at: updated_at
+   - links: links
+
+Response Example
+----------------
+
+.. literalinclude:: samples/deploy-template-show-response.json
+   :language: javascript
+
+Update a Deploy Template
+========================
+
+.. rest_method:: PATCH /v1/deploy_templates/{deploy_template_id}
+
+Update a deploy template.
+
+.. versionadded:: 1.55
+    Deploy Template API was introduced.
+
+Normal response code: 200
+
+Error response codes: 400, 401, 403, 404, 409
+
+Request
+-------
+
+The BODY of the PATCH request must be a JSON PATCH document, adhering to
+`RFC 6902 <https://tools.ietf.org/html/rfc6902>`_.
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+    - deploy_template_id: deploy_template_ident
+
+.. literalinclude:: samples/deploy-template-update-request.json
+   :language: javascript
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+   - uuid: uuid
+   - name: deploy_template_name
+   - steps: deploy_template_steps
+   - extra: extra
+   - created_at: created_at
+   - updated_at: updated_at
+   - links: links
+
+.. literalinclude:: samples/deploy-template-update-response.json
+   :language: javascript
+
+Delete Deploy Template
+======================
+
+.. rest_method::  DELETE /v1/deploy_template/{deploy_template_id}
+
+Deletes a deploy template.
+
+.. versionadded:: 1.55
+    Deploy Template API was introduced.
+
+Normal response codes: 204
+
+Error response codes: 400, 401, 403, 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - deploy_template_id: deploy_template_ident

api-ref/source/index.rst

@@ -25,6 +25,7 @@
 .. include:: baremetal-api-v1-conductors.inc
 .. include:: baremetal-api-v1-allocation.inc
 .. include:: baremetal-api-v1-node-allocation.inc
+.. include:: baremetal-api-v1-deploy-templates.inc
 .. NOTE(dtantsur): keep chassis close to the end since it's semi-deprecated
 .. include:: baremetal-api-v1-chassis.inc
 .. NOTE(dtantsur): keep misc last, since it covers internal API

api-ref/source/parameters.yaml

@@ -56,6 +56,12 @@ chassis_ident:
   in: path
   required: true
   type: string
+deploy_template_ident:
+  description: |
+    The UUID or name of the deploy template.
+  in: path
+  required: true
+  type: string
 driver_ident:
   description: |
     The name of the driver.
@@ -681,6 +687,27 @@ deploy_step:
   in: body
   required: false
   type: string
+deploy_template_name:
+  description: |
+    The unique name of the deploy template.
+  in: body
+  required: true
+  type: string
+deploy_template_steps:
+  description: |
+    The deploy steps of the deploy template. Must be a list containing at least
+    one deploy step.
+
+    A deploy step is a dictionary with required keys ``interface``, ``step``,
+    ``args``, and ``priority``.  The value for ``interface`` is the name of the
+    driver interface.  The value for ``step`` is the name of the deploy step
+    method on the driver interface. The value for ``args`` is a dictionary of
+    arguments that are passed to the deploy step method. The value for
+    ``priority`` is a non-negative integer priority for the step. A value of
+    ``0`` for ``priority`` will disable that step.
+  in: body
+  required: true
+  type: array
 description:
   description: |
     Descriptive text about the Ironic service.

api-ref/source/samples/deploy-template-create-request.json

@@ -0,0 +1,19 @@
+{
+    "extra": {},
+    "name": "CUSTOM_HYPERTHREADING_ON",
+    "steps": [
+        {
+            "interface": "bios",
+            "step": "apply_configuration",
+            "args": {
+                "settings": [
+                    {
+                        "name": "LogicalProc",
+                        "value": "Enabled"
+                    }
+                ]
+            },
+            "priority": 150
+        }
+    ]
+}

api-ref/source/samples/deploy-template-create-response.json

@@ -0,0 +1,32 @@
+{
+  "created_at": "2016-08-18T22:28:48.643434+11:11",
+  "extra": {},
+  "links": [
+    {
+      "href": "http://10.60.253.180:6385/v1/deploy_templates/bbb45f41-d4bc-4307-8d1d-32f95ce1e920",
+      "rel": "self"
+    },
+    {
+      "href": "http://10.60.253.180:6385/deploy_templates/bbb45f41-d4bc-4307-8d1d-32f95ce1e920",
+      "rel": "bookmark"
+    }
+  ],
+  "name": "CUSTOM_HYPERTHREADING_ON",
+  "steps": [
+    {
+      "args": {
+        "settings": [
+          {
+            "name": "LogicalProc",
+            "value": "Enabled"
+          }
+        ]
+      },
+      "interface": "bios",
+      "priority": 150,
+      "step": "apply_configuration"
+    }
+  ],
+  "updated_at": null,
+  "uuid": "bbb45f41-d4bc-4307-8d1d-32f95ce1e920"
+}

api-ref/source/samples/deploy-template-detail-response.json

@@ -0,0 +1,36 @@
+{
+  "deploy_templates": [
+    {
+      "created_at": "2016-08-18T22:28:48.643434+11:11",
+      "extra": {},
+      "links": [
+        {
+          "href": "http://10.60.253.180:6385/v1/deploy_templates/bbb45f41-d4bc-4307-8d1d-32f95ce1e920",
+          "rel": "self"
+        },
+        {
+          "href": "http://10.60.253.180:6385/deploy_templates/bbb45f41-d4bc-4307-8d1d-32f95ce1e920",
+          "rel": "bookmark"
+        }
+      ],
+      "name": "CUSTOM_HYPERTHREADING_ON",
+      "steps": [
+        {
+          "args": {
+            "settings": [
+              {
+                "name": "LogicalProc",
+                "value": "Enabled"
+              }
+            ]
+          },
+          "interface": "bios",
+          "priority": 150,
+          "step": "apply_configuration"
+        }
+      ],
+      "updated_at": null,
+      "uuid": "bbb45f41-d4bc-4307-8d1d-32f95ce1e920"
+    }
+  ]
+}

api-ref/source/samples/deploy-template-list-response.json

@@ -0,0 +1,18 @@
+{
+  "deploy_templates": [
+    {
+      "links": [
+        {
+          "href": "http://10.60.253.180:6385/v1/deploy_templates/bbb45f41-d4bc-4307-8d1d-32f95ce1e920",
+          "rel": "self"
+        },
+        {
+          "href": "http://10.60.253.180:6385/deploy_templates/bbb45f41-d4bc-4307-8d1d-32f95ce1e920",
+          "rel": "bookmark"
+        }
+      ],
+      "name": "CUSTOM_HYPERTHREADING_ON",
+      "uuid": "bbb45f41-d4bc-4307-8d1d-32f95ce1e920"
+    }
+  ]
+}

api-ref/source/samples/deploy-template-show-response.json

@@ -0,0 +1,32 @@
+{
+  "created_at": "2016-08-18T22:28:48.643434+11:11",
+  "extra": {},
+  "links": [
+    {
+      "href": "http://10.60.253.180:6385/v1/deploy_templates/bbb45f41-d4bc-4307-8d1d-32f95ce1e920",
+      "rel": "self"
+    },
+    {
+      "href": "http://10.60.253.180:6385/deploy_templates/bbb45f41-d4bc-4307-8d1d-32f95ce1e920",
+      "rel": "bookmark"
+    }
+  ],
+  "name": "CUSTOM_HYPERTHREADING_ON",
+  "steps": [
+    {
+      "args": {
+        "settings": [
+          {
+            "name": "LogicalProc",
+            "value": "Enabled"
+          }
+        ]
+      },
+      "interface": "bios",
+      "priority": 150,
+      "step": "apply_configuration"
+    }
+  ],
+  "updated_at": null,
+  "uuid": "bbb45f41-d4bc-4307-8d1d-32f95ce1e920"
+}

api-ref/source/samples/deploy-template-update-request.json

@@ -0,0 +1,7 @@
+[
+   {
+      "path" : "/name",
+      "value" : "CUSTOM_HT_ON",
+      "op" : "replace"
+   }
+]

api-ref/source/samples/deploy-template-update-response.json

@@ -0,0 +1,32 @@
+{
+  "created_at": "2016-08-18T22:28:48.643434+11:11",
+  "extra": {},
+  "links": [
+    {
+      "href": "http://10.60.253.180:6385/v1/deploy_templates/bbb45f41-d4bc-4307-8d1d-32f95ce1e920",
+      "rel": "self"
+    },
+    {
+      "href": "http://10.60.253.180:6385/deploy_templates/bbb45f41-d4bc-4307-8d1d-32f95ce1e920",
+      "rel": "bookmark"
+    }
+  ],
+  "name": "CUSTOM_HT_ON",
+  "steps": [
+    {
+      "args": {
+        "settings": [
+          {
+            "name": "LogicalProc",
+            "value": "Enabled"
+          }
+        ]
+      },
+      "interface": "bios",
+      "priority": 150,
+      "step": "apply_configuration"
+    }
+  ],
+  "updated_at": "2016-08-18T22:28:49.653974+00:00",
+  "uuid": "bbb45f41-d4bc-4307-8d1d-32f95ce1e920"
+}