From 0d89a035e48cbe87440534ce79a2bb6b1cef2044 Mon Sep 17 00:00:00 2001 From: JakobKrieg Date: Mon, 21 Dec 2020 09:23:05 +0100 Subject: CDS API Reference add workflow tutorial Issue-ID: CCSDK-3060 Change-Id: I9e3465f4fff816ad8dcdb74f54713e11d9d246cd Signed-off-by: JakobKrieg --- docs/api-reference/bp-processor.rst | 98 +++++++++- docs/api-reference/media/dd-postman-runner.png | Bin 0 -> 140243 bytes docs/api-reference/media/save-response-postman.png | Bin 0 -> 154196 bytes docs/api-reference/media/workflow-tutorial-cba.zip | Bin 0 -> 9437 bytes .../media/pnf-simulator.postman_collection.json | 215 ++++++++++++++++----- docs/usecases/pnf-simulator.rst | 4 + .../running-bp-processor-in-ide.rst | 2 + 7 files changed, 273 insertions(+), 46 deletions(-) create mode 100644 docs/api-reference/media/dd-postman-runner.png create mode 100644 docs/api-reference/media/save-response-postman.png create mode 100644 docs/api-reference/media/workflow-tutorial-cba.zip (limited to 'docs') 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 ` but this is not the prefered way to describe the CDS API. +You can find a sample workflow tutorial :ref:`below ` 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 ` + 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 ` 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 `. 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 ` 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 ` 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 Binary files /dev/null and b/docs/api-reference/media/dd-postman-runner.png 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 Binary files /dev/null and b/docs/api-reference/media/save-response-postman.png 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 Binary files /dev/null and b/docs/api-reference/media/workflow-tutorial-cba.zip 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 ==================================================== -- cgit 1.2.3-korg