diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/conf.py | 1 | ||||
| -rw-r--r-- | docs/conf.yaml | 3 | ||||
| -rw-r--r-- | docs/developer/design/tosca2heat.rst | 137 | ||||
| -rw-r--r-- | docs/index.rst | 17 | ||||
| -rw-r--r-- | docs/release/release-notes/release-notes.rst | 198 | ||||
| -rw-r--r-- | docs/release/userguide/feature.userguide.rst | 166 | ||||
| -rw-r--r-- | docs/requirements.txt | 2 |
7 files changed, 479 insertions, 45 deletions
diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..3c4453e --- /dev/null +++ b/docs/conf.py @@ -0,0 +1 @@ +from docs_conf.conf import * diff --git a/docs/conf.yaml b/docs/conf.yaml new file mode 100644 index 0000000..e2c35e6 --- /dev/null +++ b/docs/conf.yaml @@ -0,0 +1,3 @@ +--- +project_cfg: opnfv +project: parser diff --git a/docs/developer/design/tosca2heat.rst b/docs/developer/design/tosca2heat.rst index e49718e..6b71238 100644 --- a/docs/developer/design/tosca2heat.rst +++ b/docs/developer/design/tosca2heat.rst @@ -17,3 +17,140 @@ More details please refer to openstack related sites. Tosca2heat intends to enhanced NFV features in tosca template parse and translator, such as huge page, dpdk and sriov. + + +nfv-toscaparser api +-------------------- + + Implementation of nfv-toscaparser derived from openstack tosca parser is based on the following OASIS specification: + TOSCA Simple Profile YAML 1.2 Referecne http://docs.oasis-open.org/tosca/TOSCA-Simple-Profile-YAML/v1.2/TOSCA-Simple-Profile-YAML-v1.2.html + TOSCA Simple Profile YAML NFV 1.0 Referecne http://docs.oasis-open.org/tosca/tosca-nfv/v1.0/tosca-nfv-v1.0.html + + There are three ways to call nfv-toscaparser service, Python Lib ,CLI and REST API. + +CLI +**** +Using cli, which is used to validate tosca simple based service template. It can be used as: + tosca-parser --template-file=<path to the YAML template> [--nrpv] [--debug] + + tosca-parser --template-file=<path to the CSAR zip file> [--nrpv] [--debug] + + tosca-parser --template-file=<URL to the template or CSAR> [--nrpv] [--debug] + + options: + + --nrpv Ignore input parameter validation when parse template. + + --debug debug mode for print more details other than raise exceptions when errors happen + + + +Library(Python) +************** + Using api, which is used to parse and get the result of service template. it can be used as + ToscaTemplate(path=None, parsed_params=None, a_file=True, yaml_dict_tpl=None, + + sub_mapped_node_template=None, + + no_required_paras_valid=False, debug=False ) + + + +REST API +*********** + Using RESTfual API, which are listed as following: + + +List template versions +######################## + +PATH: /v1/template_versions +METHOD: GET +Decription: Lists all supported tosca template versions. + +Response Codes + +Success +200 - OK Request was successful. + +Error + +400 - Bad Request Some content in the request was invalid. +404 - Not Found The requested resource could not be found. +500 - Internal Server Error Something went wrong inside the service. This should not happen usually. If it does happen, it means the server has experienced some serious problems. +Request Parameters + +No + +Response Parameters + +template_versions array A list of tosca template version object each describes the type name and version information for a template version. + + +Validates a service template +############################ + +PATH: /v1/validate +METHOD: POST +Decription: Validate a service template. + +Response Codes +Success +200 - OK Request was successful. + +Error + +400 - Bad Request Some content in the request was invalid. +500 - Internal Server Error Something went wrong inside the service. This should not happen usually. If it does happen, it means the server has experienced some serious problems. +Request Parameters +environment (Optional) object A JSON environment for the template service. +environment_files (Optional) object An ordered list of names for environment files found in the files dict. +files (Optional) object +Supplies the contents of files referenced in the template or the environment. + +The value is a JSON object, where each key is a relative or absolute URI which serves as the name of a file, and the associated value provides the contents of the file. The following code shows the general structure of this parameter. + +{ ... + "files": { + "fileA.yaml": "Contents of the file", + "file:///usr/fileB.template": "Contents of the file", + "http://example.com/fileC.template": "Contents of the file" + } +... +} +ignore_errors (Optional) string List of comma separated error codes to ignore. +show_nested (Optional) boolean Set to true to include nested template service in the list. +template (Optional) object +The service template on which to perform the operation. + +This parameter is always provided as a string in the JSON request body. The content of the string is a JSON- or YAML-formatted service template. For example: + +"template": { + "tosca_definitions_version": "tosca_simple_yaml_1_0", + ... +} +This parameter is required only when you omit the template_url parameter. If you specify both parameters, this value overrides thetemplate_url parameter value. + +template_url (Optional) string A URI to the location containing the service template on which to perform the operation. See the description of the template parameter for information about the expected template content located at the URI. This parameter is only required when you omit the template parameter. If you specify both parameters, this parameter is ignored. +Request Example +{ + "template_url": "/PATH_TO_TOSCA_TEMPLATES/HelloWord_Instance.csar" +} + +Response Parameters +Description string The description specified in the template. +Error Information (Optional) string Error information + +Parse a service template +######################### +PATH: /v1/validate +METHOD: POST +Decription: Validate a service template. +Response Code: same as "Validates a service template" +Request Parameters: same as "Validates a service template" +Response Parameters +Description string The description specified in the template. +Input parameters object Input parameter list. +Service Template object Service template body +Output parameters object Input parameter list. +Error Information (Optional) string Error information diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..b2c3b5d --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,17 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 +.. International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. (c) Open Platform for NFV Project, Inc. and its contributors + +.. _parser: + +====== +Parser +====== + +.. toctree:: + :maxdepth: 2 + + release/installation/index + release/release-notes/index + release/userguide/index diff --git a/docs/release/release-notes/release-notes.rst b/docs/release/release-notes/release-notes.rst index 3c1dc70..1244a65 100644 --- a/docs/release/release-notes/release-notes.rst +++ b/docs/release/release-notes/release-notes.rst @@ -12,19 +12,25 @@ This document provides the release notes for <Danube Release> of <Parser>. Version history --------------- -+--------------------+--------------------+--------------------+--------------------+ -| **Date** | **Ver.** | **Author** | **Comment** | -| | | | | -+--------------------+--------------------+--------------------+--------------------+ -| 2017-03-06 | 1.0 | Howard Huang | Danube Release | -| | | | | -+--------------------+--------------------+--------------------+--------------------+ -| 2017-09-25 | 2.0 | Shang Xiaodong | Euphrates release | -| | | | | -+--------------------+--------------------+--------------------+--------------------+ -| | | | | -| | | | | -+--------------------+--------------------+--------------------+--------------------+ ++--------------------+--------------------+--------------------+----------------------+ +| **Date** | **Ver.** | **Author** | **Comment** | +| | | | | ++--------------------+--------------------+--------------------+----------------------+ +| 2016-04-20 | 0.5 | Howard Huang | Brahmaputra Release | +| | | | | ++--------------------+--------------------+--------------------+----------------------+ +| 2016-09-19 | 1.0 | Howard Huang | Colorado Release | +| | | | | ++--------------------+--------------------+--------------------+----------------------+ +| 2017-03-06 | 2.0 | Howard Huang | Danube Release | +| | | | | ++--------------------+--------------------+--------------------+----------------------+ +| 2017-09-25 | 5.0 | Shang Xiaodong | Euphrates release | +| | 0.5 ONAP | | | ++--------------------+--------------------+--------------------+----------------------+ +| 2018-04-20 | 6.0 | Shang Xiaodong | Fraser release | +| | 1.0 ONAP | | | ++--------------------+--------------------+--------------------+----------------------+ Important notes =============== @@ -39,7 +45,8 @@ Summary OPNFV Parser Danube release has provides four submodules to serve as translation/prevalidation tools: tosca2heat, yang2tosca, policy2tosca, and verigraph. Specifically, tosca2heat module provides an integration of OpenStack tosca-parser and heat-translater -upstream projects 0.7 release with additional Parser unique features. +upstream projects 0.7 release with additional Parser unique features, and includes nfv-toscaparser + and nfv-heattranslaotor for ONAP community. Release Data @@ -59,15 +66,155 @@ Release Data | | tion tooling | +--------------------------------------+--------------------------------------+ +Fraser Release Data +----------------------- + ++--------------------------------------+--------------------------------+ +| **Project** | OPNFV Parer | +| | | ++--------------------------------------+--------------------------------+ +| **Repo/tag** | Parser/6.0.0 | +| | | +| | | ++--------------------------------------+--------------------------------+ +| **Bottlenecks Docker image tag** | * 6.0.0 | +| | | +| | | ++--------------------------------------+--------------------------------+ +| **Release designation** | * 6.0.0 | +| | | +| | | ++--------------------------------------+--------------------------------+ +| **Release date** | * Apr 20th 2018 | +| | | +| | | ++--------------------------------------+--------------------------------+ +| **Purpose of the delivery** | Fraser stable release | +| | | +| | OPNFV Template Translation/ | +| | Prevalidation tooling | ++--------------------------------------+--------------------------------+ + +Euphrates Release Data +----------------------- + ++--------------------------------------+--------------------------------+ +| **Project** | OPNFV Parer | +| | | ++--------------------------------------+--------------------------------+ +| **Repo/tag** | Parser/5.0.0 | +| | | +| | | ++--------------------------------------+--------------------------------+ +| **Bottlenecks Docker image tag** | * 5.0.0 | +| | | +| | | ++--------------------------------------+--------------------------------+ +| **Release designation** | * 5.0.0 | +| | | +| | | ++--------------------------------------+--------------------------------+ +| **Release date** | * Sept 25th 2017 | +| | | +| | | ++--------------------------------------+--------------------------------+ +| **Purpose of the delivery** | Euphrates stable release | +| | | +| | OPNFV Template Translation/ | +| | Prevalidation tooling | ++--------------------------------------+--------------------------------+ + +Danube Release Data +----------------------- + ++--------------------------------------+--------------------------------+ +| **Project** | OPNFV Parer | +| | | ++--------------------------------------+--------------------------------+ +| **Repo/tag** | Parser/danube.2.0 | +| | | ++--------------------------------------+--------------------------------+ +| **Bottlenecks Docker image tag** | * danube.2.0 | +| | | +| | | ++--------------------------------------+--------------------------------+ +| **Release designation** | * Danube 2.0 | +| | | +| | | ++--------------------------------------+--------------------------------+ +| **Release date** | * March 6st 2017 | +| | | +| | | ++--------------------------------------+--------------------------------+ +| **Purpose of the delivery** | Danube stable release | +| | | +| | OPNFV Template Translation/ | +| | Prevalidation tooling | ++--------------------------------------+--------------------------------+ + +Colorado Release Data +----------------------- + ++--------------------------------------+--------------------------------+ +| **Project** | OPNFV Parer | +| | | ++--------------------------------------+--------------------------------+ +| **Repo/tag** | Parser/colorado.1.0 | +| | | ++--------------------------------------+--------------------------------+ +| **Bottlenecks Docker image tag** | * colorado.1.0 | +| | | ++--------------------------------------+--------------------------------+ +| **Release designation** | * Colorado 1.0 | +| | | ++--------------------------------------+--------------------------------+ +| **Release date** | * September 22 2016 | +| | | ++--------------------------------------+--------------------------------+ +| **Purpose of the delivery** | Colorado stable release | +| | | +| | OPNFV Template Translation/ | +| | Prevalidation tooling | ++--------------------------------------+--------------------------------+ + +Bramaputra Release Data +----------------------- + ++--------------------------------------+--------------------------------+ +| **Project** | OPNFV Parer | +| | | ++--------------------------------------+--------------------------------+ +| **Repo/tag** | Parser/brahmaputra.1.0 | +| | | ++--------------------------------------+--------------------------------+ +| **Bottlenecks Docker image tag** | * brahmaputra.1.0 | +| | | ++--------------------------------------+--------------------------------+ +| **Release designation** | * Brahmaputra 1.0 | +| | | ++--------------------------------------+--------------------------------+ +| **Release date** | * February 25 2016 | +| | | ++--------------------------------------+--------------------------------+ +| **Purpose of the delivery** | Brahmaputra stable release | +| | | +| | OPNFV Template Translation/ | +| | Prevalidation tooling | ++--------------------------------------+--------------------------------+ + Version change ^^^^^^^^^^^^^^ Module version changes ~~~~~~~~~~~~~~~~~~~~~~ -- OpenStack tosca-parser and heat-translator have changed from 0.6 to 0.7 +- OpenStack tosca-parser and heat-translator have changed from 0.8 to 0.9 + +- Parseer support aarch64 + +- update verigraph module -- new verigraph module +- Release 0.5 and 1.0 for ONAP community - no feature changes in yang2tosca and policy2tosca since Colorado Release. @@ -78,11 +225,9 @@ Document version changes Reason for version ^^^^^^^^^^^^^^^^^^ + Feature additions ~~~~~~~~~~~~~~~~~ -<STATE ADDED FEATURES BY REFERENCE TO JIRA> - -<EXAMPLE>: **JIRA BACK-LOG:** @@ -199,6 +344,7 @@ Known Limitations, Issues and Workarounds System Limitations ^^^^^^^^^^^^^^^^^^ +None @@ -229,11 +375,9 @@ Workarounds Test Result =========== -<STATE THE QA COVERAGE AND RESULTS> -<EXAMPLE>: -Fuel@OPNFV Arno RC2 has undergone QA test runs with the following results: +Parser test with functest runs with the following results: +--------------------------------------+--------------------------------------+ | **TEST-SUITE** | **Results:** | @@ -254,6 +398,12 @@ References ========== -For more information on the OPNFV Danube release, please see: + - WIKI project page: https://wiki.opnfv.org/display/parser + + - Parser jira page: https://jira.opnfv.org/secure/RapidBoard.jspa?rapidView=121&useStoredSettings=true + + - Parser repo: https://git.opnfv.org/cgit/parser + + - Parser CI dashboard: https://build.opnfv.org/ci/view/parser -http://opnfv.org/danube + - Parser IRC chanel: #opnfv-parser diff --git a/docs/release/userguide/feature.userguide.rst b/docs/release/userguide/feature.userguide.rst index 219bc0e..4ad4f22 100644 --- a/docs/release/userguide/feature.userguide.rst +++ b/docs/release/userguide/feature.userguide.rst @@ -7,6 +7,11 @@ Parser tosca2heat Execution =========================== +nfv-heattranslator +------------------- + + There only one way to call nfv-heattranslator service: CLI. + Step 1: Change directory to where the tosca yaml files are present, example is below with vRNC definiton. @@ -29,34 +34,156 @@ Example: heat-translator --template-file=vRNC.yaml \ --template-type=tosca --output-file=vRNC_hot.yaml -**Notes**: heat-translator will call class of ToscaTemplate in tosca-parser firstly to validate and -parse input yaml file, then tranlate the file into hot file, if you only want to validate or -check the input file and don't want to translate, please use tosaca-parser as following: +**Notes**: nfv-heattranslator will call class of ToscaTemplate in nfv-toscaparser firstly to validate and +parse input yaml file, then tranlate the file into hot file. + + +nfv-toscaparser +---------------- + +Implementation of nfv-toscaparser derived from openstack tosca parser is based on the following OASIS specification: + TOSCA Simple Profile YAML 1.2 Referecne http://docs.oasis-open.org/tosca/TOSCA-Simple-Profile-YAML/v1.2/TOSCA-Simple-Profile-YAML-v1.2.html + TOSCA Simple Profile YAML NFV 1.0 Referecne http://docs.oasis-open.org/tosca/tosca-nfv/v1.0/tosca-nfv-v1.0.html + +There are three ways to call nfv-toscaparser service, Python Lib ,CLI and REST API. + +CLI +**** +Using cli, which is used to validate tosca simple based service template. It can be used as: .. code-block:: bash - tosca-parser --template-file=<path to the YAML template> [--nrpv] [--debug] - or - tosca-parser --template-file=<path to the CSAR zip file> [--nrpv] [--debug] - or - tosca-parser --template-file=<URL to the template or CSAR> [--nrpv] [--debug] - options: - --nrpv Ignore input parameter validation when parse template. - --debug debug mode for print more details other than raise exceptions when errors happen + tosca-parser --template-file=<path to the YAML template> [--nrpv] [--debug] + tosca-parser --template-file=<path to the CSAR zip file> [--nrpv] [--debug] + tosca-parser --template-file=<URL to the template or CSAR> [--nrpv] [--debug] -Example: + options: + --nrpv Ignore input parameter validation when parse template. + --debug debug mode for print more details other than raise exceptions when errors happen + + +Library(Python) +**************** + +Using api, which is used to parse and get the result of service template. it can be used as: .. code-block:: bash - tosca-parser --template-file=vRNC.yaml --nrpv + ToscaTemplate(path=None, parsed_params=None, a_file=True, yaml_dict_tpl=None, + sub_mapped_node_template=None, + no_required_paras_valid=False, debug=False) + +REST API +********* + +Using RESTfual API, which are listed as following: + +List template versions +######################## + +PATH: /v1/template_versions +METHOD: GET +Decription: Lists all supported tosca template versions. + +Response Codes + +Success +200 - OK Request was successful. + +Error + +400 - Bad Request Some content in the request was invalid. +404 - Not Found The requested resource could not be found. +500 - Internal Server Error Something went wrong inside the service. This should not happen usually. +If it does happen, it means the server has experienced some serious problems. -Parser tosca2heat References -============================ -Refer two upstream components: - https://github.com/openstack/tosca-parser/blob/master/doc/source/usage.rst - https://github.com/openstack/heat-translator/blob/master/doc/source/usage.rst +Request Parameters +No +Response Parameters + +template_versions array A list of tosca template version object each describes the type name and + version information for a template version. + + +Validates a service template +############################# + +PATH: /v1/validate +METHOD: POST +Decription: Validate a service template. + +Response Codes +Success +200 - OK Request was successful. + +Error + +400 - Bad Request Some content in the request was invalid. +500 - Internal Server Error Something went wrong inside the service. This should not happen usually. + If it does happen, it means the server has experienced some serious problems. +Request Parameters +environment (Optional) object A JSON environment for the template service. +environment_files (Optional) object An ordered list of names for environment files found in the files dict. +files (Optional) object +Supplies the contents of files referenced in the template or the environment. + +The value is a JSON object, where each key is a relative or absolute URI which serves as the name of + a file, and the associated value provides the contents of the file. The following code shows the + general structure of this parameter. + +{ ... + "files": { + "fileA.yaml": "Contents of the file", + "file:///usr/fileB.template": "Contents of the file", + "http://example.com/fileC.template": "Contents of the file" + } +... +} +ignore_errors (Optional) string List of comma separated error codes to ignore. +show_nested (Optional) boolean Set to true to include nested template service in the list. +template (Optional) object +The service template on which to perform the operation. + +This parameter is always provided as a string in the JSON request body. The content of the string is + a JSON- or YAML-formatted service template. For example: + +"template": { + "tosca_definitions_version": "tosca_simple_yaml_1_0", + ... +} +This parameter is required only when you omit the template_url parameter. If you specify both +parameters, this value overrides thetemplate_url parameter value. + +template_url (Optional) string A URI to the location containing the service template on which to +perform the operation. See the description of the template parameter for information about the +expected template content located at the URI. This parameter is only required when you omit the +template parameter. If you specify both parameters, this parameter is ignored. + +Request Example +{ + "template_url": "/PATH_TO_TOSCA_TEMPLATES/HelloWord_Instance.csar" +} + +Response Parameters +Description string The description specified in the template. +Error Information (Optional) string Error information + +Parse a service template +######################### + +PATH: /v1/validate +METHOD: POST +Decription: Validate a service template. +Response Code: same as "Validates a service template" +Request Parameters: same as "Validates a service template" +Response Parameters +Description string The description specified in the template. +Input parameters object Input parameter list. +Service Template object Service template body +Output parameters object Input parameter list. +Error Information (Optional) string Error information Parser yang2tosca Execution @@ -97,9 +224,6 @@ Example: cat example_tosca.yaml - - - Parser policy2tosca Execution ============================= diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..9fde2df --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,2 @@ +lfdocs-conf +sphinx_opnfv_theme |