From 9672cb73d23ae140ceaf6b2412dc91a6a9402ef8 Mon Sep 17 00:00:00 2001 From: Mark Goddard Date: Mon, 11 Mar 2019 14:23:09 +0000 Subject: [PATCH] Deploy Templates: API reference Change-Id: I14716e6023dd09096e17e60c7d02230ecb3e7150 Story: 1722275 Task: 28680 --- api-ref/regenerate-samples.sh | 19 +- .../baremetal-api-v1-deploy-templates.inc | 222 ++++++++++++++++++ api-ref/source/index.rst | 1 + api-ref/source/parameters.yaml | 27 +++ .../deploy-template-create-request.json | 19 ++ .../deploy-template-create-response.json | 32 +++ .../deploy-template-detail-response.json | 36 +++ .../deploy-template-list-response.json | 18 ++ .../deploy-template-show-response.json | 32 +++ .../deploy-template-update-request.json | 7 + .../deploy-template-update-response.json | 32 +++ 11 files changed, 444 insertions(+), 1 deletion(-) create mode 100644 api-ref/source/baremetal-api-v1-deploy-templates.inc create mode 100644 api-ref/source/samples/deploy-template-create-request.json create mode 100644 api-ref/source/samples/deploy-template-create-response.json create mode 100644 api-ref/source/samples/deploy-template-detail-response.json create mode 100644 api-ref/source/samples/deploy-template-list-response.json create mode 100644 api-ref/source/samples/deploy-template-show-response.json create mode 100644 api-ref/source/samples/deploy-template-update-request.json create mode 100644 api-ref/source/samples/deploy-template-update-response.json diff --git a/api-ref/regenerate-samples.sh b/api-ref/regenerate-samples.sh index decbf7748a..6874cfb96d 100755 --- a/api-ref/regenerate-samples.sh +++ b/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 diff --git a/api-ref/source/baremetal-api-v1-deploy-templates.inc b/api-ref/source/baremetal-api-v1-deploy-templates.inc new file mode 100644 index 0000000000..96e28341e9 --- /dev/null +++ b/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 `_. + +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 diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst index c2a9d0251a..60c3faff03 100644 --- a/api-ref/source/index.rst +++ b/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 diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index c562a14aaa..36d5a01bdd 100644 --- a/api-ref/source/parameters.yaml +++ b/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. diff --git a/api-ref/source/samples/deploy-template-create-request.json b/api-ref/source/samples/deploy-template-create-request.json new file mode 100644 index 0000000000..86093c1867 --- /dev/null +++ b/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 + } + ] +} diff --git a/api-ref/source/samples/deploy-template-create-response.json b/api-ref/source/samples/deploy-template-create-response.json new file mode 100644 index 0000000000..14182cd12b --- /dev/null +++ b/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" +} diff --git a/api-ref/source/samples/deploy-template-detail-response.json b/api-ref/source/samples/deploy-template-detail-response.json new file mode 100644 index 0000000000..74975796e6 --- /dev/null +++ b/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" + } + ] +} diff --git a/api-ref/source/samples/deploy-template-list-response.json b/api-ref/source/samples/deploy-template-list-response.json new file mode 100644 index 0000000000..26fbaf85da --- /dev/null +++ b/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" + } + ] +} diff --git a/api-ref/source/samples/deploy-template-show-response.json b/api-ref/source/samples/deploy-template-show-response.json new file mode 100644 index 0000000000..14182cd12b --- /dev/null +++ b/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" +} diff --git a/api-ref/source/samples/deploy-template-update-request.json b/api-ref/source/samples/deploy-template-update-request.json new file mode 100644 index 0000000000..fd055e7029 --- /dev/null +++ b/api-ref/source/samples/deploy-template-update-request.json @@ -0,0 +1,7 @@ +[ + { + "path" : "/name", + "value" : "CUSTOM_HT_ON", + "op" : "replace" + } +] diff --git a/api-ref/source/samples/deploy-template-update-response.json b/api-ref/source/samples/deploy-template-update-response.json new file mode 100644 index 0000000000..9b8fd88bf4 --- /dev/null +++ b/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" +}