aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authorKAPIL SINGAL <ks220y@att.com>2020-12-21 14:31:18 +0000
committerGerrit Code Review <gerrit@onap.org>2020-12-21 14:31:18 +0000
commit0b225997f9ad4ca12b47900b701ca6edaa425718 (patch)
tree2dbb82de97bf123c720f52086ea0d195b10cce46 /docs
parent8836e4b122cfffc8af1ee1e3ec367b77e43554aa (diff)
parent0d89a035e48cbe87440534ce79a2bb6b1cef2044 (diff)
Merge "CDS API Reference add workflow tutorial"
Diffstat (limited to 'docs')
-rw-r--r--docs/api-reference/bp-processor.rst98
-rw-r--r--docs/api-reference/media/dd-postman-runner.pngbin0 -> 140243 bytes
-rw-r--r--docs/api-reference/media/save-response-postman.pngbin0 -> 154196 bytes
-rw-r--r--docs/api-reference/media/workflow-tutorial-cba.zipbin0 -> 9437 bytes
-rw-r--r--docs/usecases/media/pnf-simulator.postman_collection.json215
-rw-r--r--docs/usecases/pnf-simulator.rst4
-rw-r--r--docs/userguides/developer-guide/running-bp-processor-in-ide.rst2
7 files changed, 273 insertions, 46 deletions
diff --git a/docs/api-reference/bp-processor.rst b/docs/api-reference/bp-processor.rst
index c4694c0bd..00dd7cce6 100644
--- a/docs/api-reference/bp-processor.rst
+++ b/docs/api-reference/bp-processor.rst
@@ -13,6 +13,19 @@ which is automatically created during CDS build process by Swagger Maven Plugin.
also included. Endpoints can also be described using this template
:download:`api-doc-template.rst <api-doc-template.rst>` but this is not the prefered way to describe the CDS API.
+You can find a sample workflow tutorial :ref:`below <workflow-tutorial>` which will show how to use the endpoints
+in the right order. This will give you a better understanding of the CDS Blueprint Processor API.
+
+Getting Started
+-----------------
+
+If you cant access a running CDS Blueprint Processor yet, you can choose one of the below options to run it.
+Afterwards you can start trying out the API.
+
+* CDS in Microk8s: https://wiki.onap.org/display/DW/Running+CDS+on+Microk8s (RDT link to be added)
+* CDS in Minikube: https://wiki.onap.org/display/DW/Running+CDS+in+minikube (RDT link to be added)
+* CDS in an IDE: :ref:`Running BP Processor Microservice in an IDE <running_bp_processor_in_ide>`
+
Authorization
-----------------
@@ -151,4 +164,87 @@ API Reference
rendered completely, e.g. the request body. Use your favorite Swagger Editor and paste the swagger file
to get a complete view of the API reference, e.g. on https://editor.swagger.io/.
-.. swaggerv2doc:: media/cds-bp-processor-api-swagger.json \ No newline at end of file
+.. swaggerv2doc:: media/cds-bp-processor-api-swagger.json
+
+
+
+.. _workflow-tutorial:
+
+Workflow Tutorial
+------------------
+
+Introduction
+~~~~~~~~~~~~~
+
+This section will show a basic workflow how to proceed a CBA. For this we will follow
+the :ref:`PNF Simulator use case <pnf_simulator_use_case>` guide. We will use the same CBA but since this CBA is loaded during
+bootstrap per default we will first delete it and afterwards manually enrich and save it in CDS.
+The referred use case shows how the day-n configuration is assigned and deployed to a PNF through CDS.
+You don't necessarily need a netconf server (which will act as an PNF Simulator) running to get a understanding about
+this workflow tutorial. Just take care that without a set up netconf server the day-n configuration deployment will fail
+in the last step.
+
+Use the Postman Collection from the referred use case to get sample requests for the following steps:
+:download:`json <../usecases/media/pnf-simulator.postman_collection.json>`.
+
+The CBA which we are using is downloadable here :download:`zip <media/workflow-tutorial-cba.zip>`. Hint: this CBA is
+also included in the CDS source code for bootstrapping.
+
+Set up CDS
+~~~~~~~~~~
+
+If not done before, run `Bootrap` request which will call Bootstrap API of CDS (``POST /api/v1/blueprint-model/bootstrap``)
+to load all the CDS default model artifacts into CDS. You should get HTTP status 200 for the below command.
+
+Call `Get Blueprints` request to get all blueprint models which are saved in CDS. This will call the ``GET /api/v1/blueprint-model``
+endpoint. You will see the blueprint model ``"artifactName": "pnf_netconf"`` which is loaded by calling bootstrap since Guilin release.
+Since we manually want to load the CBA delete the desired CBA from CDS first through calling the delete endpoint
+``DELETE /api/v1/blueprint-model/name/{name}/version/{version}``. If you call `Get Blueprints` again you can see that the
+``pnf_netconf`` CBA is missing now.
+
+Because the CBA contains a custom data dictionary we need to push the custom entries to CDS first through calling `Data Dictionary` request.
+Actually the custom entries are also already loaded through bootstrap but just pretend they are not present in CDS so far.
+
+.. note::
+ For every data dictionary entry CDS API needs to be called seperately. The postman collection contains a loop to
+ go through all custom entries and call data dictionary endpoint seperately. To execute this loop,
+ open `Runner` in Postman and run `Data Dictionary` request like it is shown in the picture below.
+
+ |imageDDPostmanRunner|
+
+
+Enrichment
+~~~~~~~~~~~~
+
+Enrich the blueprint through executing the `Enrich Blueprint` request. Take care to provide the CBA file which you
+can download here :download:`zip <media/workflow-tutorial-cba.zip>` in the request body. After the request got executed
+download the response body like shown in the picture below, this will be your enriched CBA file.
+
+|saveResponseImage|
+
+
+Deploy/Save the Blueprint
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Run `Save Blueprint` request to save/deploy the Blueprint into the CDS database. Take care to provide the enriched
+CBA file which you downloaded earlier in the request body.
+
+After that you should see the new model ``"artifactName": "pnf_netconf"`` by calling `Get Blueprints` request.
+
+An alternative would be to use ``POST /api/v1/blueprint-model/publish`` endpoint, which would also validate the CBA.
+For doing enrichment and saving the CBA in a single call ``POST /api/v1/blueprint-model/enrichandpublish`` could also be used.
+
+Config-Assign / Config-Deploy
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+From now on you can continue with the :ref:`PNF Simulator use case <pnf_simulator_use_case_config_assign_deploy>` from section
+`Config-assign and config-deploy` to finish the workflow tutorial. The provided Postman collection already contains all
+the needed requests also for this part so you don't need to create the calls and payloads manually.
+Take care that the last step will fail if you don't have a netconf server set up.
+
+
+.. |imageDDPostmanRunner| image:: media/dd-postman-runner.png
+ :width: 500pt
+
+.. |saveResponseImage| image:: media/save-response-postman.png
+ :width: 500pt \ No newline at end of file
diff --git a/docs/api-reference/media/dd-postman-runner.png b/docs/api-reference/media/dd-postman-runner.png
new file mode 100644
index 000000000..747e86231
--- /dev/null
+++ b/docs/api-reference/media/dd-postman-runner.png
Binary files differ
diff --git a/docs/api-reference/media/save-response-postman.png b/docs/api-reference/media/save-response-postman.png
new file mode 100644
index 000000000..d46c0fe21
--- /dev/null
+++ b/docs/api-reference/media/save-response-postman.png
Binary files differ
diff --git a/docs/api-reference/media/workflow-tutorial-cba.zip b/docs/api-reference/media/workflow-tutorial-cba.zip
new file mode 100644
index 000000000..c60a07c68
--- /dev/null
+++ b/docs/api-reference/media/workflow-tutorial-cba.zip
Binary files differ
diff --git a/docs/usecases/media/pnf-simulator.postman_collection.json b/docs/usecases/media/pnf-simulator.postman_collection.json
index cab40da85..b160d061a 100644
--- a/docs/usecases/media/pnf-simulator.postman_collection.json
+++ b/docs/usecases/media/pnf-simulator.postman_collection.json
@@ -1,6 +1,6 @@
{
"info": {
- "_postman_id": "0175f488-96af-4253-ad35-d2a670330091",
+ "_postman_id": "835c7d3a-d5c4-4f5b-a80f-b2870da7850c",
"name": "CDS PNF Simulator Use Case",
"description": "This collection contains all API calls to do the \"PNF Simulator Day-N config-assign and config-deploy use case\" in CDS. ",
"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
@@ -42,10 +42,7 @@
],
"body": {
"mode": "raw",
- "raw": "{\r\n\"loadModelType\" : true,\r\n\"loadResourceDictionary\" : true,\r\n\"loadCBA\" : true\r\n}",
- "options": {
- "raw": {}
- }
+ "raw": "{\r\n\"loadModelType\" : true,\r\n\"loadResourceDictionary\" : true,\r\n\"loadCBA\" : true\r\n}"
},
"url": {
"raw": "http://{{host}}:{{port}}/api/v1/blueprint-model/bootstrap",
@@ -81,10 +78,7 @@
],
"body": {
"mode": "raw",
- "raw": "{\r\n\"loadModelType\" : false,\r\n\"loadResourceDictionary\" : true,\r\n\"loadCBA\" : false\r\n}",
- "options": {
- "raw": {}
- }
+ "raw": "{\r\n\"loadModelType\" : false,\r\n\"loadResourceDictionary\" : true,\r\n\"loadCBA\" : false\r\n}"
},
"url": {
"raw": "http://localhost:8081/api/v1/blueprint-model/bootstrap",
@@ -207,10 +201,7 @@
],
"body": {
"mode": "raw",
- "raw": "{\r\n\"loadModelType\" : true,\r\n\"loadResourceDictionary\" : true,\r\n\"loadCBA\" : false\r\n}",
- "options": {
- "raw": {}
- }
+ "raw": "{\r\n\"loadModelType\" : true,\r\n\"loadResourceDictionary\" : true,\r\n\"loadCBA\" : false\r\n}"
},
"url": {
"raw": "http://{{host}}:{{port}}/api/v1/blueprint-model",
@@ -245,10 +236,167 @@
],
"body": {
"mode": "raw",
- "raw": "{\r\n\"loadModelType\" : false,\r\n\"loadResourceDictionary\" : true,\r\n\"loadCBA\" : false\r\n}",
- "options": {
- "raw": {}
+ "raw": "{\r\n\"loadModelType\" : false,\r\n\"loadResourceDictionary\" : true,\r\n\"loadCBA\" : false\r\n}"
+ },
+ "url": {
+ "raw": "http://localhost:8081/api/v1/blueprint-model/bootstrap",
+ "protocol": "http",
+ "host": [
+ "localhost"
+ ],
+ "port": "8081",
+ "path": [
+ "api",
+ "v1",
+ "blueprint-model",
+ "bootstrap"
+ ]
+ }
+ },
+ "status": "OK",
+ "code": 200,
+ "_postman_previewlanguage": "json",
+ "header": [
+ {
+ "key": "X-ONAP-RequestID",
+ "value": "b73253b6-d2be-4701-bdb2-31fa66b79a01"
+ },
+ {
+ "key": "X-ONAP-InvocationID",
+ "value": "b1a59296-fcf2-4435-b8de-9a2e9b9f4077"
+ },
+ {
+ "key": "X-ONAP-PartnerName",
+ "value": "cds-controller"
+ },
+ {
+ "key": "Vary",
+ "value": "Origin"
+ },
+ {
+ "key": "Vary",
+ "value": "Access-Control-Request-Method"
+ },
+ {
+ "key": "Vary",
+ "value": "Access-Control-Request-Headers"
+ },
+ {
+ "key": "Content-Type",
+ "value": "application/json"
+ },
+ {
+ "key": "Content-Length",
+ "value": "0"
+ },
+ {
+ "key": "Cache-Control",
+ "value": "no-cache, no-store, max-age=0, must-revalidate"
+ },
+ {
+ "key": "Pragma",
+ "value": "no-cache"
+ },
+ {
+ "key": "Expires",
+ "value": "0"
+ },
+ {
+ "key": "X-Content-Type-Options",
+ "value": "nosniff"
+ },
+ {
+ "key": "X-Frame-Options",
+ "value": "DENY"
+ },
+ {
+ "key": "X-XSS-Protection",
+ "value": "1 ; mode=block"
+ },
+ {
+ "key": "Referrer-Policy",
+ "value": "no-referrer"
+ }
+ ],
+ "cookie": [],
+ "body": ""
+ }
+ ]
+ },
+ {
+ "name": "Delete Blueprint Model loaded in Bootstrap",
+ "protocolProfileBehavior": {
+ "disabledSystemHeaders": {}
+ },
+ "request": {
+ "auth": {
+ "type": "basic",
+ "basic": [
+ {
+ "key": "password",
+ "value": "ccsdkapps",
+ "type": "string"
+ },
+ {
+ "key": "username",
+ "value": "ccsdkapps",
+ "type": "string"
+ }
+ ]
+ },
+ "method": "DELETE",
+ "header": [
+ {
+ "key": "Content-Type",
+ "value": "application/json",
+ "disabled": true
+ },
+ {
+ "key": "",
+ "type": "text",
+ "value": "",
+ "disabled": true
+ }
+ ],
+ "url": {
+ "raw": "http://{{host}}:{{port}}/api/v1/blueprint-model/name/pnf_netconf/version/1.0.0",
+ "protocol": "http",
+ "host": [
+ "{{host}}"
+ ],
+ "port": "{{port}}",
+ "path": [
+ "api",
+ "v1",
+ "blueprint-model",
+ "name",
+ "pnf_netconf",
+ "version",
+ "1.0.0"
+ ]
+ },
+ "description": "Delete a blueprint model identified by its name and version from CDS."
+ },
+ "response": [
+ {
+ "name": "CDS Bootstrap",
+ "originalRequest": {
+ "method": "POST",
+ "header": [
+ {
+ "key": "Content-Type",
+ "value": "application/json"
+ },
+ {
+ "key": "",
+ "value": "",
+ "type": "text",
+ "disabled": true
}
+ ],
+ "body": {
+ "mode": "raw",
+ "raw": "{\r\n\"loadModelType\" : false,\r\n\"loadResourceDictionary\" : true,\r\n\"loadCBA\" : false\r\n}"
},
"url": {
"raw": "http://localhost:8081/api/v1/blueprint-model/bootstrap",
@@ -341,7 +489,6 @@
{
"listen": "prerequest",
"script": {
- "id": "697ce54a-7333-4b86-9d51-9591f741ad7d",
"exec": [
"var allDD = pm.environment.get(\"allDD\");\r",
"\r",
@@ -517,7 +664,6 @@
{
"listen": "test",
"script": {
- "id": "ba9ff38c-cfb4-4e76-a58c-11c28b62a394",
"exec": [
"var allDD = pm.environment.get(\"allDD\");\r",
"\r",
@@ -631,12 +777,9 @@
{
"key": "file",
"type": "file",
- "src": "/home/jakob/CDS_Use_Cases/PNF-DEMO-ENRICHED_WORKING/pnf-demo.zip"
+ "src": "/home/jakob/Downloads/workflow-tutorial-cba.zip"
}
- ],
- "options": {
- "formdata": {}
- }
+ ]
},
"url": {
"raw": "http://{{host}}:{{port}}/api/v1/blueprint-model/enrich",
@@ -692,12 +835,9 @@
{
"key": "file",
"type": "file",
- "src": "/home/jakob/CDS_Use_Cases/PNF-DEMO-ENRICHED_WORKING/pnf-demo.zip"
+ "src": "/home/jakob/Downloads/workflow-tutorial-cba-enriched.zip"
}
- ],
- "options": {
- "formdata": {}
- }
+ ]
},
"url": {
"raw": "http://{{host}}:{{port}}/api/v1/blueprint-model",
@@ -732,10 +872,7 @@
],
"body": {
"mode": "raw",
- "raw": "{\r\n\"loadModelType\" : false,\r\n\"loadResourceDictionary\" : true,\r\n\"loadCBA\" : false\r\n}",
- "options": {
- "raw": {}
- }
+ "raw": "{\r\n\"loadModelType\" : false,\r\n\"loadResourceDictionary\" : true,\r\n\"loadCBA\" : false\r\n}"
},
"url": {
"raw": "http://localhost:8081/api/v1/blueprint-model/bootstrap",
@@ -876,7 +1013,6 @@
"mode": "raw",
"raw": "{\n\n \"actionIdentifiers\": {\n \"mode\": \"sync\",\n \"blueprintName\": \"pnf_netconf\",\n \"blueprintVersion\": \"1.0.0\",\n \"actionName\": \"config-assign\"\n },\n \"payload\": {\n \"config-assign-request\": {\n \"resolution-key\": \"day-1\",\n \"config-assign-properties\": {\n \"stream-count\": 5\n }\n }\n },\n \"commonHeader\": {\n \"subRequestId\": \"143748f9-3cd5-4910-81c9-a4601ff2ea58\",\n \"requestId\": \"e5eb1f1e-3386-435d-b290-d49d8af8db4c\",\n \"originatorId\": \"SDNC_DG\"\n }\n}",
"options": {
- "formdata": {},
"raw": {
"language": "json"
}
@@ -953,7 +1089,6 @@
"mode": "raw",
"raw": "{\n \"actionIdentifiers\": {\n \"mode\": \"sync\",\n \"blueprintName\": \"pnf_netconf\",\n \"blueprintVersion\": \"1.0.0\",\n \"actionName\": \"config-assign\"\n },\n \"payload\": {\n \"config-assign-request\": {\n \"resolution-key\": \"day-2\",\n \"config-assign-properties\": {\n \"stream-count\": 10\n }\n }\n },\n \"commonHeader\": {\n \"subRequestId\": \"143748f9-3cd5-4910-81c9-a4601ff2ea58\",\n \"requestId\": \"e5eb1f1e-3386-435d-b290-d49d8af8db4c\",\n \"originatorId\": \"SDNC_DG\"\n }\n}",
"options": {
- "formdata": {},
"raw": {
"language": "json"
}
@@ -1030,7 +1165,6 @@
"mode": "raw",
"raw": "{\n\t\"actionIdentifiers\": {\n\t\t\"mode\": \"sync\",\n\t\t\"blueprintName\": \"pnf_netconf\",\n\t\t\"blueprintVersion\": \"1.0.0\",\n\t\t\"actionName\": \"config-deploy\"\n\t},\n\t\"payload\": {\n\t\t\"config-deploy-request\": {\n\t\t\t\"resolution-key\": \"day-1\",\n\t\t\t\t\"pnf-ipv4-address\": \"{{pnf-ipv4-address}}\",\n \"netconf-username\": \"{{netconf-username}}\",\n\t\t\t\t\"netconf-password\": \"{{netconf-password}}\"\n\t\t}\n\t},\n\t\"commonHeader\": {\n\t\t\"subRequestId\": \"143748f9-3cd5-4910-81c9-a4601ff2ea58\",\n\t\t\"requestId\": \"e5eb1f1e-3386-435d-b290-d49d8af8db4c\",\n\t\t\"originatorId\": \"SDNC_DG\"\n\t}\n}",
"options": {
- "formdata": {},
"raw": {
"language": "json"
}
@@ -1107,7 +1241,6 @@
"mode": "raw",
"raw": "{\n\t\"actionIdentifiers\": {\n\t\t\"mode\": \"sync\",\n\t\t\"blueprintName\": \"pnf_netconf\",\n\t\t\"blueprintVersion\": \"1.0.0\",\n\t\t\"actionName\": \"config-deploy\"\n\t},\n\t\"payload\": {\n\t\t\"config-deploy-request\": {\n\t\t\t\"resolution-key\": \"day-2\",\n\t\t\t\t\"pnf-ipv4-address\": \"{{pnf-ipv4-address}}\",\n \"netconf-username\": \"{{netconf-username}}\",\n\t\t\t\t\"netconf-password\": \"{{netconf-password}}\"\n\t\t}\n\t},\n\t\"commonHeader\": {\n\t\t\"subRequestId\": \"143748f9-3cd5-4910-81c9-a4601ff2ea58\",\n\t\t\"requestId\": \"e5eb1f1e-3386-435d-b290-d49d8af8db4c\",\n\t\t\"originatorId\": \"SDNC_DG\"\n\t}\n}",
"options": {
- "formdata": {},
"raw": {
"language": "json"
}
@@ -1135,7 +1268,6 @@
{
"listen": "prerequest",
"script": {
- "id": "b3476f00-24ef-4484-af58-525137927dc5",
"type": "text/javascript",
"exec": [
""
@@ -1145,7 +1277,6 @@
{
"listen": "test",
"script": {
- "id": "4715993f-2476-4d02-a1e3-7f72b9dafeba",
"type": "text/javascript",
"exec": [
""
@@ -1155,30 +1286,24 @@
],
"variable": [
{
- "id": "a1d2b48e-7c0f-4c95-a476-430be6228e95",
"key": "host",
"value": "localhost"
},
{
- "id": "9202dd75-6852-44fd-b7b0-b8ad0714e8c7",
"key": "port",
"value": "8081"
},
{
- "id": "0087a55c-64f3-44c6-9b56-6300c4b4362e",
"key": "pnf-ipv4-address",
"value": "127.17.0.2"
},
{
- "id": "fd1a7cfe-9526-4261-beb4-61935e8d4ab0",
"key": "netconf-username",
"value": "netconf"
},
{
- "id": "8b004a49-14a3-415e-9646-5c82033bf0ea",
"key": "netconf-password",
"value": "netconf"
}
- ],
- "protocolProfileBehavior": {}
+ ]
} \ No newline at end of file
diff --git a/docs/usecases/pnf-simulator.rst b/docs/usecases/pnf-simulator.rst
index 2f6c8472d..83883a241 100644
--- a/docs/usecases/pnf-simulator.rst
+++ b/docs/usecases/pnf-simulator.rst
@@ -3,6 +3,8 @@
.. International License. http://creativecommons.org/licenses/by/4.0
.. Copyright (C) 2020 Deutsche Telekom AG.
+.. _pnf_simulator_use_case:
+
PNF Simulator Day-N config-assign/deploy
========================================
@@ -327,6 +329,8 @@ here but they are not tested by the author of this guide.
docker ps -a | grep netopeer
+.. _pnf_simulator_use_case_config_assign_deploy:
+
Config-assign and config-deploy in CDS
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/userguides/developer-guide/running-bp-processor-in-ide.rst b/docs/userguides/developer-guide/running-bp-processor-in-ide.rst
index ab6ae2314..e31246b01 100644
--- a/docs/userguides/developer-guide/running-bp-processor-in-ide.rst
+++ b/docs/userguides/developer-guide/running-bp-processor-in-ide.rst
@@ -3,6 +3,8 @@
.. International License. http://creativecommons.org/licenses/by/4.0
.. Copyright (C) 2020 Deutsche Telekom AG.
+.. _running_bp_processor_in_ide:
+
Running Blueprints Processor Microservice in an IDE
====================================================