docs/release/userguide/feature.userguide.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. (c) <optionally add copywriters name>
   4
   5
   6
   7 Parser tosca2heat Execution
   8 ===========================
   9
  10 nfv-heattranslator
  11 -------------------
  12
  13  There only one way to call nfv-heattranslator service: CLI.
  14
  15 Step 1: Change directory to where the tosca yaml files are present, example is
  16 below with vRNC definiton.
  17
  18 .. code-block:: bash
  19
  20     cd parser/tosca2heat/tosca-parser/toscaparser/extensions/nfv/tests/data/vRNC/Definitions
  21
  22
  23 Step 2: Run the python command heat-translator with the TOSCA yaml file as an input option.
  24
  25 .. code-block:: bash
  26
  27     heat-translator --template-file=<input file> --template-type=tosca
  28                     --outpurt-file=<output hot file>
  29
  30 Example:
  31
  32 .. code-block:: bash
  33
  34     heat-translator --template-file=vRNC.yaml \
  35         --template-type=tosca --output-file=vRNC_hot.yaml
  36
  37 **Notes**: nfv-heattranslator will call class of ToscaTemplate in nfv-toscaparser firstly to validate and
  38 parse input yaml file, then tranlate the file into hot file.
  39
  40
  41 nfv-toscaparser
  42 ----------------
  43
  44 Implementation of nfv-toscaparser derived from openstack tosca parser is based on the following OASIS specification:
  45     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
  46     TOSCA Simple Profile YAML NFV 1.0 Referecne  http://docs.oasis-open.org/tosca/tosca-nfv/v1.0/tosca-nfv-v1.0.html
  47
  48 There are three ways to call nfv-toscaparser service, Python Lib ,CLI and  REST API.
  49
  50 CLI
  51 ****
  52 Using cli, which is used to validate tosca simple based service template. It can be used as:
  53
  54 .. code-block:: bash
  55
  56    tosca-parser --template-file=<path to the YAML template>  [--nrpv]  [--debug]
  57    tosca-parser --template-file=<path to the CSAR zip file> [--nrpv]  [--debug]
  58    tosca-parser --template-file=<URL to the template or CSAR>  [--nrpv]  [--debug]
  59
  60    options:
  61      --nrpv Ignore input parameter validation when parse template.
  62      --debug debug mode for print more details other than raise exceptions when errors happen
  63
  64
  65 Library(Python)
  66 ****************
  67
  68 Using api, which is used to parse and get the result of service template. it can be used as:
  69
  70 .. code-block:: bash
  71
  72    ToscaTemplate(path=None, parsed_params=None, a_file=True, yaml_dict_tpl=None,
  73                                           sub_mapped_node_template=None,
  74                                           no_required_paras_valid=False, debug=False)
  75
  76 REST API
  77 *********
  78
  79 Using RESTfual API, which are listed as following:
  80
  81 List template versions
  82 ########################
  83
  84 PATH: /v1/template_versions
  85 METHOD:  GET
  86 Decription: Lists all supported tosca template versions.
  87
  88 Response Codes
  89
  90 Success
  91 200 - OK        Request was successful.
  92
  93 Error
  94
  95 400 - Bad Request       Some content in the request was invalid.
  96 404 - Not Found The requested resource could not be found.
  97 500 - Internal Server Error     Something went wrong inside the service. This should not happen usually.
  98 If it does happen, it means the server has experienced some serious problems.
  99
 100 Request Parameters
 101
 102 No
 103
 104 Response Parameters
 105
 106 template_versions       array   A list of tosca template version object each describes the type name and
 107  version information for a template version.
 108
 109
 110 Validates a service template
 111 #############################
 112
 113 PATH: /v1/validate
 114 METHOD:  POST
 115 Decription: Validate a service template.
 116
 117 Response Codes
 118 Success
 119 200 - OK        Request was successful.
 120
 121 Error
 122
 123 400 - Bad Request       Some content in the request was invalid.
 124 500 - Internal Server Error     Something went wrong inside the service. This should not happen usually.
 125  If it does happen, it means the server has experienced some serious problems.
 126 Request Parameters
 127 environment (Optional)  object  A JSON environment for the template service.
 128 environment_files (Optional)    object  An ordered list of names for environment files found in the files dict.
 129 files (Optional)        object
 130 Supplies the contents of files referenced in the template or the environment.
 131
 132 The value is a JSON object, where each key is a relative or absolute URI which serves as the name of
 133  a file, and the associated value provides the contents of the file. The following code shows the
 134  general structure of this parameter.
 135
 136 { ...
 137     "files": {
 138         "fileA.yaml": "Contents of the file",
 139         "file:///usr/fileB.template": "Contents of the file",
 140         "http://example.com/fileC.template": "Contents of the file"
 141     }
 142 ...
 143 }
 144 ignore_errors (Optional)        string  List of comma separated error codes to ignore.
 145 show_nested (Optional)  boolean Set to true to include nested template service in the list.
 146 template (Optional)     object
 147 The service template on which to perform the operation.
 148
 149 This parameter is always provided as a string in the JSON request body. The content of the string is
 150  a JSON- or YAML-formatted service template. For example:
 151
 152 "template": {
 153     "tosca_definitions_version": "tosca_simple_yaml_1_0",
 154     ...
 155 }
 156 This parameter is required only when you omit the template_url parameter. If you specify both
 157 parameters, this value overrides thetemplate_url parameter value.
 158
 159 template_url (Optional) string  A URI to the location containing the service template on which to
 160 perform the operation. See the description of the template parameter for information about the
 161 expected template content located at the URI. This parameter is only required when you omit the
 162 template parameter. If you specify both parameters, this parameter is ignored.
 163
 164 Request Example
 165 {
 166     "template_url": "/PATH_TO_TOSCA_TEMPLATES/HelloWord_Instance.csar"
 167 }
 168
 169 Response Parameters
 170 Description     string  The description specified in the template.
 171 Error Information (Optional)    string  Error information
 172
 173 Parse a service template
 174 #########################
 175
 176 PATH: /v1/validate
 177 METHOD:  POST
 178 Decription: Validate a service template.
 179 Response Code: same as "Validates a service template"
 180 Request Parameters: same as "Validates a service template"
 181 Response Parameters
 182 Description     string  The description specified in the template.
 183 Input parameters        object  Input parameter list.
 184 Service Template        object  Service template body
 185 Output parameters       object  Input parameter list.
 186 Error Information (Optional)    string  Error information
 187
 188
 189 Parser yang2tosca Execution
 190 ===========================
 191
 192 Step 1: Change directory to where the scripts are present.
 193
 194 .. code-block:: bash
 195
 196     cd parser/yang2tosca
 197
 198 Step 2: Copy the YANG file which needs to be converted into TOSCA to
 199         current (parser/yang2tosca) folder.
 200
 201 Step 3: Run the python script "parser.py" with the YANG file as an input option.
 202
 203 .. code-block:: bash
 204
 205     python parser.py -n "YANG filename"
 206
 207 Example:
 208
 209 .. code-block:: bash
 210
 211     python parser.py -n example.yaml
 212
 213 Step 4: Verify the TOSCA YAMl which file has been created with the same name
 214         as the YANG file with a “_tosca” suffix.
 215
 216 .. code-block:: bash
 217
 218     cat "YANG filename_tosca.yaml"
 219
 220 Example:
 221
 222 .. code-block:: bash
 223
 224     cat example_tosca.yaml
 225
 226
 227 Parser policy2tosca Execution
 228 =============================
 229
 230 Step 1: To see a list of commands available.
 231
 232 .. code-block:: bash
 233
 234     policy2tosca --help
 235
 236 Step 2: To see help for an individual command, include the command name on the command line
 237
 238 .. code-block:: bash
 239
 240     policy2tosca help <service>
 241
 242 Step 3: To inject/remove policy types/policy definitions provide the TOSCA file as input to
 243 policy2tosca command line.
 244
 245 .. code-block:: bash
 246
 247     policy2tosca <service> [arguments]
 248
 249 Example:
 250
 251 .. code-block:: bash
 252
 253     policy2tosca add-definition \
 254         --policy_name rule2 --policy_type  tosca.policies.Placement.Geolocation \
 255         --description "test description" \
 256         --properties region:us-north-1,region:us-north-2,min_inst:2 \
 257         --targets VNF2,VNF4 \
 258         --metadata "map of strings" \
 259         --triggers "1,2,3,4" \
 260         --source example.yaml
 261
 262
 263 Step 4: Verify the TOSCA YAMl updated with the injection/removal executed.
 264
 265 .. code-block:: bash
 266
 267     cat "<source tosca file>"
 268
 269 Example:
 270
 271 .. code-block:: bash
 272
 273     cat example_tosca.yaml
 274
 275
 276 Parser verigraph Execution
 277 ==========================
 278
 279 VeriGraph is accessible via both a RESTful API and a gRPC interface.
 280
 281 **REST API**
 282
 283 Step 1. Change directory to where the service graph examples are present
 284
 285 .. code-block:: bash
 286
 287    cd parser/verigraph/examples
 288
 289 Step 2. Use a REST client (e.g., cURL) to send a POST request (whose body is one of the JSON
 290 file in the directory)
 291
 292 .. code-block:: bash
 293
 294    curl -X POST -d @<file_name>.json http://<server_address>:<server_port>/verify/api/graphs
 295    --header "Content-Type:application/json"
 296
 297 Step 3. Use a REST client to send a GET request to check a reachability-based property between
 298 two nodes of the service graph created in the previous step.
 299
 300 .. code-block:: bash
 301
 302    curl -X GET http://<server_addr>:<server_port>/verify/api/graphs/<graphID>/
 303    policy?source=<srcNodeID>&destination=<dstNodeID>&type=<propertyType>
 304
 305 where:
 306
 307 - <graphID> is the identifier of the service graph created at Step 2
 308 - <srcNodeID> is the name of the source node
 309 - <dstNodeID> is the name of the destination node
 310 - <propertyType> can be ``reachability``, ``isolation`` or ``traversal``
 311
 312 Step 4. the output is a JSON with the overall result of the verification process and the partial
 313 result for each path that connects the source and destination nodes in the service graph.
 314
 315 **gRPC API**
 316
 317 VeriGraph exposes a gRPC interface that is self-descriptive by its Protobuf file
 318 (``parser/verigraph/src/main/proto/verigraph.proto``). In the current release, Verigraph
 319 misses a module that receives service graphs in format of JSON and sends the proper
 320 requests to the gRPC server. A testing client has been provided to have an example of how
 321 to create a service graph using the gRPC interface and to trigger the verification step.
 322
 323 1. Run the testing client
 324
 325 .. code-block:: bash
 326
 327       cd parser/verigraph
 328       #Client souce code in ``parser/verigraph/src/it/polito/verigraph/grpc/client/Client.java``
 329       ant -f buildVeriGraph_gRPC.xml run-client