From d7ca6c5f9b4631ddd8f6dca7607e509a9684aa53 Mon Sep 17 00:00:00 2001 From: bhagyashris Date: Fri, 6 Sep 2019 13:02:25 +0530 Subject: [PATCH] Add vnf packages documentation Following are the list of documents updated for vnf package feature usage: 1. api-reference document 2. release notes Partial-Implements: blueprint tosca-csar-mgmt-driver Change-Id: I82fc2e9d3f39e78b24eeb8034b0f611798c1aeb8 --- api-ref/source/v1/index.rst | 1 + api-ref/source/v1/parameters.yaml | 139 +++++++++- .../vnf-packages-create-request.json | 5 + .../vnf-packages-create-response.json | 20 ++ .../vnf-packages-list-response.json | 69 +++++ .../vnf-packages-show-response.json | 65 +++++ api-ref/source/v1/vnf_packages.inc | 243 ++++++++++++++++++ ...sca-csar-mgmt-driver-6dbf9e847c8fe77a.yaml | 12 + 8 files changed, 553 insertions(+), 1 deletion(-) create mode 100644 api-ref/source/v1/samples/vnf_packages/vnf-packages-create-request.json create mode 100644 api-ref/source/v1/samples/vnf_packages/vnf-packages-create-response.json create mode 100644 api-ref/source/v1/samples/vnf_packages/vnf-packages-list-response.json create mode 100644 api-ref/source/v1/samples/vnf_packages/vnf-packages-show-response.json create mode 100644 api-ref/source/v1/vnf_packages.inc create mode 100644 releasenotes/notes/bp-tosca-csar-mgmt-driver-6dbf9e847c8fe77a.yaml diff --git a/api-ref/source/v1/index.rst b/api-ref/source/v1/index.rst index 08010c31c..44228b2f4 100644 --- a/api-ref/source/v1/index.rst +++ b/api-ref/source/v1/index.rst @@ -19,3 +19,4 @@ NFV Orchestration API v1.0 .. include:: classifiers.inc .. include:: nsds.inc .. include:: nss.inc +.. include:: vnf_packages.inc diff --git a/api-ref/source/v1/parameters.yaml b/api-ref/source/v1/parameters.yaml index 863ae4748..316d52301 100644 --- a/api-ref/source/v1/parameters.yaml +++ b/api-ref/source/v1/parameters.yaml @@ -55,6 +55,12 @@ vnf_id_path: in: path required: true type: string +vnf_package_id_path: + description: | + The UUID of the VNF Package. + in: path + required: true + type: string vnfd_id_path: description: | The UUID of the VNFD. @@ -77,6 +83,13 @@ vnffgd_id_path: # variables in query # variables in body +addressInformation: + description: | + Address information of the VNF package content. The NFVO can use this address + to obtain the VNF package. + in: body + required: true + type: string alias: description: | The alias for the extension. For example, @@ -354,6 +367,37 @@ nss: in: body required: true type: array +onboardingState: + description: | + On-boarding state of the VNF package. + The on-boarding state is represented by the "onboardingState" attribute in the "VnfPkgInfo" + information element with below values: + CREATED: The VNF Package information object is created. + UPLOADING: The VNF Package is being uploaded. + PROCESSING: The VNF Package is being processed, e.g. validation. + ONBOARDED: The VNF Package is successfully on-boarded. + in: body + required: true + type: string +operationalState: + description: | + Operational state of the VNF package. + The operational state is represented by the "operationalState" attribute in the "VnfPkgInfo" + information element with below values: + ENABLED: The VNF Package is enabled. + DISABLED: The VNF Package is disabled. + If the value of the onboardingState attribute is not equal to "ONBOARDED", the value of + the operationalState attribute shall be equal to "DISABLED". + in: body + required: true + type: string +password: + description: | + Password to be used for authentication. Shall be present if password is needed but + has not been provisioned out of band. + in: body + required: true + type: string service_types: description: | A list of service type. @@ -417,6 +461,15 @@ sfcs: in: body required: true type: array +software_images: + description: | + Information about VNF package artifacts that are software images. + This attribute shall not be present before the VNF package content is on-boarded. + Otherwise, this attribute shall be present unless it has been requested to be + excluded per attribute selector. + in: body + required: true + type: array symmetrical: description: | Indicate whether reverse traffic should also flow through the path. @@ -453,6 +506,31 @@ updated_at: in: body required: true type: string +usageState: + description: | + Usage state of the VNF package. + The usage state is represented by the "usageState" attribute in the "VnfPkgInfo" information + element with below values: + IN_USE: The VNF Package is in use. + NOT_IN_USE: The VNF Package is not in use. + If the value of the onboardingState attribute is not equal to "ONBOARDED", the value of + the usageState attribute shall be equal to "NOT_IN_USE". + in: body + required: true + type: string +userDefinedData: + description: | + User defined data for the VNF package. + in: body + required: true + type: object +userName: + description: | + User name to be used for authentication. Shall be present if user name is needed + but has not been provisioned out of band. + in: body + required: true + type: string version_href: description: | Link to the API. @@ -708,6 +786,12 @@ vnf_monitoring_policy: in: body required: true type: string +vnf_package_id: + description: | + Identifier of the VNF package. This identifier is allocated by the NFVO. + in: body + required: true + type: string vnf_param_values: description: | VNF parameter object. These parameters will be substituted for VNF @@ -728,6 +812,28 @@ vnf_param_values_opt: in: body required: false type: object +vnf_pkg_content: + description: | + A VNF Package is a tar-archive containing all the information required for managing + the lifecycle of a VNF. + The "Content-Type" HTTP header should be set to "application/zip". + in: body + required: true + type: object +vnf_pkg_links: + description: | + Links to resources related to this resource. + in: body + required: true + type: object +vnf_pkg_vnfd_id: + description: | + This identifier, which is managed by the VNF provider, identifies the VNF package and the VNFD + in a globally unique way. It is copied from the VNFD of the onboarded VNF package. It shall be + present after the VNF package content has been on-boarded and absent otherwise. + in: body + required: true + type: string vnf_placement_attr: description: | VNF placement information object. This object includes ``region_name`` @@ -741,6 +847,21 @@ vnf_placement_attr_opt: in: body required: false type: object +vnf_product_name: + description: | + Name to identify the VNF product. Invariant for the VNF product lifetime. + This information is copied from the VNFD. It shall be present after the VNF + package content has been on-boarded and absent otherwise. + in: body + required: true + type: string +vnf_provider: + description: | + Provider of the VNF package and the VNFD. This information is copied from the VNFD. + It shall be present after the VNF package content has been on-boarded and absent otherwise. + in: body + required: true + type: string vnf_resource_id: description: | The UUID of the VNF resource. This is equivalent to Heat stack resource ID. @@ -785,6 +906,15 @@ vnf_scale_type: in: body required: true type: string +vnf_software_version: + description: | + Software version of the VNF. This is changed when there is any change to the software + included in the VNF package. + This information is copied from the VNFD. It shall be present after the VNF package + content has been on-boarded and absent otherwise. + in: body + required: true + type: string vnf_status: description: | Status of the VNF. @@ -829,6 +959,14 @@ vnfd_template_source: in: body required: false type: string +vnfd_version: + description: | + The version of the VNFD. This information is copied from the VNFD. + It shall be present after the VNF package content has been on-boarded + and absent otherwise. + in: body + required: true + type: string vnfds: description: | A list of ``vnfd`` objects. @@ -899,4 +1037,3 @@ vnfs: in: body required: true type: array - diff --git a/api-ref/source/v1/samples/vnf_packages/vnf-packages-create-request.json b/api-ref/source/v1/samples/vnf_packages/vnf-packages-create-request.json new file mode 100644 index 000000000..48ff4dc36 --- /dev/null +++ b/api-ref/source/v1/samples/vnf_packages/vnf-packages-create-request.json @@ -0,0 +1,5 @@ +{ + "userDefinedData":{ + "abc":"xyz" + } +} diff --git a/api-ref/source/v1/samples/vnf_packages/vnf-packages-create-response.json b/api-ref/source/v1/samples/vnf_packages/vnf-packages-create-response.json new file mode 100644 index 000000000..719c338fc --- /dev/null +++ b/api-ref/source/v1/samples/vnf_packages/vnf-packages-create-response.json @@ -0,0 +1,20 @@ +{ + "usageState":"NOT_IN_USE", + "userDefinedData":{ + "abc":"xyz" + }, + "_links":{ + "packageContent":{ + "href":"/vnfpkgm/v1/vnf_packages/4e8b9d2c-ecb5-408b-a8ce-8ea0890bacbb/package_content" + }, + "self":{ + "href":"/vnfpkgm/v1/vnf_packages/4e8b9d2c-ecb5-408b-a8ce-8ea0890bacbb" + }, + "vnfd":{ + "href":"/vnfpkgm/v1/vnf_packages/4e8b9d2c-ecb5-408b-a8ce-8ea0890bacbb/vnfd" + } + }, + "onboardingState":"CREATED", + "operationalState":"DISABLED", + "id":"4e8b9d2c-ecb5-408b-a8ce-8ea0890bacbb" +} diff --git a/api-ref/source/v1/samples/vnf_packages/vnf-packages-list-response.json b/api-ref/source/v1/samples/vnf_packages/vnf-packages-list-response.json new file mode 100644 index 000000000..efad74888 --- /dev/null +++ b/api-ref/source/v1/samples/vnf_packages/vnf-packages-list-response.json @@ -0,0 +1,69 @@ +{ + "vnf_packages":[ + { + "vnfSoftwareVersion":"1.0", + "usageState":"NOT_IN_USE", + "vnfProductName":"Sample VNF", + "softwareImages":[ + { + "imagePath":"", + "diskFormat":"qcow2", + "userMetadata":{ + + }, + "id":"VirtualStorage", + "size":2, + "name":"VrtualStorage", + "checksum":{ + "hash":"b9c3036539fd7a5f87a1bf38eb05fdde8b556a1a7e664dbeda90ed3cd74b4f9d", + "algorithm":"sha-256" + }, + "minDisk":2, + "version":"0.4.0", + "provider":"provider", + "minRam":8192, + "containerFormat":"bare" + }, + { + "imagePath":"", + "diskFormat":"qcow2", + "userMetadata":{ + + }, + "id":"VDU1", + "size":1, + "name":"Software of VDU1", + "checksum":{ + "hash":"b9c3036539fd7a5f87a1bf38eb05fdde8b556a1a7e664dbeda90ed3cd74b4f9d", + "algorithm":"sha-256" + }, + "minDisk":1, + "version":"0.4.0", + "provider":"provider", + "minRam":0, + "containerFormat":"bare" + } + ], + "vnfProvider":"Test VNF Provider", + "userDefinedData":{ + "abc":"xyz" + }, + "vnfdId":"b3ab49d6-389d-46f9-8650-d0bf778b5e92", + "_links":{ + "packageContent":{ + "href":"/vnfpkgm/v1/vnf_packages/4e8b9d2c-ecb5-408b-a8ce-8ea0890bacbb/package_content" + }, + "self":{ + "href":"/vnfpkgm/v1/vnf_packages/4e8b9d2c-ecb5-408b-a8ce-8ea0890bacbb" + }, + "vnfd":{ + "href":"/vnfpkgm/v1/vnf_packages/4e8b9d2c-ecb5-408b-a8ce-8ea0890bacbb/vnfd" + } + }, + "vnfdVersion":"1.0", + "onboardingState":"ONBOARDED", + "operationalState":"DISABLED", + "id":"4e8b9d2c-ecb5-408b-a8ce-8ea0890bacbb" + } + ] +} diff --git a/api-ref/source/v1/samples/vnf_packages/vnf-packages-show-response.json b/api-ref/source/v1/samples/vnf_packages/vnf-packages-show-response.json new file mode 100644 index 000000000..251b7de96 --- /dev/null +++ b/api-ref/source/v1/samples/vnf_packages/vnf-packages-show-response.json @@ -0,0 +1,65 @@ +{ + "vnfSoftwareVersion":"1.0", + "usageState":"NOT_IN_USE", + "vnfProductName":"Sample VNF", + "softwareImages":[ + { + "imagePath":"", + "diskFormat":"qcow2", + "userMetadata":{ + + }, + "id":"VirtualStorage", + "size":2, + "name":"VrtualStorage", + "checksum":{ + "hash":"b9c3036539fd7a5f87a1bf38eb05fdde8b556a1a7e664dbeda90ed3cd74b4f9d", + "algorithm":"sha-256" + }, + "minDisk":2, + "version":"0.4.0", + "provider":"provider", + "minRam":8192, + "containerFormat":"bare" + }, + { + "imagePath":"", + "diskFormat":"qcow2", + "userMetadata":{ + + }, + "id":"VDU1", + "size":1, + "name":"Software of VDU1", + "checksum":{ + "hash":"b9c3036539fd7a5f87a1bf38eb05fdde8b556a1a7e664dbeda90ed3cd74b4f9d", + "algorithm":"sha-256" + }, + "minDisk":1, + "version":"0.4.0", + "provider":"provider", + "minRam":0, + "containerFormat":"bare" + } + ], + "vnfProvider":"Test VNF Provider", + "userDefinedData":{ + "abc":"xyz" + }, + "vnfdId":"b3ab49d6-389d-46f9-8650-d0bf778b5e92", + "_links":{ + "packageContent":{ + "href":"/vnfpkgm/v1/vnf_packages/4e8b9d2c-ecb5-408b-a8ce-8ea0890bacbb/package_content" + }, + "self":{ + "href":"/vnfpkgm/v1/vnf_packages/4e8b9d2c-ecb5-408b-a8ce-8ea0890bacbb" + }, + "vnfd":{ + "href":"/vnfpkgm/v1/vnf_packages/4e8b9d2c-ecb5-408b-a8ce-8ea0890bacbb/vnfd" + } + }, + "vnfdVersion":"1.0", + "onboardingState":"ONBOARDED", + "operationalState":"DISABLED", + "id":"4e8b9d2c-ecb5-408b-a8ce-8ea0890bacbb" +} diff --git a/api-ref/source/v1/vnf_packages.inc b/api-ref/source/v1/vnf_packages.inc new file mode 100644 index 000000000..d2c4380e8 --- /dev/null +++ b/api-ref/source/v1/vnf_packages.inc @@ -0,0 +1,243 @@ +.. -*- rst -*- + +==================================================== +Virtualized Network Function Packages (VNF packages) +==================================================== + +Manages Virtualized Network Function Packages (VNF Packages) and their resources. + +A VNF Package is a tar-archive containing all the information required for managing +the lifecycle of a VNF. + +Create VNF Package +================== + +.. rest_method:: POST /vnfpkgm/v1/vnf_packages + +Creates a VNF Package. + +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 201 + +.. rest_status_code:: error status.yaml + + - 400 + - 401 + - 403 + +Request Parameters +------------------ + +.. rest_parameters:: parameters.yaml + + - userDefinedData: userDefinedData + +Request Example +--------------- + +.. literalinclude:: samples/vnf_packages/vnf-packages-create-request.json + :language: javascript + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - id: vnf_package_id + - _links: vnf_pkg_links + - onboardingState: onboardingState + - operationalState: operationalState + - usageState: usageState + - userDefinedData: userDefinedData + +Response Example +---------------- + +.. literalinclude:: samples/vnf_packages/vnf-packages-create-response.json + :language: javascript + +List VNF Packages +================= + +.. rest_method:: GET /vnfpkgm/v1/vnf_packages + +Lists VNF Packages. + +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 200 + +.. rest_status_code:: error status.yaml + + - 401 + - 403 + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - id: vnf_package_id + - vnfdId: vnf_pkg_vnfd_id + - vnfProvider: vnf_provider + - vnfProductName: vnf_product_name + - vnfSoftwareVersion: vnf_software_version + - vnfdVersion: vnfd_version + - softwareImages: software_images + - onboardingState: onboardingState + - operationalState: operationalState + - usageState: usageState + - userDefinedData: userDefinedData + - _links: vnf_pkg_links + +Response Example +---------------- + +.. literalinclude:: samples/vnf_packages/vnf-packages-list-response.json + :language: javascript + +Show VNF Package +================= + +.. rest_method:: GET /vnfpkgm/v1/vnf_packages/{vnf_package_id} + +Shows information of a given VNF Package. + +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 200 + +.. rest_status_code:: error status.yaml + + - 401 + - 403 + - 404 + +Request Parameters +------------------ + +.. rest_parameters:: parameters.yaml + + - vnf_package_id: vnf_package_id_path + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - id: vnf_package_id + - vnfdId: vnf_pkg_vnfd_id + - vnfProvider: vnf_provider + - vnfProductName: vnf_product_name + - vnfSoftwareVersion: vnf_software_version + - vnfdVersion: vnfd_version + - softwareImages: software_images + - onboardingState: onboardingState + - operationalState: operationalState + - usageState: usageState + - userDefinedData: userDefinedData + - _links: vnf_pkg_links + +Response Example +---------------- + +.. literalinclude:: samples/vnf_packages/vnf-packages-show-response.json + :language: javascript + +Delete VNF Package +================== + +.. rest_method:: DELETE /vnfpkgm/v1/vnf_packages/{vnf_package_id} + +Deletes a given VNF Package. + +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 204 + +.. rest_status_code:: error status.yaml + + - 401 + - 403 + - 404 + +Request Parameters +------------------ + +.. rest_parameters:: parameters.yaml + + - vnf_package_id: vnf_package_id_path + +Upload VNF Package from content +=============================== + +.. rest_method:: PUT /vnfpkgm/v1/vnf_packages/{vnf_package_id}/package_content + +Upload a given VNF Package from content. + +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 202 + +.. rest_status_code:: error status.yaml + + - 401 + - 403 + - 404 + - 409 + +Request Parameters +------------------ + +.. rest_parameters:: parameters.yaml + + - vnf_package_id: vnf_package_id_path + - vnf_package_content: vnf_pkg_content + +Upload VNF Package from uri +=========================== + +.. rest_method:: POST /vnf_packages/{vnf_package_id}/package_content/upload_from_uri + +Upload a given VNF Package from content. + +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 202 + +.. rest_status_code:: error status.yaml + + - 401 + - 400 + - 403 + - 404 + - 409 + +Request Parameters +------------------ + +.. rest_parameters:: parameters.yaml + + - vnf_package_id: vnf_package_id_path + - addressInformation: addressInformation + - userName: userName + - password: password \ No newline at end of file diff --git a/releasenotes/notes/bp-tosca-csar-mgmt-driver-6dbf9e847c8fe77a.yaml b/releasenotes/notes/bp-tosca-csar-mgmt-driver-6dbf9e847c8fe77a.yaml new file mode 100644 index 000000000..3e2898188 --- /dev/null +++ b/releasenotes/notes/bp-tosca-csar-mgmt-driver-6dbf9e847c8fe77a.yaml @@ -0,0 +1,12 @@ +--- +features: + - | + Added new RESTful APIs for managing VNF packages required for managing the + lifecycle of a VNF. See the `spec`_ for more details. + + .. note:: VNF create API can create a VNF using a VNFD registered by + VNFD create API only. VNF creation and instantiation using VNF package + will be made available in future release. + + .. _spec : https://specs.openstack.org/openstack/tacker-specs/specs/train/vnf_package_support.html +