From d87eca863ac4f7470a737a40dd4b3f1b92eda053 Mon Sep 17 00:00:00 2001 From: "Vanathi.Selvaraju" Date: Wed, 26 Mar 2025 15:29:47 -0400 Subject: [PATCH] VIM Rest API updates for kubernetes and software upgrade This commit updates documentation, below are the updates done in kubernetes and software deploy upgrade strategy. 1. Kubernetes upgrade section is added 2. Updated missing request and response parameters 3. Details of the mandatory and recommended parameters added 4. System health API URL is modified and also removed API from few places as its taken care as part of deploy precheck. TEST PLAN PASSED: Converted into html format(tox -e api-ref) PASSED: Converted into html format(sphinx-build) Change-Id: Ic52fa8f5f1c5839e8d9bb4061bd64ee52ad9eee7 Signed-off-by: Vanathi.Selvaraju --- api-ref/source/api-ref-nfv-vim-v1.rst | 1557 +++++++++++++++++++++---- 1 file changed, 1351 insertions(+), 206 deletions(-) diff --git a/api-ref/source/api-ref-nfv-vim-v1.rst b/api-ref/source/api-ref-nfv-vim-v1.rst index 988fcd8e..0fbab7c4 100644 --- a/api-ref/source/api-ref-nfv-vim-v1.rst +++ b/api-ref/source/api-ref-nfv-vim-v1.rst @@ -534,9 +534,9 @@ plan, automated software deployment procedure contains a number of parameters for customizing the particular behavior of the software deploy orchestration. -************************************************************************** -Shows detailed information about the current sw-deploy strategy (AIO-DX) -************************************************************************** +****************************************************************** +Shows detailed information about the current sw-deploy strategy +****************************************************************** .. rest_method:: GET /api/orchestration/sw-upgrade/strategy @@ -555,6 +555,52 @@ This operation does not accept a request body. serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413), itemNotFound (404) +**Response parameters** + +The details of the strategy can be checked using below response parameter. + +* state - 'building or applying or aborting' or 'ready-to-apply or 'applied' + or 'aborted' or 'build-failed or apply-failed or abort-failed'. +* result - 'success' or 'failed' or 'aborted'. +* reason and response - It's empty "" on success and on failure it's updated + with details of error. + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "name", "plain", "xsd:string", "The current strategy name." + "release", "plain", "xsd:string", "The release identification name." + "controller-apply-type", "plain", "xsd:string", "Apply type of controller host." + "storage-apply-type", "plain", "xsd:string", "Apply type of storage host." + "worker-apply-type", "plain", "xsd:string", "Apply type of worker host." + "state", "plain", "xsd:string", "The current strategy state." + "current-phase", "plain", "xsd:string", "The current ongoing phase." + "stage-name", "plain", "xsd:string", "The current stage of execution in the current phase." + "step-name", "plain", "xsd:string", "The current step of execution in the current stage." + "completion-percentage", "plain", "xsd:integer", "The completion percentage of strategy." + "result", "plain", "xsd:string", "The result of current strategy." + "reason", "plain", "xsd:string", "The reason for success/failure of the current phase." + "response", "plain", "xsd:string", "This displays the detailed error message of the + reason for failure,if any." + +**Note** + +* Phase - This refers to 'create or apply or abort' phase of strategy +* Stage - This points to various stages at each phase. + Example; 'sw-upgrade start deploy', 'sw-upgrade deploy host' +* Step - This refers to different steps executed in each stage. + Example; In 'sw-upgrade deploy host' stage, there are different steps like lock-hosts, + upgrade-hosts, system-stabilize, unlock-hosts. + +When using this API to monitor the progress or status of a create, apply or abort +operation, wait for the 'completion-percentage' parameter to reach 100%. +The 'completion-percentage' is 100% only in success case. +Then, use the 'result' parameter to determine whether it indicates +'success' or 'failure'. In the failure scenario, the 'reason' and 'response' +parameters provide more detailed information related to the failure. + + **Response body example** :: @@ -573,17 +619,20 @@ forbidden (403), badMethod (405), overLimit (413), itemNotFound (404) "end-date-time": "", "phase-name": "apply", "completion-percentage": 100, + "state": "applying", "total-stages": 3, "stop-at-stage": 0, "result": "initial", "timeout": 0, "reason": "", + "response": "", "inprogress": false, "stages": [ { "start-date-time": "", "end-date-time": "", "stage-id": 0, + "stage-name": "sw-upgrade-query", "reason": "", "current-step": 0, "steps": [ @@ -1026,7 +1075,7 @@ Creates a sw-deploy strategy worker hosts to upgrade in parallel; only applicable if ``worker-apply-type = parallel``. Default value is ``2``." "alarm-restrictions (Optional)", "plain", "xsd:string", "The strictness of alarm checks: - ``strict`` or ``relaxed``." + ``strict`` or ``relaxed`` (recommended option)." "release", "plain", "xsd:string", "The release identification name." "rollback", "plain", "xsd:bool", "The flag that indicates this is a rollback action." "delete", "plain", "xsd:bool", "The flag that indicates that deployment will be marked complete." @@ -1049,7 +1098,7 @@ Creates a sw-deploy strategy **Response** **Normal response codes** - + 200 **Error response codes** @@ -1057,6 +1106,36 @@ Creates a sw-deploy strategy serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413) +**Response parameters** + +The "sw-deploy create strategy" request starts the creation process of the strategy, +and returns a response to indicate the status of the creation process. +E.g. typically after initially starting the create. + +* state ='building'. +* current-phase ='build' + +Use the sw-deploy get strategy request to monitor the progress and status of the create. + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "name", "plain", "xsd:string", "The current strategy name." + "release", "plain", "xsd:string", "The release identification name." + "controller-apply-type", "plain", "xsd:string", "Apply type of controller host." + "storage-apply-type", "plain", "xsd:string", "Apply type of storage host." + "worker-apply-type", "plain", "xsd:string", "Apply type of worker host." + "state", "plain", "xsd:string", "The current strategy state." + "current-phase", "plain", "xsd:string", "The current ongoing phase." + "stage-name", "plain", "xsd:string", "The current stage of execution in the current phase." + "step-name", "plain", "xsd:string", "The current step of execution in the current stage." + "completion-percentage", "plain", "xsd:integer", "The completion percentage of strategy." + "result", "plain", "xsd:string", "The result of current strategy." + "reason", "plain", "xsd:string", "The reason for success/failure of the current phase." + "response", "plain", "xsd:string", "This displays the detailed error message of the + reason for failure,if any." + **Response body example** :: @@ -1081,7 +1160,7 @@ forbidden (403), badMethod (405), overLimit (413) "result": "initial", "timeout": 0, "reason": "", - "inprogress": false, + "inprogress": true, "stages": [], "current-stage": 0, }, @@ -1198,23 +1277,33 @@ Applies or aborts a sw-deploy strategy **Request body parameters** +These parameters are common for both apply and abort strategy. + .. csv-table:: :header: "Parameter", "Style", "Type", "Description" :widths: 20, 20, 20, 60 - "action", "plain", "xsd:string", "The action to take: ``apply-all``, ``apply-stage``, - ``abort`` or ``abort-stage``." - "stage-id (Optional)", "plain", "xsd:string", "The stage-id to apply or abort. + "action", "plain", "xsd:string", "The action to take: ``apply-all``, + ``apply-stage``,``abort`` or ``abort-stage``." + "stage-id", "plain", "xsd:string", "The stage-id to apply or abort. Only used with ``apply-stage`` or ``abort-stage`` actions." +**Note** + +* stage-id - This is used to apply or abort a particular stage in the execution flow. + Each stage has a number specified. This can be identified from the response + parameter 'stage-id' which can be used to apply or abort a specific stage. +* apply-all or abort-all - This is recommended option, as it takes care of applying + or aborting all the required stages." + **Request body example** - + :: { "action": "apply-all" } - + **Response** **Normal response codes** @@ -1226,6 +1315,36 @@ Applies or aborts a sw-deploy strategy serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413) +**Response parameters** + +The "sw-deploy" strategy "apply" or "abort" request starts the apply or abort process, +and returns a response to indicate the current status of the apply or abort process. +E.g. typically after initially starting the create. + +* state = 'applying' or 'aborting'. +* current-phase ='apply' or 'abort' + +Use the sw-deploy get strategy request to monitor the progress and status of the apply. + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "name", "plain", "xsd:string", "The current strategy name." + "release", "plain", "xsd:string", "The release identification name." + "controller-apply-type", "plain", "xsd:string", "Apply type of controller host." + "storage-apply-type", "plain", "xsd:string", "Apply type of storage host." + "worker-apply-type", "plain", "xsd:string", "Apply type of worker host." + "state", "plain", "xsd:string", "The current strategy state." + "current-phase", "plain", "xsd:string", "The current ongoing phase." + "stage-name", "plain", "xsd:string", "The current stage of execution in the current phase." + "step-name", "plain", "xsd:string", "The current step of execution in the current stage." + "completion-percentage", "plain", "xsd:integer", "The completion percentage of strategy." + "result", "plain", "xsd:string", "The result of current strategy." + "reason", "plain", "xsd:string", "The reason for success/failure of the current phase." + "response", "plain", "xsd:string", "This displays the detailed error message of the + reason for failure,if any." + **Response body example** :: @@ -1594,6 +1713,490 @@ forbidden (403), badMethod (405), overLimit (413) } } +---------------------------- +Kubernetes Upgrade Strategy +---------------------------- + +Kubernetes upgrade orchestration is performed with a kube upgrade orchestration +strategy, or plan, for the automated upgrade of kubernetes components to the +target version. A kube-upgrade strategy is capable of upgrading multiple versions +at once in simplex system configuration. In other system configurations, +kube-upgrade strategy can upgrade only single version at a time. +Kubernetes upgrade contains a number of parameters for customizing the particular +behavior of the kubernetes upgrade orchestration. + +********************************************************** +Shows detailed information about the kubernetes strategy +********************************************************** + +.. rest_method:: GET /api/orchestration/kube-upgrade/strategy + +**Request** + +This operation does not accept a request body. + +**Response** + +**Normal response codes** + +200 + +**Error response codes** + +serviceUnavailable (503), badRequest (400), unauthorized (401), +forbidden (403), badMethod (405), overLimit (413), itemNotFound (404) + +**Response parameters** + +The details of the strategy can be checked using below response parameter. + +* state - 'building or applying or aborting' or 'ready-to-apply or applied + or aborted' or 'build-failed or apply-failed or abort-failed'. +* result - 'success' or 'failed' or 'aborted'. +* reason and response - It's empty "" on success and on failure it's updated + with details of error. + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "name", "plain", "xsd:string", "The current strategy name." + "controller-apply-type", "plain", "xsd:string", "Apply type of controller host." + "storage-apply-type", "plain", "xsd:string", "Apply type of storage host." + "worker-apply-type", "plain", "xsd:string", "Apply type of worker host." + "state", "plain", "xsd:string", "The current strategy state." + "current-phase", "plain", "xsd:string", "The current ongoing phase." + "stage-name", "plain", "xsd:string", "The current stage of execution in the current phase." + "step-name", "plain", "xsd:string", "The current step of execution in the current stage." + "completion-percentage", "plain", "xsd:integer", "The completion percentage of strategy." + "result", "plain", "xsd:string", "The result of current strategy." + "reason", "plain", "xsd:string", "The reason for success/failure of the current phase." + + +**Response body example** +:: + + { + "strategy": { + "controller-apply-type": "ignore", + "swift-apply-type": "ignore", + "storage-apply-type": "ignore", + "worker-apply-type": "serial", + "state": "ready-to-apply", + "default-instance-action": "stop-start", + "max-parallel-worker-hosts": 2, + "alarm-restrictions": "strict", + "current-phase-completion-percentage": 100, + "uuid": "5dd16d94-dfc5-4029-bfcb-d815e7c2dc3d", + "name": "kube-upgrade", + "current-phase": "build", + "build-phase": { + "phase-name": "build", + "current-stage": 1, + "total-stages": 1, + "completion-percentage": 100, + "start-date-time": "2025-03-26 13:31:02", + "end-date-time": "2025-03-26 13:31:02" + "stop-at-stage": 1, + "result": "success", + "timeout": 982, + "reason": "", + "inprogress": false, + "stages": [ + { + "start-date-time": "", + "end-date-time": "", + "stage-id": 0, + "stage-name": "kube-upgrade-query", + "reason": "", + "current-step": 0, + "steps": [ + { + "start-date-time": "", + "end-date-time": "", + "timeout": 60, + "step-id": 0, + "step-name": "query-kube-versions", + "result": "initial", + "reason": "" + }, + { + "start-date-time": "", + "end-date-time": "", + "timeout": 60, + "step-id": 0, + "entity-uuids": [], + "step-name": "query-kube-upgrade", + "result": "initial", + "reason": "" + }, + { + "start-date-time": "", + "end-date-time": "", + "timeout": 200, + "step-id": 0, + "step-name": "query-kube-host-upgrade", + result": "initial", + "reason": "" + }] + } + } + +This operation does not accept a request body. + +******************************** +Creates a kube-upgrade strategy +******************************** + +.. rest_method:: POST /api/orchestration/kube-upgrade/strategy + +**Request** + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "controller-apply-type", "plain", "xsd:string", "The apply type for controller hosts: ``ignore``." + "storage-apply-type", "plain", "xsd:string", "The apply type for storage hosts: ``ignore``." + "worker-apply-type", "plain", "xsd:string", "The apply type for worker hosts: ``serial``, + ``parallel`` or ``ignore``." + "max-parallel-worker-hosts (Optional)", "plain", "xsd:integer", "The maximum number of + worker hosts to patch in parallel; only applicable if ``worker-apply-type = parallel``. + Default value is ``2``." + "default-instance-action", "plain", "xsd:string", "The default instance action: + ``stop-start`` or ``migrate``." + "alarm-restrictions (Optional)", "plain", "xsd:string", "The strictness of alarm checks: + ``strict`` or ``relaxed`` (recommended option)" + "to-version (mandatory)", "plain", "xsd:string", "The kubernetes version to upgrade" + +**Request body example** + +:: + + { + "controller-apply-type": "serial", + "storage-apply-type": "serial", + "worker-apply-type": "serial", + "default-instance-action": "stop-start", + "alarm-restrictions": "relaxed", + "to-version": "v1.31.5" + } + +**Response** + +**Normal response codes** + +200 + +**Error response codes** + +serviceUnavailable (503), badRequest (400), unauthorized (401), +forbidden (403), badMethod (405), overLimit (413) + +**Response parameters** + +The kubernetes create strategy request starts the creation process of the strategy, +and returns a response to indicate the status of the creation process. +E.g. typically after initially starting the create. + +* state ='building'. +* current-phase ='build' + +Use the kubernetes get strategy request to monitor the progress and status of the create. + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "name", "plain", "xsd:string", "The current strategy name." + "controller-apply-type", "plain", "xsd:string", "Apply type of controller host." + "storage-apply-type", "plain", "xsd:string", "Apply type of storage host." + "worker-apply-type", "plain", "xsd:string", "Apply type of worker host." + "state", "plain", "xsd:string", "The current strategy state." + "current-phase", "plain", "xsd:string", "The current ongoing phase." + "stage-name", "plain", "xsd:string", "The current stage of execution in the current phase." + "step-name", "plain", "xsd:string", "The current step of execution in the current stage." + "completion-percentage", "plain", "xsd:integer", "The completion percentage of strategy." + "result", "plain", "xsd:string", "The result of current strategy." + "reason", "plain", "xsd:string", "The reason for success/failure of the current phase." + +**Response body example** + +:: + + { + "strategy": { + "controller-apply-type": "ignore", + "swift-apply-type": "ignore", + "storage-apply-type": "ignore", + "worker-apply-type": "serial", + "state": "ready-to-apply", + "default-instance-action": "stop-start", + "max-parallel-worker-hosts": 2, + "alarm-restrictions": "strict", + "current-phase-completion-percentage": 100, + "uuid": "5dd16d94-dfc5-4029-bfcb-d815e7c2dc3d", + "name": "kube-upgrade", + "current-phase": "build", + "build-phase": { + "phase-name": "build", + "current-stage": 1, + "total-stages": 1, + "completion-percentage": 100, + "start-date-time": "2025-03-26 13:31:02", + "end-date-time": "2025-03-26 13:31:02" + "stop-at-stage": 1, + "result": "success", + "timeout": 982, + "reason": "", + "inprogress": false, + "stages": [ + { + "start-date-time": "", + "end-date-time": "", + "stage-id": 0, + "reason": "", + "current-step": 0, + "steps": [ + { + "start-date-time": "", + "end-date-time": "", + "timeout": 60, + "step-id": 0, + "step-name": "query-kube-versions", + "result": "initial", + "reason": "" + }, + { + "start-date-time": "", + "end-date-time": "", + "timeout": 60, + "step-id": 0, + "entity-uuids": [], + "step-name": "query-kube-upgrade", + "result": "initial", + "reason": "" + }] + } + "apply-phase": { + "start-date-time": "", + "end-date-time": "", + "phase-name": "apply", + "completion-percentage": 100, + "total-stages": 0, + "stop-at-stage": 0, + "result": "initial", + "timeout": 0, + "reason": "", + "inprogress": false, + "stages": [], + "current-stage": 0 + }, + "abort-phase": { + "start-date-time": "", + "end-date-time": "", + "phase-name": "abort", + "completion-percentage": 100, + "total-stages": 0, + "stop-at-stage": 0, + "result": "initial", + "timeout": 0, + "reason": "", + "inprogress":false, + "stages": [], + "current-stage": 0 + } + } + + +******************************************* +Deletes the current kube-upgrade strategy +******************************************* + +.. rest_method:: DELETE /api/orchestration/kube-upgrade/strategy + +**Request** + +This operation does not accept a request body. + +**Response** + +**Normal response codes** + +204 + +**Response body example** + +:: + + { + } + +**************************************** +Applies or aborts kube-upgrade strategy +**************************************** + +.. rest_method:: POST /api/orchestration/kube-upgrade/strategy/actions + +**Request** + +**Request parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "action", "plain", "xsd:string", "The action to take: ``apply-all``, ``apply-stage``, + ``abort``or ``abort-stage``." + "stage-id (Optional)", "plain", "xsd:string", "The stage-id to apply or abort. + Only used with ``apply-stage`` or ``abort-stage`` actions." + +**Note** + +* stage-id - This is used to apply or abort a particular stage in the execution flow. + Each stage has a number specified. This can be identified from the response parameter + 'stage-id' which can be used to apply or abort a specific stage. +* apply-all or abort-all - This is recommended option, as it takes care of applying + or aborting all the required stages." + +**Request body example** + +:: + + { + "action": "apply-all" + } + +**Response** + +**Normal response codes** + +200 + +**Error response codes** + +serviceUnavailable (503), badRequest (400), unauthorized (401), +forbidden (403), badMethod (405), overLimit (413), itemNotFound (404) + +**Response parameters** + +The kubernetes strategy apply or abort request starts the apply or abort process, +and returns a response to indicate the current status of the apply or abort process. +E.g. typically after initially starting the create. + +* state = 'applying' or 'aborting'. +* current-phase ='apply' or 'abort' + +Use the kubernetes get strategy request to monitor the progress and status of Apply strategy. + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "name", "plain", "xsd:string", "The current strategy name." + "controller-apply-type", "plain", "xsd:string", "Apply type of controller host." + "storage-apply-type", "plain", "xsd:string", "Apply type of storage host." + "worker-apply-type", "plain", "xsd:string", "Apply type of worker host." + "state", "plain", "xsd:string", "The current strategy state." + "current-phase", "plain", "xsd:string", "The current ongoing phase." + "stage-name", "plain", "xsd:string", "The current stage of execution in the current phase." + "step-name", "plain", "xsd:string", "The current step of execution in the current stage." + "completion-percentage", "plain", "xsd:integer", "The completion percentage of strategy." + "result", "plain", "xsd:string", "The result of current strategy." + "reason", "plain", "xsd:string", "The reason for success/failure of the current phase." + +**Response body example** + +:: + + { + "strategy": { + "controller-apply-type": "ignore", + "swift-apply-type": "ignore", + "storage-apply-type": "ignore", + "worker-apply-type": "serial", + "state": "ready-to-apply", + "default-instance-action": "stop-start", + "max-parallel-worker-hosts": 2, + "alarm-restrictions": "strict", + "current-phase-completion-percentage": 100, + "uuid": "5dd16d94-dfc5-4029-bfcb-d815e7c2dc3d", + "name": "kube-upgrade", + "current-phase": "build", + "build-phase": { + "phase-name": "build", + "current-stage": 1, + "total-stages": 1, + "completion-percentage": 100, + "start-date-time": "2025-03-26 13:31:02", + "end-date-time": "2025-03-26 13:31:02" + "stop-at-stage": 1, + "result": "success", + "timeout": 982, + "reason": "", + "inprogress": false, + "stages": [ + { + "start-date-time": "", + "end-date-time": "", + "stage-id": 0, + "stage-name": "kube-upgrade-query", + "reason": "", + "current-step": 0, + "steps": [ + { + "start-date-time": "", + "end-date-time": "", + "timeout": 60, + "step-id": 0, + "step-name": "query-kube-versions", + "result": "initial", + "reason": "" + }, + { + "start-date-time": "", + "end-date-time": "", + "timeout": 60, + "step-id": 0, + "entity-uuids": [], + "step-name": "query-kube-upgrade", + "result": "initial", + "reason": "" + }] + } + "apply-phase": { + "start-date-time": "", + "end-date-time": "", + "phase-name": "apply", + "completion-percentage": 100, + "total-stages": 0, + "stop-at-stage": 0, + "result": "initial", + "timeout": 0, + "reason": "", + "inprogress": false, + "stages": [], + "current-stage": 0 + }, + "abort-phase": { + "start-date-time": "", + "end-date-time": "", + "phase-name": "abort", + "completion-percentage": 100, + "total-stages": 0, + "stop-at-stage": 0, + "result": "initial", + "timeout": 0, + "reason": "", + "inprogress":false, + "stages": [], + "current-stage": 0 + } + } + + ------------------------ Firmware Update Strategy ------------------------ @@ -1928,10 +2531,15 @@ forbidden (403), badMethod (405), overLimit (413) "controller-apply-type", "plain", "xsd:string", "The apply type for controller hosts: ``ignore``." "storage-apply-type", "plain", "xsd:string", "The apply type for storage hosts: ``ignore``." - "worker-apply-type", "plain", "xsd:string", "The apply type for worker hosts: ``serial``, ``parallel`` or ``ignore``." - "max-parallel-worker-hosts (Optional)", "plain", "xsd:integer", "The maximum number of worker hosts to patch in parallel; only applicable if ``worker-apply-type = parallel``. Default value is ``2``." - "default-instance-action", "plain", "xsd:string", "The default instance action: ``stop-start`` or ``migrate``." - "alarm-restrictions (Optional)", "plain", "xsd:string", "The strictness of alarm checks: ``strict`` or ``relaxed``." + "worker-apply-type", "plain", "xsd:string", "The apply type for worker hosts: ``serial``, + ``parallel`` or ``ignore``." + "max-parallel-worker-hosts (Optional)", "plain", "xsd:integer", + "The maximum number of worker hosts to patch in parallel; only applicable if + ``worker-apply-type = parallel``. Default value is ``2``." + "default-instance-action", "plain", "xsd:string", "The default instance action: + ``stop-start`` or ``migrate``." + "alarm-restrictions (Optional)", "plain", "xsd:string", "The strictness of alarm checks: + ``strict`` or ``relaxed``." :: @@ -2090,8 +2698,18 @@ forbidden (403), badMethod (405), overLimit (413) :header: "Parameter", "Style", "Type", "Description" :widths: 20, 20, 20, 60 - "action", "plain", "xsd:string", "The action to take: ``apply-all``, ``apply-stage``, ``abort`` or ``abort-stage``." - "stage-id (Optional)", "plain", "xsd:string", "The stage-id to apply or abort. Only used with ``apply-stage`` or ``abort-stage`` actions." + "action", "plain", "xsd:string", "The action to take: ``apply-all``, ``apply-stage``, + ``abort`` or ``abort-stage``." + "stage-id (Optional)", "plain", "xsd:string", "The stage-id to apply or abort. + Only used with ``apply-stage`` or ``abort-stage`` actions." + +**Note** + +* stage-id - This is used to apply or abort a particular stage in the execution flow. + Each stage has a number specified. This can be identified from the response parameter + 'stage-id' which can be used to apply or abort a specific stage. +* apply-all or abort-all - This is recommended option, as it takes care of applying + or aborting all the required stages." :: @@ -2575,12 +3193,19 @@ forbidden (403), badMethod (405), overLimit (413) :header: "Parameter", "Style", "Type", "Description" :widths: 20, 20, 20, 60 - "controller-apply-type", "plain", "xsd:string", "The apply type for controller hosts: ``serial`` or ``ignore``." - "storage-apply-type", "plain", "xsd:string", "The apply type for storage hosts: ``serial`` or ``ignore``." - "worker-apply-type", "plain", "xsd:string", "The apply type for worker hosts: ``serial``, ``parallel`` or ``ignore``." - "max-parallel-worker-hosts (Optional)", "plain", "xsd:integer", "The maximum number of worker hosts to patch in parallel; only applicable if ``worker-apply-type = parallel``. Default value is ``2``." - "default-instance-action", "plain", "xsd:string", "The default instance action: ``stop-start`` or ``migrate``." - "alarm-restrictions (Optional)", "plain", "xsd:string", "The strictness of alarm checks: ``strict`` or ``relaxed``." + "controller-apply-type", "plain", "xsd:string", "The apply type for controller hosts: + ``serial`` or ``ignore``." + "storage-apply-type", "plain", "xsd:string", "The apply type for storage hosts: + ``serial`` or ``ignore``." + "worker-apply-type", "plain", "xsd:string", "The apply type for worker hosts: + ``serial``, ``parallel`` or ``ignore``." + "max-parallel-worker-hosts (Optional)", "plain", "xsd:integer", + "The maximum number of worker hosts to patch in parallel; only applicable if + ``worker-apply-type = parallel``. Default value is ``2``." + "default-instance-action", "plain", "xsd:string", "The default instance action: + ``stop-start`` or ``migrate``." + "alarm-restrictions (Optional)", "plain", "xsd:string", "The strictness of alarm checks: + ``strict`` or ``relaxed``." :: @@ -2739,8 +3364,18 @@ forbidden (403), badMethod (405), overLimit (413) :header: "Parameter", "Style", "Type", "Description" :widths: 20, 20, 20, 60 - "action", "plain", "xsd:string", "The action to take: ``apply-all``, ``apply-stage``, ``abort`` or ``abort-stage``." - "stage-id (Optional)", "plain", "xsd:string", "The stage-id to apply or abort. Only used with ``apply-stage`` or ``abort-stage`` actions." + "action", "plain", "xsd:string", "The action to take: ``apply-all``, ``apply-stage``, + ``abort`` or ``abort-stage``." + "stage-id (Optional)", "plain", "xsd:string", "The stage-id to apply or abort. + Only used with ``apply-stage`` or ``abort-stage`` actions." + +**Note** + +* stage-id - This is used to apply or abort a particular stage in the execution flow. + Each stage has a number specified. This can be identified from the response parameter + 'stage-id' which can be used to apply or abort a specific stage. +* apply-all or abort-all - This is recommended option, as it takes care of applying + or aborting all the required stages." :: @@ -2888,6 +3523,15 @@ This operation does not accept a request body. serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413), itemNotFound (404) +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "name", "plain", "xsd:string", "Strategy name." + "state", "plain", "xsd:string", "Current state of strategy." + **Response body example** The result shows current active strategy name and type. @@ -2957,6 +3601,15 @@ This operation does not accept a request body. serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413), itemNotFound (404) +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "name", "plain", "xsd:string", "Strategy name." + "state", "plain", "xsd:string", "Current state of strategy." + **Response body example** The result shows there is no current strategy. @@ -2972,136 +3625,13 @@ This command should take few seconds to return. If there is an existing strategy, 'strategy-name' and 'state' would be returned. Wait for the existing strategy to complete. --------------------- -Check System Health --------------------- - -The typical port used for SYSINV API is 6385. - -.. rest_method:: GET sysinv_url:sysinv_port/v1/ihosts/ - -**Request** - -This operation does not accept a request body. - -**Response** - -**Normal response codes** - -200 - -**Error response codes** - -computeFault (400, 500, ...), serviceUnavailable (503), badRequest (400), -unauthorized (401), forbidden (403), badMethod (405), overLimit (413), -itemNotFound (404) - -**Response body example** - -:: - - { - "ihosts": [ - { - "id": 1, - "uuid": "805b1368-f188-4264-a815-aaaed984c267", - "hostname": "controller-0", - "sysadmin", "personality": "controller", - "subfunctions": "controller", - "subfunction_oper": "disabled", - "subfunction_avail": "online", - "serialid": null, - "administrative": "unlocked", - "operational": "enabled", - "availability": "available", - "action": "none", - "ihost_action": "unlock", - "inv_state": "inventoried", - "vim_progress_status": "services-enabled" - ] - } - } - -**Note** -This command would take only few seconds to return. -All hosts are expected to be in 'unlocked', 'enabled' and 'available' state. -Any unexpected state, needs to be fixed before proceeding further. - ------------------ -Check for alarms ------------------ -The typical port used for the FM REST API is 18002. - -.. rest_method:: GET fm_url:fm_port/v1/alarms - -The supported query options are alarm_id, entity_type_id, -entity_instance_id, severity and alarm_type. - -**Request** - -**Request parameters** - -.. csv-table:: - :header: "Parameter", "Style", "Type", "Description" - :widths: 20, 20, 20, 60 - - "include_suppress (Optional)", "query", "xsd:boolean", "This optional parameter when - set to true (include_suppress=true) - specifies to include suppressed alarms in output." - "expand (Optional)", "query", "xsd:boolean", "This optional parameter when set to true (expand=true) specifies - that the response should contains the same response parameters as when querying for a specific alarm." - -**Response** - -**Normal response codes** - -200 - -**Error response codes** - -computeFault (400, 500, ...), serviceUnavailable (503), badRequest (400), -unauthorized (401), forbidden (403), badMethod (405), overLimit (413), -itemNotFound (404) - -**Response body parameters** - -.. csv-table:: - :header: "Parameter", "Style", "Type", "Description" - :widths: 20, 20, 20, 60 - - "alarms (Optional)", "plain", "xsd:list", "The list of active alarms based on the specified query." - "alarm_id (Optional)", "plain", "xsd:string", "The alarm ID; each type of alarm has a unique ID. - Note the alarm_id and the entity_instance_id uniquely identify an alarm instance." - "entity_instance_id (Optional)", "plain", "xsd:string", "The instance of the object raising alarm. A . - separated list of sub-entity-type=instance-value pairs, representing the containment structure of the - overall entity instance. Note the alarm_id and the entity_instance_id uniquely identify - an alarm instance." - "reason_text (Optional)", "plain", "xsd:string", "The text description of the alarm." - "severity (Optional)", "plain", "xsd:string", "The severity of the alarm; ``critical``, ``major``, - ``minor``, or ``warning``." - "timestamp (Optional)", "plain", "xsd:dateTime", "The time in UTC at which the alarm - has last been updated." - "uuid (Optional)", "plain", "csapi:UUID", "The unique identifier of the alarm." - -**Responde body example** - -:: - - { - "alarms": [] - } - -**Note** -If active alarm is present, proceed after the alarms are cleared. -This API takes few seconds to return. - ------------------------------------------------ Upload of software release on system controller ------------------------------------------------ The typical port used for Software REST API is 5497. -.. rest_method:: POST software_url:software_port/v1/release +.. rest_method:: POST {software_url}:{software_port}/v1/release **Request** @@ -3131,6 +3661,11 @@ internalServerError (500) **Response body parameters** +To verify if the software upload of a release is successful or not use below parameter. + +* error - In case of successful upload, this is an empty string(""). On failure, + this will have the error message. + .. csv-table:: :header: "Parameter", "Style", "Type", "Description" :widths: 20, 20, 20, 60 @@ -3179,7 +3714,8 @@ internalServerError (500) } **Note** -This command can take several minutes to complete (e.g. ~ 10 mins); especially in the case of a Major Release ISO. +This command can take several minutes to complete (e.g. ~ 10 mins); +especially in the case of a Major Release ISO. Patch files are typically much smaller and faster to load, e.g. a minute or less. There is no mechanism to monitor progress. The RESTAPI Response is not sent until the command completes. @@ -3190,9 +3726,9 @@ DC - Prestage software release on subcloud Create prestage-strategy is used in case of Distributed Cloud environment(DC), to make the software release available on the subcloud. -The typical port used for DCMANAGER REST API is 8119. +The typical port used for dcmanager REST API is 8119. -.. rest_method:: POST dcmanager_url:dcmanager_port/v1.0/sw-update-strategy/ +.. rest_method:: POST {dcmanager_url}:{dcmanager_port}/v1.0/sw-update-strategy/ **Request** @@ -3231,10 +3767,34 @@ badRequest (400), unauthorized (401), forbidden (403), badMethod (405), HTTPUnprocessableEntity (422), internalServerError (500), serviceUnavailable (503) +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Type", "Description" + :widths: 20, 20, 90 + + "type", "xsd:string", "Filter to query a particular type of update strategy + if it exists. One of: firmware, kube-rootca-update, kubernetes, patch, prestage, + or sw-deploy." + "subcloud-apply-type", "xsd:string", "The apply type for the update. serial + or parallel." + "max-parallel-subclouds", "xsd:integer", "The maximum number of subclouds + to update in parallel." + "stop-on-failure", "xsd:boolean", "Flag to indicate if the update should + stop updating additional subclouds if a failure is encountered." + "state", "xsd:integer", "The internal state of the sw-update-strategy." + "prestage_software_version", "xsd:integer", "The prestage software version for + the subcloud." + +**Note** +In case of create prestage strategy , the strategy response would be in 'initial' state on +successful creation of prestage-strategy. On failure, there would not be any strategy created +and error response will be returned. + **Response body example** :: - + { strategy type: prestage subcloud apply type: None @@ -3251,7 +3811,7 @@ DC - Apply prestage-strategy Apply prestage strategy is used in case of Distributed Cloud environment(DC), to make the software release available on the subcloud. -.. rest_method:: POST dcmanager_url:dcmanager_port/v1.0/sw-update-strategy/actions?type=prestage +.. rest_method:: POST {dcmanager_url}:{dcmanager_port}/v1.0/sw-update-strategy/actions?type=prestage **Request** @@ -3291,6 +3851,32 @@ badRequest (400), unauthorized (401), forbidden (403), badMethod (405), HTTPUnprocessableEntity (422), internalServerError (500), serviceUnavailable (503) +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Type", "Description" + :widths: 20, 20, 60 + + "type", "xsd:string", "Filter to query a particular type of update strategy + if it exists. One of: firmware, kube-rootca-update, kubernetes, patch, prestage, + or sw-deploy." + "subcloud-apply-type", "xsd:string", "The apply type for the update. serial + or parallel." + "max-parallel-subclouds", "xsd:integer", "The maximum number of subclouds + to update in parallel." + "stop-on-failure", "xsd:boolean", "Flag to indicate if the update should + stop updating additional subclouds if a failure is encountered." + "state", "xsd:integer", "The internal state of the sw-update-strategy." + "prestage_software_version", "xsd:integer", "The prestage software version for + the subcloud." + +**Note** +On applying a prestage strategy , below are the different 'state' that can be seen. + +* 'completed' - strategy applied successfully. +* 'applying' - strategy apply in progress. +* 'aborted' or 'failed' - strategy apply failed. + **Response body example** :: @@ -3335,7 +3921,8 @@ Creates software deploy strategy ``strict`` or ``relaxed``." "release", "plain", "xsd:string", "The release identification name." "rollback", "plain", "xsd:bool", "The flag that indicates this is a rollback action." - "delete", "plain", "xsd:bool", "The flag that indicates that deployment will be marked complete." + "delete", "plain", "xsd:bool", "The flag that indicates that deployment will be + marked complete." **Request body example** @@ -3363,6 +3950,36 @@ Creates software deploy strategy serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413) +**Response parameters** + +The "sw-deploy create strategy" request starts the creation process of the strategy, +and returns a response to indicate the status of the creation process. +E.g. typically after initially starting the create. + +* state ='building'. +* current-phase ='build' + +Use the sw-deploy get strategy request to monitor the progress and status of the create. + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "name", "plain", "xsd:string", "The current strategy name." + "release", "plain", "xsd:string", "The release identification name." + "controller-apply-type", "plain", "xsd:string", "Apply type of controller host." + "storage-apply-type", "plain", "xsd:string", "Apply type of storage host." + "worker-apply-type", "plain", "xsd:string", "Apply type of worker host." + "state", "plain", "xsd:string", "The current strategy state." + "current-phase", "plain", "xsd:string", "The current ongoing phase." + "stage-name", "plain", "xsd:string", "The current stage of execution in the current phase." + "step-name", "plain", "xsd:string", "The current step of execution in the current stage." + "completion-percentage", "plain", "xsd:integer", "The completion percentage of strategy." + "result", "plain", "xsd:string", "The result of current strategy." + "reason", "plain", "xsd:string", "The reason for success/failure of the current phase." + "response", "plain", "xsd:string", "This displays the detailed error message of the + reason for failure,if any." + **Response body example** :: @@ -3414,7 +4031,7 @@ forbidden (403), badMethod (405), overLimit (413) **Note** The execution will take few seconds to return the result. -The progress can be monitered using step 2. +The progress can be monitored using step 2. ----------------------------- 2) Show the strategy details @@ -3439,12 +4056,57 @@ This operation does not accept a request body. serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413), itemNotFound (404) +**Response parameters** + +The details of the strategy can be checked using below response parameter. + +* state - 'building or applying or aborting' or 'ready-to-apply or applied + or aborted' or 'build-failed or apply-failed or abort-failed'. +* result - 'success' or 'failed' or 'aborted'. +* reason and response - It's empty "" on success and on failure it's updated + with details of error. + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "name", "plain", "xsd:string", "The current strategy name." + "release", "plain", "xsd:string", "The release identification name." + "controller-apply-type", "plain", "xsd:string", "Apply type of controller host." + "storage-apply-type", "plain", "xsd:string", "Apply type of storage host." + "worker-apply-type", "plain", "xsd:string", "Apply type of worker host." + "state", "plain", "xsd:string", "The current strategy state." + "current-phase", "plain", "xsd:string", "The current ongoing phase." + "stage-name", "plain", "xsd:string", "The current stage of execution in the current phase." + "step-name", "plain", "xsd:string", "The current step of execution in the current stage." + "completion-percentage", "plain", "xsd:integer", "The completion percentage of strategy." + "result", "plain", "xsd:string", "The result of current strategy." + "reason", "plain", "xsd:string", "The reason for success/failure of the current phase." + "response", "plain", "xsd:string", "This displays the detailed error message of the + reason for failure,if any." + +**Note** + +* Phase - This refers to 'create or apply or abort' phase of strategy +* Stage - This points to various stages at each phase.Example; 'sw-upgrade start deploy', + 'sw-upgrade deploy host' +* Step - This refers to different steps executed in each stage. + Example; In 'sw-upgrade deploy host' stage, there are different steps like lock-hosts, + upgrade-hosts, system-stabilize, unlock-hosts. + +When using this API to monitor the progress or status of a create, apply or abort +operation, wait for the 'completion-percentage' parameter to reach 100%. +The 'completion-percentage' is 100% only in success case. +Then, use the 'result' parameter to determine whether it indicates +'success' or 'failure'. In the failure scenario, the 'reason' and 'response' +parameters provide more detailed information related to the failure. + **Response body example** :: { - "current-phase-completion": 100% + "completion-percentage": 100% "state": "ready-to-apply" } @@ -3470,6 +4132,14 @@ in response message. "stage-id (Optional)", "plain", "xsd:string", "The stage-id to apply or abort. Only used with ``apply-stage`` or ``abort-stage`` actions." +**Note** + +* stage-id - This is used to apply or abort a particular stage in the execution flow. + Each stage has a number specified. This can be identified from the response parameter + 'stage-id' which can be used to apply or abort a specific stage. +* apply-all or abort-all - This is recommended option, as it takes care of applying + or aborting all the required stages." + **Request body example** :: @@ -3489,6 +4159,36 @@ in response message. serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413) +**Response parameters** + +The "sw-deploy" strategy "apply" or "abort" request starts the apply or abort process, +and returns a response to indicate the current status of the apply or abort process. +E.g. typically after initially starting the create. + +* state = 'applying' or 'aborting'. +* current-phase ='apply' or 'abort' + +Use the sw-deploy get strategy request to monitor the progress and status of Apply strategy. + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "name", "plain", "xsd:string", "The current strategy name." + "release", "plain", "xsd:string", "The release identification name." + "controller-apply-type", "plain", "xsd:string", "Apply type of controller host." + "storage-apply-type", "plain", "xsd:string", "Apply type of storage host." + "worker-apply-type", "plain", "xsd:string", "Apply type of worker host." + "state", "plain", "xsd:string", "The current strategy state." + "current-phase", "plain", "xsd:string", "The current ongoing phase." + "stage-name", "plain", "xsd:string", "The current stage of execution in the current phase." + "step-name", "plain", "xsd:string", "The current step of execution in the current stage." + "completion-percentage", "plain", "xsd:integer", "The completion percentage of strategy." + "result", "plain", "xsd:string", "The result of current strategy." + "reason", "plain", "xsd:string", "The reason for success/failure of the current phase." + "response", "plain", "xsd:string", "This displays the detailed error message of the + reason for failure,if any." + **Response body example** :: @@ -3512,6 +4212,7 @@ forbidden (403), badMethod (405), overLimit (413) "result": "inprogress", "timeout": 18304, "reason": "", + "response": "" "inprogress": true, "stages": [ { @@ -3558,11 +4259,19 @@ for stage-id data in the strategy output. :header: "Parameter", "Style", "Type", "Description" :widths: 20, 20, 20, 60 - "action", "plain", "xsd:string", "The action to take: ``apply-all``, ``apply-stage``, - ``abort`` or ``abort-stage``." + "action", "plain", "xsd:string", "The action to take: ``apply-all``, + ``apply-stage``,``abort``or ``abort-stage``." "stage-id (Optional)", "plain", "xsd:string", "The stage-id to apply or abort. Only used with ``apply-stage`` or ``abort-stage`` actions." +**Note** + +* stage-id - This is used to apply or abort a particular stage in the execution flow. + Each stage has a number specified. This can be identified from the response parameter + 'stage-id' which can be used to apply or abort a specific stage. +* apply-all or abort-all - This is recommended option, as it takes care of applying + or aborting all the required stages." + **Request body example** :: @@ -3583,6 +4292,36 @@ for stage-id data in the strategy output. serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413) +**Response parameters** + +The "sw-deploy" strategy "apply" or "abort" request starts the apply or abort process, +and returns a response to indicate the current status of the apply or abort process. +E.g. typically after initially starting the create. + +* state = 'applying' or 'aborting'. +* current-phase ='apply' or 'abort' + +Use the sw-deploy get strategy request to monitor the progress and status of Apply strategy. + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "name", "plain", "xsd:string", "The current strategy name." + "release", "plain", "xsd:string", "The release identification name." + "controller-apply-type", "plain", "xsd:string", "Apply type of controller host." + "storage-apply-type", "plain", "xsd:string", "Apply type of storage host." + "worker-apply-type", "plain", "xsd:string", "Apply type of worker host." + "state", "plain", "xsd:string", "The current strategy state." + "current-phase", "plain", "xsd:string", "The current ongoing phase." + "stage-name", "plain", "xsd:string", "The current stage of execution in the current phase." + "step-name", "plain", "xsd:string", "The current step of execution in the current stage." + "completion-percentage", "plain", "xsd:integer", "The completion percentage of strategy." + "result", "plain", "xsd:string", "The result of current strategy." + "reason", "plain", "xsd:string", "The reason for success/failure of the current phase." + "response", "plain", "xsd:string", "This displays the detailed error message of the + reason for failure,if any." + **Response body example** :: @@ -3654,13 +4393,61 @@ This operation does not accept a request body. serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413), itemNotFound (404) +**Response parameters** + +The details of the strategy can be checked using below response parameter. + +* state - 'building or applying or aborting' or 'ready-to-apply or + applied or aborted' or 'build-failed or apply-failed or abort-failed'. +* result - 'success' or 'failed' or 'aborted'. +* reason and response - It's empty "" on success and on failure it's updated + with details of error. + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "name", "plain", "xsd:string", "The current strategy name." + "release", "plain", "xsd:string", "The release identification name." + "controller-apply-type", "plain", "xsd:string", "Apply type of controller host." + "storage-apply-type", "plain", "xsd:string", "Apply type of storage host." + "worker-apply-type", "plain", "xsd:string", "Apply type of worker host." + "state", "plain", "xsd:string", "The current strategy state." + "current-phase", "plain", "xsd:string", "The current ongoing phase." + "stage-name", "plain", "xsd:string", "The current stage of execution in the current phase." + "step-name", "plain", "xsd:string", "The current step of execution in the current stage." + "completion-percentage", "plain", "xsd:integer", "The completion percentage of strategy." + "result", "plain", "xsd:string", "The result of current strategy." + "reason", "plain", "xsd:string", "The reason for success/failure of the current phase." + "response", "plain", "xsd:string", "This displays the detailed error message of the + reason for failure,if any." + +**Note** + +* Phase - This refers to 'create or apply or abort' phase of strategy +* Stage - This points to various stages at each phase.Example; + 'sw-upgrade start deploy', 'sw-upgrade deploy host' +* Step - This refers to different steps executed in each stage. + Example; In 'sw-upgrade deploy host' stage, there are different steps like lock-hosts, + upgrade-hosts, system-stabilize, unlock-hosts. + +When using this API to monitor the progress or status of a create, apply or abort +operation, wait for the 'completion-percentage' parameter to reach 100%. +The 'completion-percentage' is 100% only in success case. +Then, use the 'result' parameter to determine whether it indicates +'success' or 'failure'. In the failure scenario, the 'reason' and 'response' +parameters provide more detailed information related to the failure. + **Response body example** :: { - "current-phase-completion": 100% - "state": "applied" + "completion-percentage": 100% + "state": "applied", + "result": success, + "reason": "", + "response": "", } ------------------ @@ -3671,7 +4458,7 @@ If the user has not selected ‘delete: true’ in step 1, then complete the dep using below API to delete. The typical port used for software REST API is 5497. -.. rest_method:: DELETE software_url:software_port/v1/deploy +.. rest_method:: DELETE {software_url}:{software_port}/v1/deploy **Request** @@ -3749,6 +4536,15 @@ This operation does not accept a request body. serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413), itemNotFound (404) +**Response parameters** + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "name", "plain", "xsd:string", "Strategy name." + "state", "plain", "xsd:string", "Current state of strategy." + **Response body example** The result shows there is no current strategy. @@ -3766,7 +4562,7 @@ Shows software list The typical port used for the Software REST API is 5497. Software list shows the release is in ‘deployed’ state. -.. rest_method:: GET software_url:software_port/v1/release/{release-id} +.. rest_method:: GET {software_url}:{software_port}/v1/release/{release-id} **Request** @@ -3847,9 +4643,13 @@ Create software deploy strategy. "storage-apply-type", "plain", "xsd:string", "The apply type for storage hosts: ``serial``, ``parallel`` or ``ignore``." - "worker-apply-type", "plain", "xsd:string", "The apply type for worker hosts: ``serial`` , ``parallel`` or ``ignore``." - "max-parallel-worker-hosts (Optional)", "plain", "xsd:integer", "The maximum number of w orker hosts to upgrade in parallel; only applicable if ``worker-apply-type = parallel``. Default value is ``2``." - "alarm-restrictions (Optional)", "plain", "xsd:string", "The strictness of alarm checks: ``strict`` or ``relaxed``." + "worker-apply-type", "plain", "xsd:string", "The apply type for worker hosts: ``serial``, + ``parallel`` or ``ignore``." + "max-parallel-worker-hosts (Optional)", "plain", "xsd:integer", "The maximum number of + worker hosts to upgrade in parallel; only applicable if ``worker-apply-type = parallel``. + Default value is ``2``." + "alarm-restrictions (Optional)", "plain", "xsd:string", "The strictness of alarm checks: + ``strict`` or ``relaxed``." "release", "plain", "xsd:string", "The release identification name." "rollback", "plain", "xsd:bool", "The flag that indicates this is a rollback action." "delete", "plain", "xsd:bool", "The flag that indicates that deployment will be marked complete." @@ -3880,6 +4680,36 @@ Create software deploy strategy. serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413) +**Response parameters** + +The "sw-deploy create strategy" request starts the creation process of the strategy, +and returns a response to indicate the status of the creation process. +E.g. typically after initially starting the create. + +* state ='building'. +* current-phase ='build' + +Use the sw-deploy get strategy request to monitor the progress and status of the create. + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "name", "plain", "xsd:string", "The current strategy name." + "release", "plain", "xsd:string", "The release identification name." + "controller-apply-type", "plain", "xsd:string", "Apply type of controller host." + "storage-apply-type", "plain", "xsd:string", "Apply type of storage host." + "worker-apply-type", "plain", "xsd:string", "Apply type of worker host." + "state", "plain", "xsd:string", "The current strategy state." + "current-phase", "plain", "xsd:string", "The current ongoing phase." + "stage-name", "plain", "xsd:string", "The current stage of execution in the current phase." + "step-name", "plain", "xsd:string", "The current step of execution in the current stage." + "completion-percentage", "plain", "xsd:integer", "The completion percentage of strategy." + "result", "plain", "xsd:string", "The result of current strategy." + "reason", "plain", "xsd:string", "The reason for success/failure of the current phase." + "response", "plain", "xsd:string", "This displays the detailed error message of the reason + for failure,if any." + **Response body example** :: @@ -3956,6 +4786,51 @@ This operation does not accept a request body. serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413), itemNotFound (404) +**Response parameters** + +The details of the strategy can be checked using below response parameter. + +* state - 'building or applying or aborting' or 'ready-to-apply or + applied or aborted' or 'build-failed or apply-failed or abort-failed'. +* result - 'success' or 'failed' or 'aborted'. +* reason and response - It's empty "" on success and on failure it's updated + with details of error. + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "name", "plain", "xsd:string", "The current strategy name." + "release", "plain", "xsd:string", "The release identification name." + "controller-apply-type", "plain", "xsd:string", "Apply type of controller host." + "storage-apply-type", "plain", "xsd:string", "Apply type of storage host." + "worker-apply-type", "plain", "xsd:string", "Apply type of worker host." + "state", "plain", "xsd:string", "The current strategy state." + "current-phase", "plain", "xsd:string", "The current ongoing phase." + "stage-name", "plain", "xsd:string", "The current stage of execution in the current phase." + "step-name", "plain", "xsd:string", "The current step of execution in the current stage." + "completion-percentage", "plain", "xsd:integer", "The completion percentage of strategy." + "result", "plain", "xsd:string", "The result of current strategy." + "reason", "plain", "xsd:string", "The reason for success/failure of the current phase." + "response", "plain", "xsd:string", "This displays the detailed error message of the + reason for failure,if any." + +**Note** + +* Phase - This refers to 'create or apply or abort' phase of strategy +* Stage - This points to various stages at each phase. + Example; 'sw-upgrade start deploy', 'sw-upgrade deploy host' +* Step - This refers to different steps executed in each stage. + Example; In 'sw-upgrade deploy host' stage, there are different steps like lock-hosts, + upgrade-hosts, system-stabilize, unlock-hosts. + +When using this API to monitor the progress or status of a create, apply or abort +operation, wait for the 'completion-percentage' parameter to reach 100%. +The 'completion-percentage' is 100% only in success case. +Then, use the 'result' parameter to determine whether it indicates +'success' or 'failure'. In the failure scenario, the 'reason' and 'response' +parameters provide more detailed information related to the failure. + **Response body example** :: @@ -3987,6 +4862,14 @@ in response message. "stage-id (Optional)", "plain", "xsd:string", "The stage-id to apply or abort. Only used with ``apply-stage`` or ``abort-stage`` actions." +**Note** + +* stage-id - This is used to apply or abort a particular stage in the execution flow. + Each stage has a number specified. This can be identified from the response parameter + 'stage-id' which can be used to apply or abort a specific stage. +* apply-all or abort-all - This is recommended option, as it takes care of applying + or aborting all the required stages." + **Request body example** :: @@ -4006,6 +4889,36 @@ in response message. serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413) +**Response parameters** + +The "sw-deploy" strategy "apply" or "abort" request starts the apply or abort process, +and returns a response to indicate the current status of the apply or abort process. +E.g. typically after initially starting the create. + +* state = 'applying' or 'aborting'. +* current-phase ='apply' or 'abort' + +Use the sw-deploy get strategy request to monitor the progress and status of Apply strategy. + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "name", "plain", "xsd:string", "The current strategy name." + "release", "plain", "xsd:string", "The release identification name." + "controller-apply-type", "plain", "xsd:string", "Apply type of controller host." + "storage-apply-type", "plain", "xsd:string", "Apply type of storage host." + "worker-apply-type", "plain", "xsd:string", "Apply type of worker host." + "state", "plain", "xsd:string", "The current strategy state." + "current-phase", "plain", "xsd:string", "The current ongoing phase." + "stage-name", "plain", "xsd:string", "The current stage of execution in the current phase." + "step-name", "plain", "xsd:string", "The current step of execution in the current stage." + "completion-percentage", "plain", "xsd:integer", "The completion percentage of strategy." + "result", "plain", "xsd:string", "The result of current strategy." + "reason", "plain", "xsd:string", "The reason for success/failure of the current phase." + "response", "plain", "xsd:string", "This displays the detailed error message of the + reason for failure,if any." + **Response body example** :: @@ -4063,8 +4976,8 @@ The API takes long time to complete the operation. Approximately it takes an hou ------------------------------------------ If a particular stage needs to be applied, then use the stage id parameter. -To identify the stage-id that needs to be applied, the user can get the details by looking -for stage-id data in the strategy output. +To identify the stage-id that needs to be applied, the user can get the details +by looking for stage-id data in the strategy output. .. rest_method:: POST /api/orchestration/sw-upgrade/strategy/actions @@ -4081,6 +4994,14 @@ for stage-id data in the strategy output. "stage-id (Optional)", "plain", "xsd:string", "The stage-id to apply or abort. Only used with ``apply-stage`` or ``abort-stage`` actions." +**Note** + +* stage-id - This is used to apply or abort a particular stage in the execution flow. + Each stage has a number specified. This can be identified from the response parameter + 'stage-id' which can be used to apply or abort a specific stage. +* apply-all or abort-all - This is recommended option, as it takes care of applying + or aborting all the required stages." + **Request body example** :: @@ -4101,6 +5022,36 @@ for stage-id data in the strategy output. serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413) +**Response parameters** + +The "sw-deploy" strategy "apply" or "abort" request starts the apply or abort process, +and returns a response to indicate the current status of the apply or abort process. +E.g. typically after initially starting the create. + +* state = 'applying' or 'aborting'. +* current-phase ='apply' or 'abort' + +Use the sw-deploy get strategy request to monitor the progress and status of Apply strategy. + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "name", "plain", "xsd:string", "The current strategy name." + "release", "plain", "xsd:string", "The release identification name." + "controller-apply-type", "plain", "xsd:string", "Apply type of controller host." + "storage-apply-type", "plain", "xsd:string", "Apply type of storage host." + "worker-apply-type", "plain", "xsd:string", "Apply type of worker host." + "state", "plain", "xsd:string", "The current strategy state." + "current-phase", "plain", "xsd:string", "The current ongoing phase." + "stage-name", "plain", "xsd:string", "The current stage of execution in the current phase." + "step-name", "plain", "xsd:string", "The current step of execution in the current stage." + "completion-percentage", "plain", "xsd:integer", "The completion percentage of strategy." + "result", "plain", "xsd:string", "The result of current strategy." + "reason", "plain", "xsd:string", "The reason for success/failure of the current phase." + "response", "plain", "xsd:string", "This displays the detailed error message of the reason + for failure,if any." + **Response body example** :: @@ -4169,6 +5120,51 @@ This operation does not accept a request body. serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413), itemNotFound (404) +**Response parameters** + +The details of the strategy can be checked using below response parameter. + +* state - 'building or applying or aborting' or 'ready-to-apply or + applied or aborted' or 'build-failed or apply-failed or abort-failed'. +* result - 'success' or 'failed' or 'aborted'. +* reason and response - It's empty "" on success and on failure it's updated + with details of error. + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "name", "plain", "xsd:string", "The current strategy name." + "release", "plain", "xsd:string", "The release identification name." + "controller-apply-type", "plain", "xsd:string", "Apply type of controller host." + "storage-apply-type", "plain", "xsd:string", "Apply type of storage host." + "worker-apply-type", "plain", "xsd:string", "Apply type of worker host." + "state", "plain", "xsd:string", "The current strategy state." + "current-phase", "plain", "xsd:string", "The current ongoing phase." + "stage-name", "plain", "xsd:string", "The current stage of execution in the current phase." + "step-name", "plain", "xsd:string", "The current step of execution in the current stage." + "completion-percentage", "plain", "xsd:integer", "The completion percentage of strategy." + "result", "plain", "xsd:string", "The result of current strategy." + "reason", "plain", "xsd:string", "The reason for success/failure of the current phase." + "response", "plain", "xsd:string", "This displays the detailed error message of the reason + for failure,if any." + +**Note** + +* Phase - This refers to 'create or apply or abort' phase of strategy +* Stage - This points to various stages at each phase. + Example; 'sw-upgrade start deploy', 'sw-upgrade deploy host' +* Step - This refers to different steps executed in each stage. + Example; In 'sw-upgrade deploy host' stage, there are different steps like lock-hosts, + upgrade-hosts, system-stabilize, unlock-hosts. + +When using this API to monitor the progress or status of a create, apply or abort +operation, wait for the 'completion-percentage' parameter to reach 100%. +The 'completion-percentage' is 100% only in success case. +Then, use the 'result' parameter to determine whether it indicates +'success' or 'failure'. In the failure scenario, the 'reason' and 'response' +parameters provide more detailed information related to the failure. + **Response body example** :: @@ -4190,7 +5186,7 @@ If the user has not selected ‘delete: true’ in step 1, then complete the dep using below API to delete. The typical port used for software REST API is 5497. -.. rest_method:: DELETE software_url:software_port/v1/deploy +.. rest_method:: DELETE {software_url}:{software_port}/v1/deploy **Request** @@ -4226,7 +5222,7 @@ internalServerError (500) "error": "" } -This will mark the deploymet complete. +This will mark the deployment complete. ----------------------------------------------------------------------- Software deployment Orchestration For Patch and Major Release Rollback @@ -4268,6 +5264,7 @@ forbidden (403), badMethod (405), overLimit (413), itemNotFound (404) **Response body example** +The strategy can be in 'failed' or 'aborted' or 'timed-out' state. The result shows current active strategy name and state as 'failed'. :: @@ -4279,13 +5276,19 @@ The result shows current active strategy name and state as 'failed'. } } + +**Note** +If a strategy is in failed/aborted/timed-out state, check the "reason" and "response" +message fields of the failed strategy. Refer section 'Shows detailed information about the +current sw-deploy strategy' to get details of the reason for failure. + --------------------- Check System Health --------------------- The typical port used for SYSINV API is 6385. -.. rest_method:: GET system_url:system_port/v1/ihosts/ +.. rest_method:: GET {sysinv_url}:{sysinv_port}/v1/health/ **Request** @@ -4308,30 +5311,25 @@ itemNotFound (404) :: { - "ihosts": [ + "System Health": { - "id": 1, - "uuid": "805b1368-f188-4264-a815-aaaed984c267", - "hostname": "controller-0", - "sysadmin", "personality": "controller", - "subfunctions": "controller", - "subfunction_oper": "disabled", - "subfunction_avail": "online", - "serialid": null, - "administrative": "locked", - "operational": "enabled", - "availability": "available", - "action": "none", - "ihost_action": "unlock", - "inv_state": "inventoried", - "vim_progress_status": "services-enabled" - ] + "All hosts are provisioned": [OK], + "All hosts are unlocked/enabled": [Fail], + "Locked or disabled hosts": controller-1, + "All hosts have current configurations": [OK], + "All hosts are patch current": [OK], + "Ceph Storage Healthy": [Fail], + "No alarms": [Fail][19] alarms found, [16] of which are + management affecting and [0] are certificate expiration alarms. + Use "fm alarm-list" for details + "All kubernetes nodes are ready": [OK] + "All kubernetes control plane pods are ready": [OK] } } **Note** The system is not in healthy state. -Example, the host may be in locked or unvailable +Example, the host may be in locked or unavailable state. ------------------ @@ -4340,7 +5338,7 @@ Check for alarms The typical port used for the FM REST API is 18002. -.. rest_method:: GET fm_url:fm_port/v1/alarms +.. rest_method:: GET {fm_url}:{fm_port}/v1/alarms The supported query options are alarm_id, entity_type_id, entity_instance_id, severity and alarm_type. @@ -4353,10 +5351,12 @@ entity_instance_id, severity and alarm_type. :header: "Parameter", "Style", "Type", "Description" :widths: 20, 20, 20, 60 - "include_suppress (Optional)", "query", "xsd:boolean", "This optional parameter when set to true (include_suppress=true) + "include_suppress (Optional)", "query", "xsd:boolean", "This optional parameter when set + to true (include_suppress=true) specifies to include suppressed alarms in output." - "expand (Optional)", "query", "xsd:boolean", "This optional parameter when set to true (expand=true) specifies - that the response should contains the same response parameters as when querying for a specific alarm." + "expand (Optional)", "query", "xsd:boolean", "This optional parameter when set to + true (expand=true) specifies that the response should contains the same response + parameters as when querying for a specific alarm." **Response** @@ -4376,16 +5376,20 @@ itemNotFound (404) :header: "Parameter", "Style", "Type", "Description" :widths: 20, 20, 20, 60 - "alarms (Optional)", "plain", "xsd:list", "The list of active alarms based on the specified query." - "alarm_id (Optional)", "plain", "xsd:string", "The alarm ID; each type of alarm has a unique ID. + "alarms (Optional)", "plain", "xsd:list", "The list of active alarms based on + the specified query." + "alarm_id (Optional)", "plain", "xsd:string", "The alarm ID; each type of alarm + has a unique ID.Note the alarm_id and the entity_instance_id uniquely identify an + alarm instance." + "entity_instance_id (Optional)", "plain", "xsd:string", "The instance of the object + raising alarm. A .separated list of sub-entity-type=instance-value pairs, + representing the containment structure of the overall entity instance. Note the alarm_id and the entity_instance_id uniquely identify an alarm instance." - "entity_instance_id (Optional)", "plain", "xsd:string", "The instance of the object raising alarm. A . - separated list of sub-entity-type=instance-value pairs, representing the containment structure of the - overall entity instance. Note the alarm_id and the entity_instance_id uniquely identify an alarm instance." "reason_text (Optional)", "plain", "xsd:string", "The text description of the alarm." - "severity (Optional)", "plain", "xsd:string", "The severity of the alarm; ``critical``, ``major``, - ``minor``, or ``warning``." - "timestamp (Optional)", "plain", "xsd:dateTime", "The time in UTC at which the alarm has last been updated." + "severity (Optional)", "plain", "xsd:string", "The severity of the alarm; ``critical``, + ``major``,``minor``, or ``warning``." + "timestamp (Optional)", "plain", "xsd:dateTime", "The time in UTC at which the alarm + has last been updated." "uuid (Optional)", "plain", "csapi:UUID", "The unique identifier of the alarm." **Responde body example** @@ -4409,7 +5413,7 @@ itemNotFound (404) **Note** -Active alarm will be present as the system might be in +Active alarm(s) may be present as the system might be in locked, unavailable state. ------ @@ -4454,15 +5458,28 @@ Steps **Request parameters** +The "sw-deploy create strategy" request starts the creation process of the strategy, +and returns a response to indicate the status of the creation process. +E.g. typically after initially starting the create. + +* state ='building'. +* current-phase ='build' + +Use the sw-deploy get strategy request to monitor the progress and status of the create. + .. csv-table:: :header: "Parameter", "Style", "Type", "Description" :widths: 20, 20, 20, 60 "storage-apply-type", "plain", "xsd:string", "The apply type for storage hosts: ``serial``, ``parallel`` or ``ignore``." - "worker-apply-type", "plain", "xsd:string", "The apply type for worker hosts: ``serial`` , ``parallel`` or ``ignore``." - "max-parallel-worker-hosts (Optional)", "plain", "xsd:integer", "The maximum number of w orker hosts to upgrade in parallel; only applicable if ``worker-apply-type = parallel``. Default value is ``2``." - "alarm-restrictions (Optional)", "plain", "xsd:string", "The strictness of alarm checks: ``strict`` or ``relaxed``." + "worker-apply-type", "plain", "xsd:string", "The apply type for worker hosts: ``serial`` , + ``parallel`` or ``ignore``." + "max-parallel-worker-hosts (Optional)", "plain", "xsd:integer", "The maximum number + of worker hosts to upgrade in parallel; only applicable if ``worker-apply-type = + parallel``. Default value is ``2``." + "alarm-restrictions (Optional)", "plain", "xsd:string", "The strictness of alarm + checks:``strict`` or ``relaxed``." "release", "plain", "xsd:string", "The release identification name." "rollback", "plain", "xsd:bool", "The flag that indicates this is a rollback action." "delete", "plain", "xsd:bool", "The flag that indicates that deployment will be marked complete." @@ -4507,6 +5524,51 @@ This operation does not accept a request body. serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413), itemNotFound (404) +**Response parameters** + +The details of the strategy can be checked using below response parameter. + +* state - 'building or applying or aborting' or 'ready-to-apply or + applied or aborted' or 'build-failed or apply-failed or abort-failed' +* result - 'success' or 'failed' or 'aborted'. +* reason and response - It's empty "" on success and on failure it's updated + with details of error. + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "name", "plain", "xsd:string", "The current strategy name." + "release", "plain", "xsd:string", "The release identification name." + "controller-apply-type", "plain", "xsd:string", "Apply type of controller host." + "storage-apply-type", "plain", "xsd:string", "Apply type of storage host." + "worker-apply-type", "plain", "xsd:string", "Apply type of worker host." + "state", "plain", "xsd:string", "The current strategy state." + "current-phase", "plain", "xsd:string", "The current ongoing phase." + "stage-name", "plain", "xsd:string", "The current stage of execution in the current phase." + "step-name", "plain", "xsd:string", "The current step of execution in the current stage." + "completion-percentage", "plain", "xsd:integer", "The completion percentage of strategy." + "result", "plain", "xsd:string", "The result of current strategy." + "reason", "plain", "xsd:string", "The reason for success/failure of the current phase." + "response", "plain", "xsd:string", "This displays the detailed error message of the reason + for failure,if any." + +**Note** + +* Phase - This refers to 'create or apply or abort' phase of strategy +* Stage - This points to various stages at each phase.Example; 'sw-upgrade start deploy', + 'sw-upgrade deploy host' +* Step - This refers to different steps executed in each stage. + Example; In 'sw-upgrade deploy host' stage, there are different steps like lock-hosts, + upgrade-hosts, system-stabilize, unlock-hosts. + +When using this API to monitor the progress or status of a create, apply or abort +operation, wait for the 'completion-percentage' parameter to reach 100%. +The 'completion-percentage' is 100% only in success case. +Then, use the 'result' parameter to determine whether it indicates +'success' or 'failure'. In the failure scenario, the 'reason' and 'response' +parameters provide more detailed information related to the failure. + **Response body example** :: @@ -4538,6 +5600,14 @@ in response message. "stage-id (Optional)", "plain", "xsd:string", "The stage-id to apply or abort. Only used with ``apply-stage`` or ``abort-stage`` actions." +**Note** + +* stage-id - This is used to apply or abort a particular stage in the execution flow. + Each stage has a number specified. This can be identified from the response parameter + 'stage-id' which can be used to apply or abort a specific stage. +* apply-all or abort-all - This is recommended option, as it takes care of applying + or aborting all the required stages." + **Request body example** :: @@ -4557,6 +5627,36 @@ in response message. serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413) +**Response parameters** + +The "sw-deploy" strategy "apply" or "abort" request starts the apply or abort process, +and returns a response to indicate the current status of the apply or abort process. +E.g. typically after initially starting the create. + +* state = 'applying' or 'aborting'. +* current-phase ='apply' or 'abort' + +Use the sw-deploy get strategy request to monitor the progress and status of Apply strategy. + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "name", "plain", "xsd:string", "The current strategy name." + "release", "plain", "xsd:string", "The release identification name." + "controller-apply-type", "plain", "xsd:string", "Apply type of controller host." + "storage-apply-type", "plain", "xsd:string", "Apply type of storage host." + "worker-apply-type", "plain", "xsd:string", "Apply type of worker host." + "state", "plain", "xsd:string", "The current strategy state." + "current-phase", "plain", "xsd:string", "The current ongoing phase." + "stage-name", "plain", "xsd:string", "The current stage of execution in the current phase." + "step-name", "plain", "xsd:string", "The current step of execution in the current stage." + "completion-percentage", "plain", "xsd:integer", "The completion percentage of strategy." + "result", "plain", "xsd:string", "The result of current strategy." + "reason", "plain", "xsd:string", "The reason for success/failure of the current phase." + "response", "plain", "xsd:string", "This displays the detailed error message of the reason + for failure,if any." + **Response body example** :: @@ -4625,6 +5725,51 @@ This operation does not accept a request body. serviceUnavailable (503), badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413), itemNotFound (404) +**Response parameters** + +The details of the strategy can be checked using below response parameter. + +* state - 'building or applying or aborting' or 'ready-to-apply or + 'applied' or 'aborted' or 'build-failed or apply-failed or abort-failed'. +* result - 'success' or 'failed' or 'aborted'. +* reason and response - It's empty "" on success and on failure it's updated + with details of error. + +.. csv-table:: + :header: "Parameter", "Style", "Type", "Description" + :widths: 20, 20, 20, 60 + + "name", "plain", "xsd:string", "The current strategy name." + "release", "plain", "xsd:string", "The release identification name." + "controller-apply-type", "plain", "xsd:string", "Apply type of controller host." + "storage-apply-type", "plain", "xsd:string", "Apply type of storage host." + "worker-apply-type", "plain", "xsd:string", "Apply type of worker host." + "state", "plain", "xsd:string", "The current strategy state." + "current-phase", "plain", "xsd:string", "The current ongoing phase." + "stage-name", "plain", "xsd:string", "The current stage of execution in the current phase." + "step-name", "plain", "xsd:string", "The current step of execution in the current stage." + "completion-percentage", "plain", "xsd:integer", "The completion percentage of strategy." + "result", "plain", "xsd:string", "The result of current strategy." + "reason", "plain", "xsd:string", "The reason for success/failure of the current phase." + "response", "plain", "xsd:string", "This displays the detailed error message of the + reason for failure,if any." + +**Note** + +* Phase - This refers to 'create or apply or abort' phase of strategy +* Stage - This points to various stages at each phase. + Example; 'sw-upgrade start deploy', 'sw-upgrade deploy host' +* Step - This refers to different steps executed in each stage. + Example; In 'sw-upgrade deploy host' stage, there are different steps like lock-hosts, + upgrade-hosts, system-stabilize, unlock-hosts. + +When using this API to monitor the progress or status of a create, apply or abort +operation, wait for the 'completion-percentage' parameter to reach 100%. +The 'completion-percentage' is 100% only in success case. +Then, use the 'result' parameter to determine whether it indicates +'success' or 'failure'. In the failure scenario, the 'reason' and 'response' +parameters provide more detailed information related to the failure. + **Response body example** :: @@ -4649,7 +5794,7 @@ The typical port used for Software REST API is 5497. The release should be rolled back and the earlier release would be marked as the active one. -.. rest_method:: GET software_url:software_port/v1/release +.. rest_method:: GET {software_url}:{software_port}/v1/release **Request**