From 53b22cfb7ad8b323073213e4e55584261dd4e50a Mon Sep 17 00:00:00 2001 From: zhipengh Date: Thu, 2 Mar 2017 11:51:07 +0800 Subject: [PATCH] Danube Release Docs Fixup patch 1 Done in this patch 1. Fixes in overview.rst 2. Moves governance folder under docs 3. Adds arno release use case doc from https://wiki.opnfv.org/display/parser/Parser+Use+Cases to the requirement folder 4. Moves two old tosca2heat documents into developer/design/examples 5. Adds new empty tosca2heat and verigraph design document under developer/design. 6. Remove old contents in yang2tosca and policy2tosca design docs since they are all related to installation/execution, not design. 7. Fixes in installation.instruction.rst and usage,guide.rst To do in the following patches 1. Design doc writeup: Xiaodong(tosca2heat), Shiva(yang2tosca/policy2tosca), Serena(verigraph) 2. Release doc writeup: Xiaodong and Howard (postinstall.rst,scenario.description.rst), Serena(verigraph part of release-notes.rst), release-notes.rst Change-Id: If4f51067dd33acd2332e503ee31d6941b4df4c89 Signed-off-by: zhipengh --- .../design/{ => examples}/parser_new_keywords.rst | 0 .../design/{ => examples}/vRNC_tosca_intro.rst | 0 docs/developer/design/index.rst | 4 +- docs/developer/design/policy2tosca.rst | 81 +---------------- docs/developer/design/tosca2heat.rst | 7 ++ docs/developer/design/verigraph.rst | 7 ++ docs/developer/design/yang2tosca.rst | 93 +------------------ docs/developer/overview/overview.rst | 56 ++++++++---- .../parser requirement arno release.rst | 19 ++++ ...rado release committer email motion vote record | 0 ...parser project committer promotion guidline.rst | 0 docs/governance/index.rst | 12 +++ .../installation/installation.instruction.rst | 101 ++++++++++++++------- docs/release/userguide/feature.userguide.rst | 46 ---------- 14 files changed, 153 insertions(+), 273 deletions(-) rename docs/developer/design/{ => examples}/parser_new_keywords.rst (100%) rename docs/developer/design/{ => examples}/vRNC_tosca_intro.rst (100%) create mode 100644 docs/developer/design/tosca2heat.rst create mode 100644 docs/developer/design/verigraph.rst create mode 100644 docs/developer/requirements/parser requirement arno release.rst rename {governance/Committer => docs/governance/committer}/colorado release committer email motion vote record (100%) rename {governance/Committer => docs/governance/committer}/parser project committer promotion guidline.rst (100%) create mode 100644 docs/governance/index.rst diff --git a/docs/developer/design/parser_new_keywords.rst b/docs/developer/design/examples/parser_new_keywords.rst similarity index 100% rename from docs/developer/design/parser_new_keywords.rst rename to docs/developer/design/examples/parser_new_keywords.rst diff --git a/docs/developer/design/vRNC_tosca_intro.rst b/docs/developer/design/examples/vRNC_tosca_intro.rst similarity index 100% rename from docs/developer/design/vRNC_tosca_intro.rst rename to docs/developer/design/examples/vRNC_tosca_intro.rst diff --git a/docs/developer/design/index.rst b/docs/developer/design/index.rst index ab83cec..55be2b5 100644 --- a/docs/developer/design/index.rst +++ b/docs/developer/design/index.rst @@ -9,7 +9,7 @@ OPNFV Parser Design Documentation :numbered: :maxdepth: 6 + tosca2heat.rst yang2tosca.rst policy2tosca.rst - parser_new_keywords.rst - vRNC_tosca_intro.rst + verigraph.rst diff --git a/docs/developer/design/policy2tosca.rst b/docs/developer/design/policy2tosca.rst index fa238b2..3753d6c 100644 --- a/docs/developer/design/policy2tosca.rst +++ b/docs/developer/design/policy2tosca.rst @@ -2,86 +2,7 @@ .. http://creativecommons.org/licenses/by/4.0 =================== -Parser POLICY2TOSCA +Parser polic2tosca =================== -Overview -======== -Parser is an open source project and licensed under Apache 2. Parser will help -to provide a tooling mechanism, by parsing Telecom operators’ VNF descriptors -(YANG templates) into TOSCA templates and then further translate TOSCA -templates into certain common templates, which could be used in IaaS orchestration -projects like OpenStack Heat. - -Prerequisites -============= - -Parser - POLICY2TOSCA requires the following to be installed. - -1. cliff --------- - -Install cliff with the following links. -:: -- `install ` -or -- `demoapp ` - -Installation -============================ - -Please follow the below installation steps to install parser - POLICY2TOSCA. - -Step 1: Clone the parser project. - -.. code-block:: bash - - git clone https://gerrit.opnfv.org/gerrit/parser - -Step 2: Install the policy2tosca module. - -.. code-block:: bash - - cd parser/policy2tosca - python setup.py install - -Execution -=========================== - -Step 1: To see a list of commands available. - -.. code-block:: bash - - policy2tosca --help - -Step 2: To see help for an individual command, include the command name on the command line - -.. code-block:: bash - - policy2tosca help - -Step 3: To inject/remove policy types/policy definitions provide the TOSCA file as input to policy2tosca command line. - -.. code-block:: bash - - policy2tosca [arguments] - -Example: - -.. code-block:: bash - - policy2tosca add-definition --policy_name rule2 --policy_type tosca.policies.Placement.Geolocation --description "test description" --properties region:us-north-1,region:us-north-2,min_inst:2 --targets VNF2,VNF4 --metadata "map of strings" --triggers "1,2,3,4" --source example.yaml - - -Step 4: Verify the TOSCA YAMl updated with the injection/removal executed. - -.. code-block:: bash - - cat "" - -Example: - -.. code-block:: bash - - cat example_tosca.yaml diff --git a/docs/developer/design/tosca2heat.rst b/docs/developer/design/tosca2heat.rst new file mode 100644 index 0000000..d4ead14 --- /dev/null +++ b/docs/developer/design/tosca2heat.rst @@ -0,0 +1,7 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +=================== +Parser tosca2heat +=================== + diff --git a/docs/developer/design/verigraph.rst b/docs/developer/design/verigraph.rst new file mode 100644 index 0000000..91d5a36 --- /dev/null +++ b/docs/developer/design/verigraph.rst @@ -0,0 +1,7 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +================= +Parser verigraph +================= + diff --git a/docs/developer/design/yang2tosca.rst b/docs/developer/design/yang2tosca.rst index 5aaf463..61d31b2 100644 --- a/docs/developer/design/yang2tosca.rst +++ b/docs/developer/design/yang2tosca.rst @@ -2,97 +2,6 @@ .. http://creativecommons.org/licenses/by/4.0 ================= -Parser YANG2TOSCA +Parser yang2tosca ================= -Overview -======== - -Parser is an open source project and licensed under Apache 2. Parser will help -to provide a tooling mechanism, by parsing Telecom operators’ VNF descriptors -(YANG templates) into TOSCA templates and then further translate TOSCA -templates into certain common templates, which could be used in IaaS orchestration -projects like OpenStack Heat. - -Prerequisites -============= - -Parser requires the following to be installed. - -1. PYANG --------- - -Please follow the below installation steps. - -Step 1: Clone pyang tool or download the zip file from the following link. - -.. code-block:: bash - - git clone https://github.com/mbj4668/pyang.git - -OR - -.. code-block:: bash - - wget https://github.com/mbj4668/pyang/archive/master.zip - -Step 2: Change directory to the downloaded directory and run the setup file. - -.. code-block:: bash - - cd pyang - python setup.py - -2. python-lxml --------------- - -Please follow the below installation link. http://lxml.de/installation.html - - -Installation -============================ - -Please follow the below installation steps to install parser. - -Step 1: Clone the parser project. - -.. code-block:: bash - - git clone https://gerrit.opnfv.org/gerrit/parser - -Execution -=========================== - -Step 1: Change directory to where the scripts are present. - -.. code-block:: bash - - cd parser/yang2tosca - -Step 2: Copy the YANG file which needs to be converted into TOSCA to - current (parser/yang2tosca) folder. - -Step 3: Run the python script "parser.py" with the YANG file as an input option. - -.. code-block:: bash - - python parser.py -n "YANG filename" - -Example: - -.. code-block:: bash - - python parser.py -n example.yaml - -Step 4: Verify the TOSCA YAMl which file has been created with the same name - as the YANG file with a “_tosca” suffix. - -.. code-block:: bash - - cat "YANG filename_tosca.yaml" - -Example: - -.. code-block:: bash - - cat example_tosca.yaml diff --git a/docs/developer/overview/overview.rst b/docs/developer/overview/overview.rst index d1cad64..f9efebe 100644 --- a/docs/developer/overview/overview.rst +++ b/docs/developer/overview/overview.rst @@ -26,14 +26,23 @@ operators’ descriptors/records into TOSCA/CAMP templates and then further translate TOSCA/CAMP templates into certain common templates, which could be used in IaaS orchestration projects like OpenStack Heat. -Upgrades from Arno +For Arno Release ------------------------ +Parser is not one of the Arno Release projects, however the project has established +the code base for the later releases: -For Release B, Parser offers the following additional capabilities: +* OpenStack Heat Translator Kilo Release +* Initial documentation on use cases -* Integration of Heat-Translator Liberty release code. (both heat in-tree code and standalone package are provided) +Upgrades from Arno Release +------------------------ + +For Brahmaputra Release, Parser offers the following additional capabilities: + +* Update with the integration of OpenStack Heat-Translator Liberty Release, of which + both heat in-tree code and standalone package are provided. -* Yang2Tosca module which offers the capability to translate yang based +* New module yang2tosca module which offers the capability to translate yang based scriptors to tosca formate templates. Users could further use Heat-translator module to translate this tosca template to Heat Orchestration template. Yang2Tosca module could be installed seperately after user installed @@ -45,22 +54,22 @@ For Release B, Parser offers the following additional capabilities: from Release C to indicate which specific set of keywords are supported in Parser. -* The "vRNC_tosca_intro" document describes Parser's use case analysis on vRNC scenario. - The "example" folder contains examples of tosca-nfv standard and vRNC scenario. - See also https://wiki.opnfv.org/parser. +* The "vRNC_tosca_intro" document describes Parser's use case analysis on vRNC +scenario.The "example" folder contains examples of tosca-nfv standard and vRNC +scenario. See also https://wiki.opnfv.org/parser. -Upgrades from Brumapatra +Upgrades from Brahmaputra Release ----------------------- -For Release C, Parser offers the following additional capabilities: +For Colorado Release, Parser offers the following additional capabilities: -* Policy2Tosca module which enables policy related fields in tosca could be translated - into heat orchestration template correctly. Policy2Tosca module could be installed seperately - after user installed OPNFV C release platform. +* New module policy2tosca which enables policy related fields in tosca could be +translated into heat orchestration template correctly. Policy2Tosca module could +be installed seperately after user installed OPNFV C release platform. -* Tosca2Heat enhancements which includes a set of feature addons (such as substitution mapping) -for OpenStack tosca-parser module which is integrated in the OPNFV C release platform. And the -main details are listed below: +* New module tosca2heat enhancements which includes a set of feature addons (such +as substitution mapping) for OpenStack tosca-parser module which is integrated in +the OPNFV C release platform. And the main details are listed below: ** support substitution mapping semantic in tosca-parser: - support parse and validation about substitution mapping definition; @@ -82,8 +91,19 @@ main details are listed below: * Additional testing support. -Upgrades from Colorado ----------------------- +Upgrades from Colorado Release +------------------------------ + +For Danube Release, Parser offers the following additional capabilities: + +* New module verigraph which is a formal verification tool for service graphs. Given + a service graph, which can include stateful network functions and their configurations + (e.g., filtering rules for firewalls, and blacklists for anti-spamming filters), verigraph + can accurately and quickly check reachability properties in the graph (e.g. if a particular + flow of packets can go from one node of the graph to another node). Verigraph exploits + Satisfiability Modulo Theories (SMT) and the general-purpose SMT solver Z3. It includes a + library of network function models. -For Release D, Parser offers the following additional capabilities: +* The tosca2heat module updated with the intgeration of OpenStack tosca-parser and heat-translator + 0.7.0 releases. diff --git a/docs/developer/requirements/parser requirement arno release.rst b/docs/developer/requirements/parser requirement arno release.rst new file mode 100644 index 0000000..96d1d38 --- /dev/null +++ b/docs/developer/requirements/parser requirement arno release.rst @@ -0,0 +1,19 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +***************************************** +OPNFV Parser Requirements In Arno Release +***************************************** + +.. contents:: + :depth: 3 + :local: + +Use Case Description +--------------- + +* When Operators want to do automation on utilizing VIM to manage hypervisor +level accelerators which VNFs don't have knowledge of, certain templates +would be deployed and Parser would be used if operator defined template could +not be supported by VIM automation/orchestration tools directly. + diff --git a/governance/Committer/colorado release committer email motion vote record b/docs/governance/committer/colorado release committer email motion vote record similarity index 100% rename from governance/Committer/colorado release committer email motion vote record rename to docs/governance/committer/colorado release committer email motion vote record diff --git a/governance/Committer/parser project committer promotion guidline.rst b/docs/governance/committer/parser project committer promotion guidline.rst similarity index 100% rename from governance/Committer/parser project committer promotion guidline.rst rename to docs/governance/committer/parser project committer promotion guidline.rst diff --git a/docs/governance/index.rst b/docs/governance/index.rst new file mode 100644 index 0000000..6413aa9 --- /dev/null +++ b/docs/governance/index.rst @@ -0,0 +1,12 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +************************************* +OPNFV Parser Governance Documentation +************************************* + +.. toctree:: + :numbered: + :maxdepth: 6 + + ../committer/parser project committer promotion guidline.rst diff --git a/docs/release/installation/installation.instruction.rst b/docs/release/installation/installation.instruction.rst index 3a1417a..63a8b09 100644 --- a/docs/release/installation/installation.instruction.rst +++ b/docs/release/installation/installation.instruction.rst @@ -2,40 +2,66 @@ .. http://creativecommons.org/licenses/by/4.0 -Parser general configuration -===================== -Parser can be configured with any installer in current OPNFV. +Parser tosca2heat Installation +============================ + +Please follow the below installation steps to install tosca2heat submodule in parser. + +Step 1: Clone the parser project. + +.. code-block:: bash + + git clone https://gerrit.opnfv.org/gerrit/parser + +Step 2: Install the heat-translator sub project. -Pre-configuration activities ------------------------------ -For parser, there is not specific pre-configuration activities. +.. code-block:: bash + + # uninstall pre-installed tosca-parser + pip uninstall -y heat-translator + + # change directory to heat-translator + cd parser/tosca2heat/heat-translator + + # install requirements + pip install -r requirements.txt -Hardware configuration ------------------------ -For parser, there is not hardware configuration needed for this specific installer. + # install heat-translator + python setup.py install + +Step 3: Install the tosca-parser sub project. + +.. code-block:: bash -Jumphost configuration ------------------------ -For parser, there is not intial Jumphost configuration (network and software)needed in order -to deploy any installer. + # uninstall pre-installed tosca-parser + pip uninstall -y tosca-parser + # change directory to tosca-parser + cd parser/tosca2heat/tosca-parser -Parser tosca2heat configuration -===================== -For tosca2heat components(tosca-parser and heat-translator) in parser,there are not specific -configuration of each component in installer. + # install requirements + pip install -r requirements.txt + # install tosca-parser + python setup.py install -Parser yang2tosca configuration -===================== + + **Notes** It must uninstall pre-installed tosca-parser and heat-translator before install the two + components, and install heat-translator before installing tosca-parser, which is sure to use the + OPNFV version of tosca-parser and heat-translator other than openstack's components. + + +Parser yang2tosca Installation +============================== Parser yang2tosca requires the following to be installed. -1. PYANG --------- +Step 1: Clone the parser project. -Please follow the below installation steps. +.. code-block:: bash -Step 1: Clone pyang tool or download the zip file from the following link. + git clone https://gerrit.opnfv.org/gerrit/parser + +Step 2: Clone pyang tool or download the zip file from the following link. .. code-block:: bash @@ -47,30 +73,35 @@ OR wget https://github.com/mbj4668/pyang/archive/master.zip -Step 2: Change directory to the downloaded directory and run the setup file. +Step 3: Change directory to the downloaded directory and run the setup file. .. code-block:: bash cd pyang python setup.py -2. python-lxml +Step 4: install python-lxml -------------- Please follow the below installation link. http://lxml.de/installation.html -Parser policy2tosca configuration -============================ -Parser - POLICY2TOSCA requires the following to be installed. +Parser policy2tosca installation +================================ + +Please follow the below installation steps to install parser - POLICY2TOSCA. -1. cliff --------- +Step 1: Clone the parser project. + +.. code-block:: bash + + git clone https://gerrit.opnfv.org/gerrit/parser + +Step 2: Install the policy2tosca module. + +.. code-block:: bash -Install cliff with the following links. -:: -- `install ` -or -- `demoapp + cd parser/policy2tosca + python setup.py install diff --git a/docs/release/userguide/feature.userguide.rst b/docs/release/userguide/feature.userguide.rst index c42330c..e6e8974 100644 --- a/docs/release/userguide/feature.userguide.rst +++ b/docs/release/userguide/feature.userguide.rst @@ -2,53 +2,7 @@ .. http://creativecommons.org/licenses/by/4.0 .. (c) -Parser tosca2heat Installation -============================ - -Please follow the below installation steps to install tosca2heat submodule in parser. - -Step 1: Clone the parser project. - -.. code-block:: bash - - git clone https://gerrit.opnfv.org/gerrit/parser - -Step 2: Install the heat-translator sub project. - -.. code-block:: bash - - # uninstall pre-installed tosca-parser - pip uninstall -y heat-translator - - # change directory to heat-translator - cd parser/tosca2heat/heat-translator - - # install requirements - pip install -r requirements.txt - - # install heat-translator - python setup.py install - -Step 3: Install the tosca-parser sub project. - -.. code-block:: bash - - # uninstall pre-installed tosca-parser - pip uninstall -y tosca-parser - - # change directory to tosca-parser - cd parser/tosca2heat/tosca-parser - - # install requirements - pip install -r requirements.txt - - # install tosca-parser - python setup.py install - - **Notes** It must uninstall pre-installed tosca-parser and heat-translator before install the two - components, and install heat-translator before installing tosca-parser, which is sure to use the - OPNFV version of tosca-parser and heat-translator other than openstack's components. Parser tosca2heat Execution =========================== -- 2.16.6