diff options
| -rw-r--r-- | docs/APPC LCM API Guide/APPC LCM API Guide.rst | 610 |
1 files changed, 319 insertions, 291 deletions
diff --git a/docs/APPC LCM API Guide/APPC LCM API Guide.rst b/docs/APPC LCM API Guide/APPC LCM API Guide.rst index 83427f95b..24b7447c7 100644 --- a/docs/APPC LCM API Guide/APPC LCM API Guide.rst +++ b/docs/APPC LCM API Guide/APPC LCM API Guide.rst @@ -130,7 +130,7 @@ Table 1 Request / Response Message Fields | | "input" : { | | | | "common-header" : {...} | | | | "action" : "configure", | | -| | "action-identifiers" : {...}, | | +| | "action-identifiers" : {...}, | | | | "payload": "..." | | | | } | | +----------------------+----------------------------------------------------------------------------------------------------------------+---------------------+ @@ -173,85 +173,85 @@ The LCM request conforms to the following structure:: Table 2 LCM Request Fields -+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ -| **Field** | **Description** | **Required?** | -+===========================+========================================================================================================================================================================================================================================================================================================================+=====================+ -| input | The block that defines the details of the input to the command processing. Contains the common-header details. | Yes | -+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ -| common- header | The block that contains the generic details about a request. | Yes | -+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ -| timestamp | The time of the request, in ISO 8601 format, ZULU offset. For example: 2016-08-03T08:50:18.97Z. | Yes | -| | | | -| | APPC will reject the request if timestamp is in the future (due to clock error), or timestamp is too old (compared to TTL flag) | | -+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ -| api-ver | Identifies the API version, in X.YY format, where X denotes the major version increased with each APPC release, and YY is the minor release version. | Yes | -| | | | -| | 2.00 should be used for all LCM API requests | | -+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ -| originator-id | An identifier of the calling system limited to a length of 40 characters. | Yes | -| | | | -| | It can be used for addressing purposes, such as to return an asynchronous response to the correct destination, in particular where there are multiple consumers of APPC APIs. | | -+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ -| request-id | The UUID for the request ID, limited to a length of 40 characters. The unique OSS/BSS identifier for the request ID that triggers the current LCM action. Multiple API calls can be made with the same request-id. | Yes | -| | | | -| | The request-id is stored throughout the operations performed during a single request. | | -+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ -| sub-request-id | Uniquely identifies a specific LCM or control action, limited to a length of 40 characters. Persists throughout the life cycle of a single request. | No | -+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ -| flags | Generic flags that apply to all LCM actions: | No | -| | | | -| | - "MODE" : | | -| | | | -| | - "EXCLUSIVE" - reject requests on this VNF while another request is in progress, or | | -| | | | -| | - "NORMAL" - allow requests (pending additional validations) on this VNF if there is another request is in progress. | | -| | | | -| | - "FORCE" : | | -| | - TRUE – forces APP-C to process the request regardless of whether there is another request for the VNF or VM in progress. | | -| | - FALSE – default value. Will return an error if there is another action in progress on the same VNF or VM, unless the two actions are allowed in parallel based on a Request Management Model stored in APP-C. | | -| | The model allows some non-disruptive actions such as Lock, Unlock, CheckLock, and ActionStatus to be performed in conjunction with other actions. | | -| | | | -| | - "TTL": <0....N> - The timeout value is used to determine if the request timeout has been exceeded (i.e., if the TTL value is less than the current time minus the timestamp, the request is rejected). The value is in seconds. | | -| | | | -| | If no TTL value provided, the default/configurable TTL value is to be used. | | -+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ -| action | The action to be taken by APPC, for example: Test, Start | Yes | -| | | | -| | These are case-sensitive; e.g.,”Restart” is correct; “restart” is incorrect. | | -| | | | -| | ***NOTE:** The specific value for the action parameter is provided for each command. | | -+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ -| action-identifiers | A block containing the action arguments. These are used to specify the object upon which APPC LCM command is to operate. At least one action-identifier must be specified (note that vnf-id is mandatory). For actions that are at the VM level, the action-identifiers provided would be vnf-id and vserver-id. | Yes | -+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ -| service-instance-id | Identifies a specific service instance that the command refers to. When multiple APPC instances are used and applied to a subset of services, this will become significant. The field is mandatory when the vnf-id is empty. Currently not used. | No | -+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ -| vnf-id | Identifies the VNF instance to which this action is to be applied. Required for actions. | Yes | -+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ -| vnfc-name | Identifies the VNFC instance to which this action is to be applied. Required if the action applied to a specific VNFC. Currently not used. | No | -+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ -| vserver-id | Identifies a specific VM instance to which this action is to be applied. Required if the action applied to a specific VM. (Populate the vserver-id field with the UUID of the VM) | No | -+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ -| vf-module-id | Identifies a specific VF module to which this action is to be applied. Required if the action applied to a specific VF module. | No | -+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ -| payload | An action-specific open-format field. | No | -| | | | -| | The payload can be any valid JSON string value. JSON escape characters need to be added when an inner JSON string is included within the payload, for example: ``"{\\" vnf -host- ip | | -| | | | -| | -address\\": \\"<VNF-HOST-IP-ADDRESS>\\"}"``. | | -| | | | -| | The payload is typically used to provide parametric data associated with the command, such as a list of configuration parameters. | | -| | | | -| | Note that not all LCM commands need have a payload. | | -| | | | -| | ***NOTE:** See discussion below on the use of payloads for self-service actions. | | -+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ ++---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ +| **Field** | **Description** | **Required?** | ++===========================+=============================================================================================================================================================================================================================================================================================================================================================================+=====================+ +| input | The block that defines the details of the input to the command processing. Contains the common-header details. | Yes | ++---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ +| common- header | The block that contains the generic details about a request. | Yes | ++---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ +| timestamp | The time of the request, in ISO 8601 format, ZULU offset. For example: 2016-08-03T08:50:18.97Z. | Yes | +| | | | +| | APPC will reject the request if timestamp is in the future (due to clock error), or timestamp is too old (compared to TTL flag) | | ++---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ +| api-ver | Identifies the API version, in X.YY format, where X denotes the major version increased with each APPC release, and YY is the minor release version. | Yes | +| | | | +| | 2.00 should be used for all LCM API requests | | ++---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ +| originator-id | An identifier of the calling system limited to a length of 40 characters. | Yes | +| | | | +| | It can be used for addressing purposes, such as to return an asynchronous response to the correct destination, in particular where there are multiple consumers of APPC APIs. | | ++---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ +| request-id | The UUID for the request ID, limited to a length of 40 characters. The unique OSS/BSS identifier for the request ID that triggers the current LCM action. Multiple API calls can be made with the same request-id. | Yes | +| | | | +| | The request-id is stored throughout the operations performed during a single request. | | ++---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ +| sub-request-id | Uniquely identifies a specific LCM or control action, limited to a length of 40 characters. Persists throughout the life cycle of a single request. | No | ++---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ +| flags | Generic flags that apply to all LCM actions: | No | +| | | | +| | - "MODE" : | | +| | | | +| | - "EXCLUSIVE" - reject requests on this VNF while another request is in progress, or | | +| | | | +| | - "NORMAL" - allow requests (pending additional validations) on this VNF if there is another request is in progress. | | +| | | | +| | - "FORCE" : | | +| | - **TRUE** – forces APPC to process the request regardless of whether there is another request for the VNF or VM in progress. | | +| | - **FALSE** – default value. Will return an error if there is another action in progress on the same VNF or VM, unless the two actions are allowed in parallel based on a Request Management Model stored in APPC. The model allows some non-disruptive actions such as Lock, Unlock, CheckLock, and ActionStatus to be performed in conjunction with other actions. | | +| | | | +| | | | +| | - "TTL": <0....N> - The timeout value is used to determine if the request timeout has been exceeded (i.e., if the TTL value is less than the current time minus the timestamp, the request is rejected). The value is in seconds. | | +| | | | +| | If no TTL value provided, the default/configurable TTL value is to be used. | | ++---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ +| action | The action to be taken by APPC, for example: Test, Start | Yes | +| | | | +| | These are case-sensitive; e.g.,”Restart” is correct; “restart” is incorrect. | | +| | | | +| | ***NOTE:** The specific value for the action parameter is provided for each command. | | ++---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ +| action-identifiers | A block containing the action arguments. These are used to specify the object upon which APPC LCM command is to operate. At least one action-identifier must be specified (note that vnf-id is mandatory). For actions that are at the VM level, the action-identifiers provided would be vnf-id and vserver-id. | Yes | ++---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ +| service-instance-id | Identifies a specific service instance that the command refers to. When multiple APPC instances are used and applied to a subset of services, this will become significant. The field is mandatory when the vnf-id is empty. Currently not used. | No | ++---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ +| vnf-id | Identifies the VNF instance to which this action is to be applied. Required for actions. | Yes | ++---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ +| vnfc-name | Identifies the VNFC instance to which this action is to be applied. Required if the action applied to a specific VNFC. Currently not used. | No | ++---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ +| vserver-id | Identifies a specific VM instance to which this action is to be applied. Required if the action applied to a specific VM. (Populate the vserver-id field with the UUID of the VM) | No | ++---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ +| vf-module-id | Identifies a specific VF module to which this action is to be applied. Required if the action applied to a specific VF module. | No | ++---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ +| payload | An action-specific open-format field. | No | +| | | | +| | The payload can be any valid JSON string value. JSON escape characters need to be added when an inner JSON string is included within the payload, for example: | | +| | | | +| | ``"{\" vnf-host-ip-address\": \"<VNF-HOST-IP-ADDRESS>\"}"`` | | +| | | | +| | The payload is typically used to provide parametric data associated with the command, such as a list of configuration parameters. | | +| | | | +| | Note that not all LCM commands need have a payload. | | +| | | | +| | ***NOTE:** See discussion below on the use of payloads for self-service actions. | | ++---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ Request Processing and Validation Logic ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When a new request is received, APPC applies the following validation logic. For any failure, the request is rejected and an error (300 range) is returned. -1. If the request has timeout out (i.e., the difference between current +1. If the request has timeout (i.e., the difference between current time and the request timestamp value is greater than TTL value in request), a timeout error is returned. @@ -274,9 +274,7 @@ When a new request is received, APPC applies the following validation logic. For VNF level request would overlap with another request in progress). a. If there is no overlap between the new request and requests in - progress, the new request is accepted. For example, a Start - request on VM1 and a Stop request on VM2 can be running in - parallel. + progress, the new request is accepted. b. If there is overlap, then only special cases are allowed in parallel (for example, Audit and HealthCheck are allowed). @@ -387,7 +385,7 @@ The different responses are categorized as follows: **REJECT** Request rejected during processing due to invalid data, such as an - unsupported command or a non-existent service-instance-id. + unsupported command. **SUCCESS** @@ -562,11 +560,11 @@ Commands, or actions, may be currently supported on all VNF types or a limited s +------------------------+-----------+------------------+----------------+----------+------------------------------------------------------------+ | CheckLock | Yes | | | | Any | +------------------------+-----------+------------------+----------------+----------+------------------------------------------------------------+ -| Configure | Yes | | Yes | | Any (requires self-service onboarding) | +| Configure | Yes | | | | Any (requires self-service onboarding) | +------------------------+-----------+------------------+----------------+----------+------------------------------------------------------------+ | ConfigBackup | Yes | | | | Chef and Ansible only (requires self-service onboarding) | +------------------------+-----------+------------------+----------------+----------+------------------------------------------------------------+ -| ConfigModify | Yes | | Yes | | Any (requires self-service onboarding) | +| ConfigModify | Yes | | | | Any (requires self-service onboarding) | +------------------------+-----------+------------------+----------------+----------+------------------------------------------------------------+ | ConfigRestore | Yes | | | | Chef and Ansible only (requires self-service onboarding) | +------------------------+-----------+------------------+----------------+----------+------------------------------------------------------------+ @@ -723,7 +721,7 @@ Cinder is a Block Storage service for OpenStack. It's designed to present storag http://developer.openstack.org/api-ref/compute/. +--------------------------+----------------------------------------------------------+ -| **Target URL** | /restconf /operations/ appc-provider-lcm:attach-volume | +| **Target URL** | /restconf/operations/appc-provider-lcm:attach-volume | +--------------------------+----------------------------------------------------------+ | **Action** | AttachVolume | +--------------------------+----------------------------------------------------------+ @@ -736,15 +734,17 @@ Cinder is a Block Storage service for OpenStack. It's designed to present storag | -+-----------------------------+-----------------------------------------------------------------------------------------------------------------------------+--------------------+--------------------------------------------------------------------------------------------------------------------------------+ -| **Payload Parameter** | **Description** | **Required** | **Example** | -+=============================+=============================================================================================================================+====================+================================================================================================================================+ -| volumeId | The UUID of the volume to attach. | Yes | "volumeId": "a26887c6-c47b-4654- abb5-dfadf7d3f803", | -+-----------------------------+-----------------------------------------------------------------------------------------------------------------------------+--------------------+--------------------------------------------------------------------------------------------------------------------------------+ -| vm-id | The unique identifier (UUID) of the resource. For backwards- compatibility, this can be the self- link URL of the VM. | Yes | "vm-id": http://135.25.246.162:8774/v2/64a f07e991424b8e9e54eca27d5c0d48/ servers/b074cd1b-8d53-412e-a102- 351cc51ac10a" | -+-----------------------------+-----------------------------------------------------------------------------------------------------------------------------+--------------------+--------------------------------------------------------------------------------------------------------------------------------+ -| Identity-url | The identity URL used to access the resource | No | "identity-url": "http://135.25.246.162:5000/v2.0" | -+-----------------------------+-----------------------------------------------------------------------------------------------------------------------------+--------------------+--------------------------------------------------------------------------------------------------------------------------------+ ++-----------------------------+------------------------------------------------------+--------------------+---------------------------------------------------------------------------------------------------------------------------+ +| **Payload Parameter** | **Description** | **Required** | **Example** | ++=============================+======================================================+====================+===========================================================================================================================+ +| volumeId | The UUID of the volume to attach. | Yes | "volumeId": "a26887c6-c47b-4654-abb5-dfadf7d3f803", | ++-----------------------------+------------------------------------------------------+--------------------+---------------------------------------------------------------------------------------------------------------------------+ +| device | The device identifier | Yes | "device": "/dev/vdb" | ++-----------------------------+------------------------------------------------------+--------------------+---------------------------------------------------------------------------------------------------------------------------+ +| vm-id | TThe self- link URL of the VM. | Yes | "vm-id": http://135.25.246.162:8774/v2/64af07e991424b8e9e54eca27d5c0d48/servers/b074cd1b-8d53-412e-a102-351cc51ac10a" | ++-----------------------------+------------------------------------------------------+--------------------+---------------------------------------------------------------------------------------------------------------------------+ +| Identity-url | The identity URL used to access the resource | Yes | "identity-url": "http://135.25.246.162:5000/v2.0" | ++-----------------------------+------------------------------------------------------+--------------------+---------------------------------------------------------------------------------------------------------------------------+ AttachVolume Response: ^^^^^^^^^^^^^^^^^^^^^^ @@ -776,7 +776,7 @@ The Audit action does not require any payload parameters. +------------------------------+------------------------------------------------------+ -| **Target URL** | /restconf /operations/ appc-provider-lcm:audit | +| **Target URL** | /restconf/operations/appc-provider-lcm:audit | +------------------------------+------------------------------------------------------+ | **Action** | Audit | +------------------------------+------------------------------------------------------+ @@ -851,20 +851,20 @@ response. { "output": { "status": { - "code": <RESULT\_CODE>, "message": "<RESULT\_MESSAGE>" + "code": <RESULT_CODE>, "message": "<RESULT_MESSAGE>" }, "common-header": { - "api-ver": "<API\_VERSION>", - "request-id": "<ECOMP\_REQUEST\_ID>", "originator-id": - "<ECOMP\_SYSTEM\_ID>", - "sub-request-id": "<ECOMP\_SUBREQUEST\_ID>", "timestamp": + "api-ver": "<API_VERSION>", + "request-id": "<ECOMP\_REQUEST_ID>", "originator-id": + "<ECOMP_SYSTEM_ID>", + "sub-request-id": "<ECOMP_SUBREQUEST_ID>", "timestamp": "2016-08-08T23:09:00.11Z", "flags": { - "ttl": <TTL\_VALUE>, "force": "<TRUE\|FALSE>", - "mode": "<EXCLUSIVE\|NORMAL>" + "ttl": <TTL_VALUE>, "force": "<TRUE|FALSE>", + "mode": "<EXCLUSIVE|NORMAL>" } }, - "locked": "<TRUE\|FALSE>" + "locked": "<TRUE|FALSE>" } @@ -893,38 +893,43 @@ A failed Configure action returns a failure response and the specific failure me | -+---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+-----------------------------------------------------------------+ -| **Payload Parameter** | **Description** | **Required?** | **Example** | -| | | | | -+=================================+============================================================================================================================================================================================================================================================================================================+=====================+=================================================================+ -| request- parameters | vnf-host-ip-address: required if Netconf or other direct interface to the VNF. Optionally, it can be provided for all requests. | Yes | | -| | | | "payload": | -| | vnfc-type: if request is vnfc specific | | "{\"request-parameters | -| | | | \": { | -| | template-name: if specific template needs to be specified (otherwise, the most recent default template is used). | | \"vnf-host-ip-address\": | -| | | | \”value\”, | -| | | | \”vnfc-type\”: \”value\”’ | -| | | | \”template-name\”: \”name\”, | -| | | | } | -| | | | | -| | | | | -| | | | | -| | | | | -| | | | | -| | | | | -| | | | | -| | | | | -+---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ | -| configuration- parameters | A set of instance specific configuration parameters should be specified. If provided, APPC replaces variables in the configuration template with the values supplied. | No | \"configuration- parameters\": {\"<CONFIG- PARAMS>\"} | -+---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+-----------------------------------------------------------------+ ++---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+-----------------------------------------------------------------+ +| **Payload Parameter** | **Description** | **Required?** | **Example** | +| | | | | ++=================================+================================================================================================================================================================================================================+=====================+=================================================================+ +| request-parameters | vnf-host-ip-address: optional if Netconf or other direct interface to the VNF. If not provided, APPC will look for the host-ip-address in the A&AI VNF oam ipv4 address field. | No | | +| | | | "payload": | +| | vnfc-type: must be included if template is vnfc specific | | "{ \\"request-parameters | +| | | | \\": { | +| | | | \\"vnf-host-ip-address\\": | +| | | | \\”value\\”, | +| | | | \\”vnfc-type\\”: \\”value\\”’ | +| | | | } | +| | | | | +| | | | | +| | | | | +| | | | | +| | | | | +| | | | | +| | | | | +| | | | | +| | | | | ++---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ | +| configuration-parameters | A set of instance specific configuration parameters should be specified. If provided, APPC replaces variables in the configuration template with the values supplied. | No | \\"configuration- parameters\\": {\\"<CONFIG- PARAMS>\\"} | ++---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+-----------------------------------------------------------------+ Configure Response ^^^^^^^^^^^^^^^^^^ -The Configure response returns an indication of success or failure of the request. If successful, the return payload contains the ‘upload\_config\_id’ and values for any records created. In addition, the configuration is sent to the ONAP Data Router bus which may be received by an external configuration storage system. +The Configure response returns an indication of success or failure of the request. -SO is creating the VNFC records in A&AI. APPC is updating the VNFC status. +**Success:** A successful Configure returns a success status code 400. +**Failure:** A failed Configure returns a failure code 401 and the failure message. + +If successful, the return payload contains the ‘upload_config_id’ and values for any records created in the APPC DB. In addition, the configuration is sent to the ONAP Data Router bus which may be received by an external configuration storage system. + +If APPC in unable to update A&AI with the VNFC records, a 501 intermediate error message returned prior to the final 400 or 401 success message. ConfigModify ------------ @@ -942,7 +947,7 @@ Request Structure: +--------------------------+--------------------------------------------------------+ | **Action-Identifiers** | vnf-id | +--------------------------+--------------------------------------------------------+ -| **Payload Parameters** | request-parameters, configuration-parameters | +| **Payload Parameters** | request-parameters, configuration-parameters | +--------------------------+--------------------------------------------------------+ | **Revision History** | Unchanged in this release. | +--------------------------+--------------------------------------------------------+ @@ -953,13 +958,14 @@ Request Payload Parameters: | **Payload Parameter** | **Description** | **Required?** | **Example** | +=========================+========================================+=================+=======================================================+ | request-parameters | vnf-host-ip-address: optional if | No | "payload": | -| | Netconf or other direct interface | | "{\\"request-parameters | -| | to the VNF. If not provided, it is | | \\": { | -| | obtained from A&AI | | \\"vnf-host-ip-address\\": | -| | | | \\”value\\ | -| | vnfc-type: if request is vnfc | | }, | -| | specific | | | -| | | | {\\"configuration- parameters\\": {\\"name1\\": | +| | Netconf or other direct interface | | "{\\"request-parameters \\": | +| | to the VNF. If not provided, it is | | {\\"vnf-host-ip-address\\": \\”value\\", | +| | obtained from A&AI | | \\”vnfc-type\\”: \\”value\\” | +| | | | } | +| | | | | +| | vnfc-type: must be included if template| | | +| | is vnfc specific | | | +| | | | \\"configuration- parameters\\": {\\"name1\\": | | | | | \\”value1\\”,\\"name2\\": | | | | | \\”value2\\” | | | | | } | @@ -975,7 +981,7 @@ ConfigModify Response **Success:** A successful ConfigModify returns a success status code 400. -Note: The return payload contains the ‘upload_config_id’ and values associated with the configuration stored in the APPC DB. In addition, the configuration is sent to the message bus which may be received by an external configuration storage system. +If successful, the return payload contains the ‘upload_config_id’ and values associated with the configuration stored in the APPC DB. In addition, the configuration is sent to the message bus which may be received by an external configuration storage system. **Failure:** A failed ConfigModify returns a failure code 401 and the failure message. @@ -1002,24 +1008,28 @@ A failed ConfigBackup action returns a failure response code and the specific fa | -+---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+-----------------------------------------------------------------+ -| **Payload Parameter** | **Description** | **Required?** | **Example** | -+=================================+====================================================================================================================================================================================+=====================+=================================================================+ -| request-parameters | Not used. This request is limited to Ansible and Chef only. | No | "payload": | -| | | | \"configuration-parameters\": {\"<CONFIG-PARAMS>\"} | -| | | | | -| | | | | -| | | | | -| | | | | -+---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ | -| configuration-parameters | A set of instance specific configuration parameters should be specified, as required by the Chef cookbook or Ansible playbook. | No | | -+---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+-----------------------------------------------------------------+ ++---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+-------------------------------------------------------------------+ +| **Payload Parameter** | **Description** | **Required?** | **Example** | ++=================================+====================================================================================================================================================================================+=====================+===================================================================+ +| request-parameters | Not used. This request is limited to Ansible and Chef only. | No | "payload": \\"configuration-parameters\\": {\\"<CONFIG-PARAMS>\\"}| +| | | | | +| | | | | +| | | | | +| | | | | +| | | | | ++---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ | +| configuration-parameters | A set of instance specific configuration parameters should be specified, as required by the Chef cookbook or Ansible playbook. | No | | ++---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+-------------------------------------------------------------------+ ConfigBackup Response ^^^^^^^^^^^^^^^^^^^^^ The ConfigBackup response returns an indication of success or failure of the request. +**Success:** A successful ConfigBackup returns a success status code 400. +**Failure:** A failed ConfigBackup returns a failure code 401 and the failure message. + + ConfigRestore ------------- @@ -1030,7 +1040,7 @@ A successful ConfigRestore request returns a success response. A failed ConfigRestore action returns a failure response code and the specific failure message in the response block. +------------------------------+------------------------------------------------------------------------------------------+ -| **Target URL** | /restconf/operations/appc-provider-lcm:configrestore | +| **Target URL** | /restconf/operations/appc-provider-lcm:config-restore | +------------------------------+------------------------------------------------------------------------------------------+ | **Action** | ConfigRestore | +------------------------------+------------------------------------------------------------------------------------------+ @@ -1047,7 +1057,7 @@ A failed ConfigRestore action returns a failure response code and the specific f | **Parameter** | **Description** | **Required?** | **Example** | +=================================+====================================================================================================================================================================================+=====================+=================================================================+ | request-parameters | Not used. This request is limited to Ansible and Chef only. | No | "payload": | -| | | | \"configuration-parameters\": {\"<CONFIG- PARAMS>\"} | +| | | | \\"configuration-parameters\\": {\\"<CONFIG- PARAMS>\\"} | +---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ | | configuration-parameters | A set of instance specific configuration parameters should be specified, as required by the Chef cookbook or Ansible playbook. | No | | +---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+-----------------------------------------------------------------+ @@ -1055,7 +1065,12 @@ A failed ConfigRestore action returns a failure response code and the specific f ConfigRestore Response ^^^^^^^^^^^^^^^^^^^^^^ -The ConfigRestore response returns an indication of success or failure of the request. +**Success:** A successful ConfigRestore returns a success status code 400. + +If successful, the return payload contains the ‘upload_config_id’ and values associated with the configuration stored in the APPC DB. In addition, the configuration is sent to the ONAP Data Router bus which may be received by an external configuration storage system. + +**Failure:** A failed ConfigRestore returns a failure code 401 and the failure message. + ConfigScaleOut @@ -1071,7 +1086,7 @@ This action is supported via the Netconf (limited to configuration changes), Che | +------------------------------+------------------------------------------------------------------------------------------+ -| **Target URL** | /restconf /operations/ appc-provider-lcm: config-scale-out | +| **Target URL** | /restconf /operations/appc-provider-lcm:config-scale-out | +------------------------------+------------------------------------------------------------------------------------------+ | **Action** | ConfigScaleOut | +------------------------------+------------------------------------------------------------------------------------------+ @@ -1088,17 +1103,17 @@ This action is supported via the Netconf (limited to configuration changes), Che | **Payload Parameter** | **Description** | **Required?** | **Example** | +=================================+==================================================================================================================================================================+=====================+=============================================+ | request-parameters | vnf-host-ip-address: optional if Netconf or other direct interface to the VNF. If not provided, the vnf-host-ip-address will be obtained from A&AI. | No | "payload": | -| +------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ "{\"request-parameters \": | +| +------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ "{\\"request-parameters \\": | | | vf-module-id: used to determine the A&AI VM inventory associated with ConfigScaleOut. | Yes | { | -| +------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ \"vnf-host-ip-address\": | -| | controller-template-id: optional. This is a unique identifier that will identify the template associated with the ConfigScaleOut. | | \”value\”, | -| | Will be needed if A&AI does not contain the template identifier. | No | \”vf-module-id\”: \”value\”, | -+---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ \”controller-template-id\”: | -| configuration-parameters | A set of instance specific configuration parameters should be specified. If provided, APP-C replaces variables in the configuration template with the | No | \”value\” | +| +------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ \\"vnf-host-ip-address\\": | +| | controller-template-id: optional. This is a unique identifier that will identify the template associated with the ConfigScaleOut. | | \\”value\\”, | +| | Will be needed if A&AI does not contain the template identifier. | No | \\”vf-module-id\\”: \\”value\\”, | ++---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ \\”controller-template-id\\”: | +| configuration-parameters | A set of instance specific configuration parameters should be specified. If provided, APP-C replaces variables in the configuration template with the | No | \\”value\\” | | | values supplied. | | } | | | | | | -| | | | \"configuration-parameters\": | -| | | | {\"<CONFIG- PARAMS>\"} | +| | | | \\"configuration-parameters\\": | +| | | | {\\"<CONFIG- PARAMS>\\"} | | | | | | +---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+---------------------------------------------+ @@ -1125,7 +1140,7 @@ Cinder is a Block Storage service for OpenStack. It's designed to present storag NOTE: The command implementation is based on Openstack functionality. For further details, see http://developer.openstack.org/api-ref/compute/. +--------------------------+----------------------------------------------------------+ -| **Target URL** | /restconf /operations/ appc-provider-lcm:detach-volume | +| **Target URL** | /restconf/operations/appc-provider-lcm:detach-volume | +--------------------------+----------------------------------------------------------+ | **Action** | DetachVolume | +--------------------------+----------------------------------------------------------+ @@ -1138,15 +1153,15 @@ NOTE: The command implementation is based on Openstack functionality. For furthe Request Payload Parameters: -+-----------------------------+-----------------------------------------------------------------------------------------------------------------------------+--------------------+--------------------------------------------------------------------------------------------------------------------------------+ -| **Payload Parameter** | **Description** | **Required** | **Example** | -+=============================+=============================================================================================================================+====================+================================================================================================================================+ -| volumeId | The UUID of the volume to detach. | Yes | "volumeId": "a26887c6-c47b-4654- abb5-dfadf7d3f803", | -+-----------------------------+-----------------------------------------------------------------------------------------------------------------------------+--------------------+--------------------------------------------------------------------------------------------------------------------------------+ -| vm-id | The unique identifier (UUID) of the resource. For backwards- compatibility, this can be the self- link URL of the VM. | Yes | "vm-id": http://135.25.246.162:8774/v2/64a f07e991424b8e9e54eca27d5c0d48/ servers/b074cd1b-8d53-412e-a102- 351cc51ac10a" | -+-----------------------------+-----------------------------------------------------------------------------------------------------------------------------+--------------------+--------------------------------------------------------------------------------------------------------------------------------+ -| Identity-url | The identity URL used to access the resource | No | "identity-url": "http://135.25.246.162:5000/v2.0" | -+-----------------------------+-----------------------------------------------------------------------------------------------------------------------------+--------------------+--------------------------------------------------------------------------------------------------------------------------------+ ++-----------------------------+----------------------------------------------------------------+--------------------+--------------------------------------------------------------------------------------------------------------------------------+ +| **Payload Parameter** | **Description** | **Required** | **Example** | ++=============================+================================================================+====================+================================================================================================================================+ +| volumeId | The UUID of the volume to detach. | Yes | "volumeId": "a26887c6-c47b-4654-abb5-dfadf7d3f803" | ++-----------------------------+----------------------------------------------------------------+--------------------+--------------------------------------------------------------------------------------------------------------------------------+ +| vm-id | The self- link URL of the VM. | Yes | "vm-id": http://135.25.246.162:8774/v2/64af07e991424b8e9e54eca27d5c0d48/servers/b074cd1b-8d53-412e-a102-351cc51ac10a" | ++-----------------------------+----------------------------------------------------------------+--------------------+--------------------------------------------------------------------------------------------------------------------------------+ +| Identity-url | The identity URL used to access the resource | Yes | "identity-url": "http://135.25.246.162:5000/v2.0" | ++-----------------------------+----------------------------------------------------------------+--------------------+--------------------------------------------------------------------------------------------------------------------------------+ DetachVolume Response: ^^^^^^^^^^^^^^^^^^^^^^ @@ -1155,65 +1170,72 @@ DetachVolume Response: **Failure:** A failed DetachVolume returns a failure code 401 and the failure message. Failure messages can include: -- badRequest -- unauthorized -- forbidden -- itemNotFound -- conflict + - badRequest + - unauthorized + - forbidden + - itemNotFound + - conflict Evacuate -------- -Evacuates a specified VM from its current host to another. After a successful evacuate, a rebuild VM is performed if a snapshot is available (and the VM boots from a snapshot. +Evacuates a specified VM from its current host to another. After a successful evacuate, a rebuild VM is performed if a snapshot is available (and the VM boots from a snapshot). The host on which the VM resides needs to be down. -If the node is not specified in the request, it will be selected by relying on internal rules to evacuate. The Evacuate action will fail if the specified target host is not UP/ENABLED. +If the target host is not specified in the request, it will be selected by relying on internal rules to evacuate. The Evacuate action will fail if the specified target host is not UP/ENABLED. -After Evacuate, the rebuild VM can be disabled by setting the optional `rebuild-vm <#_bookmark43>`__ parameter to false. +After Evacuate, the rebuild VM can be disabled by setting the optional `rebuild-vm` parameter to false. A successful Evacuate action returns a success response. A failed Evacuate action returns a failure. **NOTE:** The command implementation is based on Openstack functionality. For further details, see http://developer.openstack.org/api-ref/compute/. -+------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| **Target URL** | /restconf/operations/appc-provider-lcm:evacuate | -+------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| **Action** | Evacuate | -+------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| **Action-identifiers** | Vnf-id, vserver-id | -+------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| **Payload Parameters** | `vm-id <#_bookmark40>`__, `identity-url <#_bookmark41>`__, `tenant-id <#_bookmark42>`__, `rebuild-vm <#_bookmark43>`__, `targethost-id <#_bookmark44>`__ | -+------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| **Revision History** | Unchanged in this release. | -+------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ ++------------------------------+-------------------------------------------------------------------------+ +| **Target URL** | /restconf/operations/appc-provider-lcm:evacuate | ++------------------------------+-------------------------------------------------------------------------+ +| **Action** | Evacuate | ++------------------------------+-------------------------------------------------------------------------+ +| **Action-identifiers** | Vnf-id, vserver-id | ++------------------------------+-------------------------------------------------------------------------+ +| **Payload Parameters** | vm-id, identity-url, tenant-id, rebuild-vm, targethost-id | ++------------------------------+-------------------------------------------------------------------------+ +| **Revision History** | Unchanged in this release. | ++------------------------------+-------------------------------------------------------------------------+ | +----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+---------------------------------------+ | **Parameter** | **Description** | **Required?** | **Example** | +======================+==================================================================================================================================================================================+=====================+=======================================+ -| vm-id | The unique identifier (UUID) of the resource. For backwards- compatibility, this can be the self- link URL of the VM. | Yes | "payload": | -| | | | "{\"vm-id\": \"<VM-ID> | -| | | | \", | -| | | | \"identity-url\": | -| | | | \"<IDENTITY-URL>\", | -| | | | \"tenant-id\\": \"<TENANT-ID> | -| | | | \", | -| | | | \"rebuild-vm\": \"false\", | -| | | | \"targethost-id\": | -| | | | \"nodeblade7\"}" | +| vm-id | The unique identifier (UUID) of the resource. For backwards- compatibility, this can be the self-link URL of the VM. | Yes | "payload": | +| | | | "{\\"vm-id\\": \\"<VM-ID> | +| | | | \\", | +| | | | \\"identity-url\\": | +| | | | \\"<IDENTITY-URL>\\", | +| | | | \\"tenant-id\\": \\"<TENANT-ID> | +| | | | \\", | +| | | | \\"rebuild-vm\\": \\"false\\", | +| | | | \\"targethost-id\\": | +| | | | \\"nodeblade7\\"}" | +----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ | -| identity- url | The identity URL used to access the resource | No | | +| identity-url | The identity URL used to access the resource | Yes | | +----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ | -| tenant-id | The id of the provider tenant that owns the resource | No | | +| tenant-id | The id of the provider tenant that owns the resource | Yes | | +----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ | | rebuild- vm | A boolean flag indicating if a Rebuild is to be performed after an Evacuate. The default action is to do a Rebuild. It can be switched off by setting the flag to "false". | No | | +----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ | | targethost- id | A target hostname indicating the host the VM is evacuated to. By default, the cloud determines the target host. | No | | +----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+---------------------------------------+ +Evacuate Response: +^^^^^^^^^^^^^^^^^^ +**Success:** A successful Evacuate returns a success status code 400. +**Failure:** A failed Evacuate returns a failure code 401 and the failure message. + + + HealthCheck ----------- @@ -1234,33 +1256,28 @@ The VNF level HealthCheck is a check over the entire scope of the VNF. The VNF m | **Revision History** | Unchanged in this release | +------------------------------+-----------------------------------------------------------+ -| + +Request Payload Parameters: +---------------------+-----------------------------------+---------------------+-------------------------------------+ | **Parameter** | **Description** | **Required?** | **Example** | +=====================+===================================+=====================+=====================================+ -| host-ip-address | Required only if REST | No | | -| | service. This is the ip | | | -| | address associated with the | | | +| request-parameters | host-ip-address - | No | "payload": | +| | Required only if REST | | "{\\"request-parameters \\": | +| | service. This is the ip | | "{\\"host-ip-address\\": | +| | address associated with the | | \\"10.222.22.2\\" }" | | | VM running the REST | | | | | service. | | | -+---------------------+-----------------------------------+---------------------+ | -| port-number | Required only if REST | No | "payload": | -| | service. This is the port | | "{\\"host-ip-address\\": | -| | number associated with the | | \\"10.222.22.2\\", | -| | REST service. | | \\”port-number\\”: \\”32\\”}" | -| | | | | +---------------------+-----------------------------------+---------------------+-------------------------------------+ HealthCheck Response ^^^^^^^^^^^^^^^^^^^^ -The Healthcheck returns a 200 OK if the test completes. A JSON object is returned indicating state (healthy, unhealthy), scope identifier, time-stamp and one or more blocks containing info and fault information. +**Success:** The HealthCheck returns a 400 success message if the test completes. A JSON payload is returned indicating state (healthy, unhealthy), scope identifier, time-stamp and one or more blocks containing info and fault information. Examples:: - 200 { "identifier": "scope represented", "state": "healthy", @@ -1268,7 +1285,6 @@ The Healthcheck returns a 200 OK if the test completes. A JSON object is returne } - 200 { "identifier": "scope represented", "state": "unhealthy", @@ -1283,7 +1299,7 @@ The Healthcheck returns a 200 OK if the test completes. A JSON object is returne "time": "01-01-1000:0000" } -If the VNF is unable to run the HealthCheck, it returns a standard http error code and message. APPC returns the error code 401 and the http error message. +**Failure:** If the VNF is unable to run the HealthCheck. APP-C returns the error code 401 and the http error message. Lock @@ -1297,10 +1313,10 @@ Lock is a command intended for APPC and does not execute an actual VNF command. When a VNF is locked, any subsequent sequential commands with same request-id will be accepted. Commands associated with other request-ids will be rejected. -The Lock command returns only one final response with the status of the request processing. - APPC locks the target VNF during any VNF command processing. If a lock action is then requested on that VNF, it will be rejected because the VNF was already locked, even though no actual lock command was explicitly invoked. +The lock automatically clears after 900 seconds (15 minutes). This 900 second value can be adjusted in the properties file + +------------------------------+---------------------------------------------------+ | **Target URL** | /restconf/operations/appc-provider-lcm:lock | +------------------------------+---------------------------------------------------+ @@ -1313,6 +1329,14 @@ APPC locks the target VNF during any VNF command processing. If a lock action is | **Revision History** | Unchanged in this release. | +------------------------------+---------------------------------------------------+ +Lock Response +^^^^^^^^^^^^^ + +The Lock returns a 400 Success response if the Lock is successfully applied. + +The Lock returns a 401 Failure response with the failure message if the Lock is not successful. + + Migrate ------- @@ -1324,9 +1348,6 @@ Migrate suspends the guest virtual machine, and moves an image of the guest virt The migrate action will leave the VM in the same Openstack state the VM had been in prior to the migrate action. If a VM was stopped before migration, a separate VM-level restart command would be needed to restart the VM after migration. -A successful Migrate action returns a success response. - -A failed Migrate action returns a failure and the failure messages in the response payload block. **NOTE:** The command implementation is based on Openstack functionality. For further details, see http://developer.openstack.org/api-ref/compute/. @@ -1340,28 +1361,36 @@ A failed Migrate action returns a failure and the failure messages in the respon +--------------------------------+-----------------------------------------------------------------------------------------------+ | **Action-Identifiers** | Vnf-id, vserver-id | +--------------------------------+-----------------------------------------------------------------------------------------------+ -| \ **Payload Parameters** | `vm-id <#_bookmark52>`__, `identity-url <#_bookmark54>`__, `tenant-id <#_bookmark55>`__ | +| **Payload Parameters** | vm-id, identity-url, tenant-id | +--------------------------------+-----------------------------------------------------------------------------------------------+ | **Revision History** | Unchanged in this release. | +--------------------------------+-----------------------------------------------------------------------------------------------+ Payload Parameters -+---------------------+-------------------------------------------------------------------------+---------------------+----------------------------------------+ -| **Parameter** | **Description** | **Required?** | **Example** | -+=====================+=========================================================================+=====================+========================================+ -| vm-id | The unique identifier (UUID) of | Yes | | -| | the resource. For backwards- compatibility, this can be the self- | | | -| | link URL of the VM. | | "payload": | -| | | | "{\\"vm-id\": \\"<VM-ID>\\", | -| | | | \\"identity-url\\": | -| | | | \\"<IDENTITY-URL>\\", | -+---------------------+-------------------------------------------------------------------------+---------------------+ \\"tenant-id\\": \\"<TENANT- | -| identity- url | The identity url used to access the resource | No | ID>\\"}" | -| | | | | -+---------------------+-------------------------------------------------------------------------+---------------------+ | -| tenant-id | The id of the provider tenant that owns the resource | No | | -+---------------------+-------------------------------------------------------------------------+---------------------+----------------------------------------+ ++---------------------+-------------------------------------------------------------------------+---------------------+-----------------------------------------------+ +| **Parameter** | **Description** | **Required?** | **Example** | ++=====================+=========================================================================+=====================+===============================================+ +| vm-id | The unique identifier (UUID) of | Yes | | +| | the resource. For backwards- compatibility, this can be the self- | | | +| | link URL of the VM. | | "payload": | +| | | | "{\\"vm-id\\": \\"<VM-ID>\\", | +| | | | \\"identity-url\\": | +| | | | \\"<IDENTITY-URL>\\", | ++---------------------+-------------------------------------------------------------------------+---------------------+ \\"tenant-id\\": \\"<TENANT-ID>\\"}" | +| identity- url | The identity url used to access the resource | Yes | | +| | | | | ++---------------------+-------------------------------------------------------------------------+---------------------+ | +| tenant-id | The id of the provider tenant that owns the resource | Yes | | ++---------------------+-------------------------------------------------------------------------+---------------------+-----------------------------------------------+ + + +Migrate Response +^^^^^^^^^^^^^^^^ + +**Success:** A successful Migrate returns a success status code 400. + +**Failure:** A failed Migrate returns a failure code 401 and the failure message. QuiesceTraffic @@ -1390,7 +1419,7 @@ Request Payload Parameters: +-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+------------------------------------------------+ | **Parameter** | **Description** | **Required?** | **Example** | +=======================+======================================================================================================================================================================================================+=====================+================================================+ -| operations- timeout | This is the maximum time in seconds that the command will run before APPC returns a timeout error. If the APPC template has a lower timeout value, the APPC template timeout value is applied. | Yes | "payload": | +| operations-timeout | This is the maximum time in seconds that the command will run before APPC returns a timeout error. If the APPC template has a lower timeout value, the APPC template timeout value is applied. | Yes | "payload": | | | | | "{\\"operations-timeout\\": \\"3600\\"}” | +-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+------------------------------------------------+ @@ -1416,9 +1445,10 @@ Recreates a target VM instance to a known, stable state. Rebuild calls an OpenStack command immediately and therefore does not expect any prerequisite operations to be performed, such as shutting off a VM. -Rebuild VM uses the latest snapshot by default; if there are no snapshots it uses the (original) Glance image for the rebuild. APPC rejects a rebuild request if it determines the VM boots from a Cinder Volume. +Rebuild VM uses the snapshot provided by the snapshot-id (if provided). If not provided, the latest snapshot is used. If there are no snapshots, it uses the (original) Glance image. + +APPC rejects a rebuild request if it determines the VM boots from a Cinder Volume -A successful rebuild returns a success response and the rebuild details in the response payload block. A failed rebuild returns a failure and the failure messages in the response payload block. **NOTE:** The command implementation is based on Openstack functionality. For further details, see http://developer.openstack.org/api-ref/compute/. @@ -1432,7 +1462,7 @@ A successful rebuild returns a success response and the rebuild details in the r +------------------------------+-----------------------------------------------------------------------------------------------+ | **Action-identifiers** | Vnf-id, vserver-id | +------------------------------+-----------------------------------------------------------------------------------------------+ -| **Payload Parameters** | `vm-id <#_bookmark52>`__, `identity-url <#_bookmark54>`__, `tenant-id <#_bookmark55>`__ | +| **Payload Parameters** | See table below | +------------------------------+-----------------------------------------------------------------------------------------------+ | **Revision History** | Unchanged in this release. | +------------------------------+-----------------------------------------------------------------------------------------------+ @@ -1451,15 +1481,22 @@ Payload Parameters | | | | \\"identity-url\\": | | | | | \\"<IDENTITY-URL>\\", | | | | | \\"tenant-id\\": \\"<TENANT- ID>\\"}" | ++-----------------+-----------------------------------------------+-----------------+ \\"snapshot-id\\": \\"<SNAPSHOT- ID>\\" | +| identity- url | The identity url used to access the | Yes | }" | +| | resource. | | | +-----------------+-----------------------------------------------+-----------------+ | -| identity- url | The identity url used to access the | No | | -| | resource | | | +| tenant-id | The id of the provider tenant that owns | Yes | | +| | the resource. | | | +-----------------+-----------------------------------------------+-----------------+ | -| tenant-id | The id of the provider tenant that owns | No | | -| | the resource | | | +| snapshot-id | The snapshot-id of a previously saved image. | No | | +-----------------+-----------------------------------------------+-----------------+-----------------------------------------+ +Rebuild Response +^^^^^^^^^^^^^^^^ +**Success:** A successful Rebuild returns a success status code 400. + +**Failure:** A failed Rebuild returns a failure code 401 and the failure message. Restart ------- @@ -1473,7 +1510,7 @@ Use the Restart command to restart a VM. +------------------------------+-----------------------------------------------------------------------------------------------------------------+ | **Action** | Restart | +------------------------------+-----------------------------------------------------------------------------------------------------------------+ -| **Action-identifiers** | vnf-id and vserver-id are required. | +| **Action-identifiers** | vnf-id and vserver-id are required | +------------------------------+-----------------------------------------------------------------------------------------------------------------+ | **Payload Parameters** | See table below | +------------------------------+-----------------------------------------------------------------------------------------------------------------+ @@ -1487,12 +1524,12 @@ Payload Parameters for **VM Restart** +=====================+=========================================================================+=====================+====================================+ | vm-id | The unique identifier (UUID) of | Yes | | | | the resource. For backwards- compatibility, this can be the self- | | | -| | link URL of the VM. | | "payload": | +| | link URL of the VM | | "payload": | | | | | "{\\"vm-id\\": \\"<VM-ID>\\", | | | | | \\"identity-url\\": | +---------------------+-------------------------------------------------------------------------+---------------------+ \\"<IDENTITY-URL>\\", | -| identity- url | The identity url used to access the resource | No | \"tenant-id\": \"<TENANT- | -| | | | ID>\"}" | +| identity- url | The identity url used to access the resource | No | \\"tenant-id\\": \\"<TENANT- | +| | | | ID>\\"}" | +---------------------+-------------------------------------------------------------------------+---------------------+ | | tenant-id | The id of the provider tenant that owns the resource | No | | +---------------------+-------------------------------------------------------------------------+---------------------+------------------------------------+ @@ -1535,7 +1572,7 @@ Creates a snapshot of a VM. The Snapshot command returns a customized response containing a reference to the newly created snapshot instance if the action is successful. -This command can be applied to any VNF type. The only restriction is that the particular VNF should be built based on the generic heat stack. +This command can be applied to a VM in any VNF type. The only restriction is that the particular VNF should be built based on the generic heat stack. Note: Snapshot is not reliable unless the VM is in a stopped, paused, or quiesced (no traffic being processed) status. It is up to the caller to ensure that the VM is in one of these states. @@ -1546,9 +1583,9 @@ Note: Snapshot is not reliable unless the VM is in a stopped, paused, or quiesce +------------------------------+-----------------------------------------------------------------------------------------------------+ | **Action** | Snapshot | +------------------------------+-----------------------------------------------------------------------------------------------------+ -| **Action-identifiers** | Vnf-id is required. If the snapshot is for a single VM, then the vserver-id is also required. | +| **Action-identifiers** | vnf-id, vserver-id | +------------------------------+-----------------------------------------------------------------------------------------------------+ -| **Payload Parameters** | `vm-id <#_bookmark52>`__, `identity-url <#_bookmark54>`__, `tenant-id <#_bookmark55>`__ | +| **Payload Parameters** | vm-id, identity-url, tenant-id | +------------------------------+-----------------------------------------------------------------------------------------------------+ | **Revision History** | Unchanged in this release. | +------------------------------+-----------------------------------------------------------------------------------------------------+ @@ -1558,14 +1595,14 @@ Payload Parameters +---------------------+-------------------------------------------------------------------------+---------------------+----------------------------------------+ | **Parameter** | **Description** | **Required?** | **Example** | +=====================+=========================================================================+=====================+========================================+ -| vm-id | The unique identifier (UUID) of | Yes | | -| | the resource. For backwards- compatibility, this can be the self- | | "payload": | -| | link URL of the VM. | | "{\\"vm-id\": \\"<VM-ID> | -| | | | \\", | +| vm-id | The self-link URL of the VM | Yes | | +| | | | "payload": | +| | | | "{\\"vm-id\\": \\"<VM-ID>\\", | | | | | \\"identity-url\\": | | | | | \\"<IDENTITY-URL>\\", | -+---------------------+-------------------------------------------------------------------------+---------------------+ \\"tenant-id\\": \\"<TENANT- | -| identity- url | The identity url used to access the resource | No | ID>\\"}" | +| | | | \\"tenant-id\\":\\"<TENANT-ID>\\"}"| ++---------------------+-------------------------------------------------------------------------+---------------------+ | +| identity- url | The identity url used to access the resource | No | | | | | | | +---------------------+-------------------------------------------------------------------------+---------------------+ | | tenant-id | The id of the provider tenant that owns the resource | No | | @@ -1576,20 +1613,13 @@ Snapshot Response The Snapshot command returns an extended version of the LCM response. -The Snapshot response conforms to the `standard response format <#_bookmark5>`__, but has the following additional field. - -Additional Parameters +The Snapshot response conforms to the standard response format. -+---------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------+---------------------------------------+ -| **Parameter** | **Description** | **Required** | **?Example** | -+=====================+========================================================================================================================================================+====================+=======================================+ -| snapshot-id | The snapshot identifier created by cloud host. This identifier will be returned only in the final success response returned via the message bus. | No | "snapshot-id": "<SNAPSHOT\_ID>" | -+---------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------+---------------------------------------+ Start ----- -Use the Start command to start a VNF, VF-Module, or VM that is stopped or not running. +Use the Start command to start a VM that is stopped. **NOTE:** The command implementation is based on Openstack functionality. For further details, see http://developer.openstack.org/api-ref/compute/. @@ -1600,7 +1630,7 @@ Use the Start command to start a VNF, VF-Module, or VM that is stopped or not ru +------------------------------+--------------------------------------------------------------------------------------------------------------------------------+ | **Action-identifiers** | vnf-id and vserver-id are required | +------------------------------+--------------------------------------------------------------------------------------------------------------------------------+ -| **Payload Parameters** | See below | +| **Payload Parameters** | See table below | +------------------------------+--------------------------------------------------------------------------------------------------------------------------------+ | **Revision History** | Unchanged in this release | +------------------------------+--------------------------------------------------------------------------------------------------------------------------------+ @@ -1636,13 +1666,13 @@ A successful StartApplication request returns a success response. A failed StartApplication action returns a failure response code and the specific failure message in the response block. +------------------------------+---------------------------------------------------------------+ -| **Target URL** | /restconf/operations/appc-provider-lcm:startapplication | +| **Target URL** | /restconf/operations/appc-provider-lcm:start-application | +------------------------------+---------------------------------------------------------------+ | **Action** | StartApplication | +------------------------------+---------------------------------------------------------------+ | **Action-Identifiers** | Vnf-id | +------------------------------+---------------------------------------------------------------+ -| **Payload Parameters** | See below | +| **Payload Parameters** | See table below | +------------------------------+---------------------------------------------------------------+ | **Revision History** | Unchanged in this release. | +------------------------------+---------------------------------------------------------------+ @@ -1652,14 +1682,8 @@ A failed StartApplication action returns a failure response code and the specifi +---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+-----------------------------------------------------------------+ | **Payload Parameter** | **Description** | **Required?** | **Example** | +=================================+====================================================================================================================================================================================+=====================+=================================================================+ -| request- parameters | The parameters required to process the request must include the host-ip-address to connect to the VNF (for Chef and Ansible, this will be the url to connect to the server). | Yes | "payload": | -| | | | "{\\"request-parameters | -| | | | \\": { | -| | | | \\"host-ip-address\\": \\”value\\” | -| | | | } | -| | | | \\"configuration- parameters\\": {\\"<CONFIG- PARAMS>\\"} | -+---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+ | -| configuration- parameters | A set of instance specific configuration parameters should be specified, as required by the Chef cookbook or Ansible playbook. | No | | +| | | | "payload": | +| configuration- parameters | A set of instance specific configuration parameters should be specified, as required by the Chef cookbook or Ansible playbook. | No | "{\\"configuration- parameters\\": {\\"<CONFIG- PARAMS>\\"} | +---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+-----------------------------------------------------------------+ StartApplication Response @@ -1670,7 +1694,7 @@ The StartApplication response returns an indication of success or failure of the Stop ---- -Use the Stop command to stop a VM. +Use the Stop command to stop a VM that was running. **NOTE:** The command implementation is based on Openstack functionality. For further details, see http://developer.openstack.org/api-ref/compute/. @@ -1681,7 +1705,7 @@ Use the Stop command to stop a VM. +------------------------------+--------------------------------------------------------------------------------------------------------------------------------+ | **Action-identifiers** | vnf-id and vserver-id are required. | +------------------------------+--------------------------------------------------------------------------------------------------------------------------------+ -| **Payload Parameters** | See below | +| **Payload Parameters** | See table below | +------------------------------+--------------------------------------------------------------------------------------------------------------------------------+ | **Revision History** | Unchanged in this release | +------------------------------+--------------------------------------------------------------------------------------------------------------------------------+ @@ -1723,7 +1747,7 @@ A failed StopApplication action returns a failure response code and the specific +------------------------------+--------------------------------------------------------------+ | **Action-Identifiers** | Vnf-id | +------------------------------+--------------------------------------------------------------+ -| **Payload Parameters** | See below | +| **Payload Parameters** | See table below | +------------------------------+--------------------------------------------------------------+ | **Revision History** | Unchanged in this release | +------------------------------+--------------------------------------------------------------+ @@ -1733,15 +1757,10 @@ A failed StopApplication action returns a failure response code and the specific +---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+-----------------------------------------------------------------+ | **Payload Parameter** | **Description** | **Required?** | **Example** | +=================================+====================================================================================================================================================================================+=====================+=================================================================+ -| request- parameters | The parameters required to process the request must include the host-ip-address to connect to the VNF (for Chef and Ansible, this will be the url to connect to the server). | Yes | "payload": | -| | | | "{\\"request-parameters | -| | | | \\": { | -| | | | \\"host-ip-address\\": \\”va lue\\” | -| | | | } | +| configuration- parameters | A set of instance specific configuration parameters should be specified, as required by the Chef cookbook or Ansible playbook. | No | "payload": | | | | | \\"configuration- parameters\\": {\\"<CONFIG- PARAMS>\\"} | +---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+-----------------------------------------------------------------+ -| configuration- parameters | A set of instance specific configuration parameters should be specified, as required by the Chef cookbook or Ansible playbook. | No | | -+---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+-----------------------------------------------------------------+ + StopApplication Response ^^^^^^^^^^^^^^^^^^^^^^^^ @@ -1780,7 +1799,7 @@ Unlock is a command intended for APPC and does not execute an actual VNF command The Unlock command will result in success if the VNF successfully unlocked or if it was already unlocked, otherwise commands will be rejected. -The Unlock command will only return success if the VNF was locked with same `request-id <#_bookmark4>`__. +The Unlock command will only return success if the VNF was locked with same request-id. The Unlock command returns only one final response with the status of the request processing. @@ -1793,11 +1812,19 @@ Note: APPC locks the target VNF during any command processing. If an Unlock acti +------------------------------+-----------------------------------------------------+ | **Action-identifiers** | Vnf-id | +------------------------------+-----------------------------------------------------+ -| **Payload Parameters** | None | +| **Payload Parameters** | see table below | +------------------------------+-----------------------------------------------------+ | **Revision History** | Unchanged in this release. | +------------------------------+-----------------------------------------------------+ +| + ++---------------------------------+-------------------------------------------------------------------------+---------------------+----------------------------------+ +| **Payload Parameter** | **Description** | **Required?** | **Example** | ++=================================+=========================================================================+=====================+==================================+ +| request-id | Request id from the previously submitted request | Yes | "request-id": "123456789" | ++---------------------------------+-------------------------------------------------------------------------+---------------------+----------------------------------+ + UpgradeBackout -------------- @@ -2045,18 +2072,19 @@ Ansible playbooks / Chef cookbooks: stored in the same directory on the server. The directory name will be of the format: - {existing-software-version\_new-software-version}. + {existing-software-version_new-software-version}. The path to the directory is the same for all upgrades (for example: vnf-type/softwareupgrade). - The playbooks for upgrades should use a standard naming convention - (for example: SoftwareUpgrade\_{existing-software-version\_new-software-version}). + (for example: SoftwareUpgrade_{existing-software-version_new-software-version}). APPC template: The APPC templates for the Upgrade commands can be common across upgrades for the vnf-type if the path and filenames are standardized. - The template will contain the directory path/playbook name which would be parameterized. - {vnf-type}/UpgradeSoftware/${existing\_software\_version}\_${new-software-version}/ - SoftwareUpgrade\_{existing-software-version\_new-software-version}. + {vnf-type}/UpgradeSoftware/${existing_software_version}_${new-software-version}/ + SoftwareUpgrade_{existing-software-version_new-software-version}. + |