summaryrefslogtreecommitdiffstats
path: root/docs/release/userguide/feature.userguide.rst
blob: 4d0d46e15d9737135cd5a851c34757266a7d6ce3 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. http://creativecommons.org/licenses/by/4.0
.. (c) <optionally add copywriters name>



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.

.. code-block:: bash

    cd parser/tosca2heat/tosca-parser/toscaparser/extensions/nfv/tests/data/vRNC/Definitions


Step 2: Run the python command heat-translator with the TOSCA yaml file as an input option.

.. code-block:: bash

    heat-translator --template-file=<input file> --template-type=tosca
                    --outpurt-file=<output hot file>

Example:

.. code-block:: bash

    heat-translator --template-file=vRNC.yaml \
        --template-type=tosca --output-file=vRNC_hot.yaml

**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]
   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:

.. code-block:: bash

   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


Parser yang2tosca 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


Parser policy2tosca 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 <service>

Step 3: To inject/remove policy types/policy definitions provide the TOSCA file as input to
policy2tosca command line.

.. code-block:: bash

    policy2tosca <service> [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 "<source tosca file>"

Example:

.. code-block:: bash

    cat example_tosca.yaml


Parser verigraph Execution
==========================

VeriGraph is accessible via both a RESTful API and a gRPC interface.

**REST API**

Step 1. Change directory to where the service graph examples are present

.. code-block:: bash

   cd parser/verigraph/examples

Step 2. Use a REST client (e.g., cURL) to send a POST request (whose body is one of the JSON
file in the directory)

.. code-block:: bash

   curl -X POST -d @<file_name>.json http://<server_address>:<server_port>/verify/api/graphs
   --header "Content-Type:application/json"

Step 3. Use a REST client to send a GET request to check a reachability-based property between
two nodes of the service graph created in the previous step.

.. code-block:: bash

   curl -X GET http://<server_addr>:<server_port>/verify/api/graphs/<graphID>/
   policy?source=<srcNodeID>&destination=<dstNodeID>&type=<propertyType>

where:

- <graphID> is the identifier of the service graph created at Step 2
- <srcNodeID> is the name of the source node
- <dstNodeID> is the name of the destination node
- <propertyType> can be ``reachability``, ``isolation`` or ``traversal``

Step 4. the output is a JSON with the overall result of the verification process and the partial
result for each path that connects the source and destination nodes in the service graph.

**gRPC API**

VeriGraph exposes a gRPC interface that is self-descriptive by its Protobuf file
(``parser/verigraph/src/main/proto/verigraph.proto``). In the current release, Verigraph
misses a module that receives service graphs in format of JSON and sends the proper
requests to the gRPC server. A testing client has been provided to have an example of how
to create a service graph using the gRPC interface and to trigger the verification step.

1. Run the testing client

.. code-block:: bash

      cd parser/verigraph
      #Client souce code in ``parser/verigraph/src/it/polito/verigraph/grpc/client/Client.java``
      ant -f buildVeriGraph_gRPC.xml run-client