From 42787489b278624f2204a58292dcafa5d69c0274 Mon Sep 17 00:00:00 2001 From: shangxdy Date: Thu, 26 Apr 2018 15:40:56 +0800 Subject: Modify user guide for Frase Update user guide for nfv-toscaprser JIRA: PARSER-177 Change-Id: I68f65c37c4e0c69627467a4c2e1814183638535e Signed-off-by: shangxdy --- docs/release/userguide/feature.userguide.rst | 166 +++++++++++++++++++++++---- 1 file changed, 145 insertions(+), 21 deletions(-) diff --git a/docs/release/userguide/feature.userguide.rst b/docs/release/userguide/feature.userguide.rst index 219bc0e..4d0d46e 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= [--nrpv] [--debug] - or - tosca-parser --template-file= [--nrpv] [--debug] - or - tosca-parser --template-file= [--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= [--nrpv] [--debug] + tosca-parser --template-file= [--nrpv] [--debug] + tosca-parser --template-file= [--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 ============================= -- cgit 1.2.3-korg