From b7beaee4f6759c1c5997713901f6f5a1dfdb1d2d Mon Sep 17 00:00:00 2001 From: JakobKrieg Date: Tue, 1 Dec 2020 14:17:11 +0100 Subject: CDS Read the Docs refactoring Issue-ID: CCSDK-3011 Change-Id: Id8cff94b104bfa03643eb534e36c2bce8b0b4088 Signed-off-by: JakobKrieg --- docs/cba/cba-description.rst | 41 ++ docs/cba/index.rst | 37 +- docs/index.rst | 25 +- docs/modelingconcepts/cba.rst | 37 +- docs/modelingconcepts/index.rst | 2 + docs/userguide/designtime.rst | 50 --- docs/userguide/developer-guide.rst | 34 -- docs/userguide/installation.rst | 91 ----- docs/userguide/media/blueprintprocessor.jpg | Bin 63829 -> 0 bytes docs/userguide/media/build_logs.png | Bin 126733 -> 0 bytes docs/userguide/media/create_run_config_java.png | Bin 83005 -> 0 bytes docs/userguide/media/create_run_config_kt.png | Bin 95597 -> 0 bytes docs/userguide/media/expand_vm_options.PNG | Bin 17547 -> 0 bytes docs/userguide/media/import_project.png | Bin 35239 -> 0 bytes docs/userguide/media/reimport_maven.png | Bin 138930 -> 0 bytes docs/userguide/media/run-config-set-up.png | Bin 45625 -> 0 bytes docs/userguide/media/run_config_java.png | Bin 73102 -> 0 bytes docs/userguide/media/run_config_kt.png | Bin 56159 -> 0 bytes docs/userguide/media/run_debug.png | Bin 4509 -> 0 bytes docs/userguide/media/vsc_logs.png | Bin 161184 -> 0 bytes docs/userguide/resourceassignment.rst | 74 ---- docs/userguide/running-bp-processor-in-ide.rst | 424 -------------------- docs/userguides/design-time-guide/designtime.rst | 50 +++ .../design-time-guide/resourceassignment.rst | 74 ++++ docs/userguides/developer-guide/index.rst | 35 ++ .../developer-guide/media/blueprintprocessor.jpg | Bin 0 -> 63829 bytes .../developer-guide/media/build_logs.png | Bin 0 -> 126733 bytes .../media/create_run_config_java.png | Bin 0 -> 83005 bytes .../developer-guide/media/create_run_config_kt.png | Bin 0 -> 95597 bytes .../developer-guide/media/expand_vm_options.PNG | Bin 0 -> 17547 bytes .../developer-guide/media/import_project.png | Bin 0 -> 35239 bytes .../developer-guide/media/reimport_maven.png | Bin 0 -> 138930 bytes .../developer-guide/media/run_config_java.png | Bin 0 -> 73102 bytes .../developer-guide/media/run_config_kt.png | Bin 0 -> 56159 bytes .../developer-guide/media/run_config_set_up.png | Bin 0 -> 45625 bytes .../userguides/developer-guide/media/run_debug.png | Bin 0 -> 4509 bytes docs/userguides/developer-guide/media/vsc_logs.png | Bin 0 -> 161184 bytes .../running-bp-processor-in-ide.rst | 428 +++++++++++++++++++++ docs/userguides/installation.rst | 91 +++++ 39 files changed, 737 insertions(+), 756 deletions(-) create mode 100644 docs/cba/cba-description.rst delete mode 100644 docs/userguide/designtime.rst delete mode 100644 docs/userguide/developer-guide.rst delete mode 100644 docs/userguide/installation.rst delete mode 100644 docs/userguide/media/blueprintprocessor.jpg delete mode 100644 docs/userguide/media/build_logs.png delete mode 100644 docs/userguide/media/create_run_config_java.png delete mode 100644 docs/userguide/media/create_run_config_kt.png delete mode 100644 docs/userguide/media/expand_vm_options.PNG delete mode 100644 docs/userguide/media/import_project.png delete mode 100644 docs/userguide/media/reimport_maven.png delete mode 100644 docs/userguide/media/run-config-set-up.png delete mode 100644 docs/userguide/media/run_config_java.png delete mode 100644 docs/userguide/media/run_config_kt.png delete mode 100644 docs/userguide/media/run_debug.png delete mode 100644 docs/userguide/media/vsc_logs.png delete mode 100644 docs/userguide/resourceassignment.rst delete mode 100644 docs/userguide/running-bp-processor-in-ide.rst create mode 100644 docs/userguides/design-time-guide/designtime.rst create mode 100644 docs/userguides/design-time-guide/resourceassignment.rst create mode 100644 docs/userguides/developer-guide/index.rst create mode 100644 docs/userguides/developer-guide/media/blueprintprocessor.jpg create mode 100644 docs/userguides/developer-guide/media/build_logs.png create mode 100644 docs/userguides/developer-guide/media/create_run_config_java.png create mode 100644 docs/userguides/developer-guide/media/create_run_config_kt.png create mode 100644 docs/userguides/developer-guide/media/expand_vm_options.PNG create mode 100644 docs/userguides/developer-guide/media/import_project.png create mode 100644 docs/userguides/developer-guide/media/reimport_maven.png create mode 100644 docs/userguides/developer-guide/media/run_config_java.png create mode 100644 docs/userguides/developer-guide/media/run_config_kt.png create mode 100644 docs/userguides/developer-guide/media/run_config_set_up.png create mode 100644 docs/userguides/developer-guide/media/run_debug.png create mode 100644 docs/userguides/developer-guide/media/vsc_logs.png create mode 100644 docs/userguides/developer-guide/running-bp-processor-in-ide.rst create mode 100644 docs/userguides/installation.rst (limited to 'docs') diff --git a/docs/cba/cba-description.rst b/docs/cba/cba-description.rst new file mode 100644 index 000000000..08702fbce --- /dev/null +++ b/docs/cba/cba-description.rst @@ -0,0 +1,41 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 +.. International License. http://creativecommons.org/licenses/by/4.0 +.. Copyright (C) 2019 IBM. + + +The **C**\ ontroller **B**\ lueprint **A**\ rchive is the overall service design, fully model-driven, intent based +**package** needed for SELF SERVICE provisioning and configuration management automation. + +The CBA is **.zip** file, comprised of the following folder structure, the files may vary: + +.. code-block language is required for ReadTheDocs to render code-blocks. Python set as default. + +.. code-block:: python + + ├── Definitions + │ ├── blueprint.json Overall TOSCA service template (workflow + node_template) + │ ├── artifact_types.json (generated by enrichment) + │ ├── data_types.json (generated by enrichment) + │ ├── policy_types.json (generated by enrichment) + │ ├── node_types.json (generated by enrichment) + │ ├── relationship_types.json (generated by enrichment) + │ ├── resources_definition_types.json (generated by enrichment, based on Data Dictionaries) + │ └── *-mapping.json One per Template + │ + ├── Environments Contains *.properties files as required by the service + │ + ├── Plans Contains Directed Graph + │ + ├── Tests Contains uat.yaml file for testing cba actions within a cba package + │ + ├── Scripts Contains scripts + │ ├── python Python scripts + │ └── kotlin Kotlin scripts + │ + ├── TOSCA-Metadata + │ └── TOSCA.meta Meta-data of overall package + │ + └── Templates Contains combination of mapping and template + +To process a CBA for any service we need to enrich it first. This will gather all the node- type, data-type, +artifact-type, data-dictionary definitions provided in the blueprint.json. diff --git a/docs/cba/index.rst b/docs/cba/index.rst index 70ed2aef8..62eb92717 100644 --- a/docs/cba/index.rst +++ b/docs/cba/index.rst @@ -11,43 +11,8 @@ Controller Blueprint Archived Designer Tool (CBA) Introduction ------------ -The **C**\ ontroller **B**\ lueprint **A**\ rchive is the overall service design, fully model-driven, intent based -**package** needed for SELF SERVICE provisioning and configuration management automation. - -The CBA is **.zip** file, comprised of the following folder structure, the files may vary: - -.. code-block language is required for ReadTheDocs to render code-blocks. Python set as default. - -.. code-block:: python - - ├── Definitions - │ ├── blueprint.json Overall TOSCA service template (workflow + node_template) - │ ├── artifact_types.json (generated by enrichment) - │ ├── data_types.json (generated by enrichment) - │ ├── policy_types.json (generated by enrichment) - │ ├── node_types.json (generated by enrichment) - │ ├── relationship_types.json (generated by enrichment) - │ ├── resources_definition_types.json (generated by enrichment, based on Data Dictionaries) - │ └── *-mapping.json One per Template - │ - ├── Environments Contains *.properties files as required by the service - │ - ├── Plans Contains Directed Graph - │ - ├── Tests Contains uat.yaml file for testing cba actions within a cba package - │ - ├── Scripts Contains scripts - │ ├── python Python scripts - │ └── kotlin Kotlin scripts - │ - ├── TOSCA-Metadata - │ └── TOSCA.meta Meta-data of overall package - │ - └── Templates Contains combination of mapping and template - -To process a CBA for any service we need to enrich it first. This will gather all the node- type, data-type, -artifact-type, data-dictionary definitions provided in the blueprint.json. +.. include:: cba-description.rst Architecture ------------ diff --git a/docs/index.rst b/docs/index.rst index af25a5940..ef2d94f91 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -12,13 +12,14 @@ CONTROLLER DESIGN STUDIO (CDS) Introduction ------------ - The system is designed to be self service, which means that users, not just + +The system is designed to be self service, which means that users, not just programmers, can reconfigure the software system as needed to meet customer requirements. To accomplish this goal, the system is built around models that provide for real-time changes in how the system operates. Users merely need to change a model to change how a service operates. - Self service is a completely new way of delivering services. It removes the +Self service is a completely new way of delivering services. It removes the dependence on code releases and the delays they cause and puts the control of services into the hands of the service providers. They can change a model and its parameters and create a new service without writing a single line of code. @@ -27,18 +28,19 @@ deliver products that more closely match the needs of its customers. Architecture ------------ + The Controller Design Studio is composed of two major components: * The GUI (or frontend) * The Run Time (or backend) - The GUI handles direct user input and allows for displaying both design time +The GUI handles direct user input and allows for displaying both design time and run time activities. For design time, it allows for the creation of controller blueprint, from selecting the DGs to be included, to incorporating the artifact templates, to adding necessary components. For run time, it allows the user to direct the system to resolve the unresolved elements of the controller blueprint and download the resulting configuration into a VNF. - At a more basic level, it allows for creation of data dictionaries, +At a more basic level, it allows for creation of data dictionaries, capabilities catalogs, and controller blueprint, the basic elements that are used to generate a configuration. The essential function of the Controller Design Studio is to create and populate a controller blueprint, create a @@ -51,11 +53,11 @@ configuration file (configlet) to a VNF/PNF. Modeling Concept ---------------- - In Dublin release, the CDS community has contributed a framework to automate +In Dublin release, the CDS community has contributed a framework to automate the resolution of resources for instantiation and any config provisioning operation, such as day0, day1 or day2 configuration. - The content of the CBA Package is driven from a catalog of reusable data +The content of the CBA Package is driven from a catalog of reusable data dictionary, component and workflow, delivering a reusable and simplified self service experience. @@ -105,15 +107,16 @@ Library .. |cdsArchitectureImage| image:: media/CDS_architecture.jpg :width: 500pt -User Guide ----------- +User Guides +------------ .. toctree:: :maxdepth: 3 - userguide/developer-guide - userguide/installation - userguide/designtime + userguides/developer-guide/index + userguides/installation + userguides/design-time-guide/designtime + userguides/resourceassignment Use Cases --------- diff --git a/docs/modelingconcepts/cba.rst b/docs/modelingconcepts/cba.rst index 41baa9924..a352e760a 100644 --- a/docs/modelingconcepts/cba.rst +++ b/docs/modelingconcepts/cba.rst @@ -9,39 +9,4 @@ Controller Blueprint Archive (.cba) ----------------------------------- -The **C**\ ontroller **B**\ lueprint **A**\ rchive is the overall service design, fully model-driven, intent based -**package** needed for SELF SERVICE provisioning and configuration management automation. - -The CBA is **.zip** file, comprised of the following folder structure, the files may vary: - -.. code-block language is required for ReadTheDocs to render code-blocks. Python set as default. - -.. code-block:: python - - ├── Definitions - │ ├── blueprint.json Overall TOSCA service template (workflow + node_template) - │ ├── artifact_types.json (generated by enrichment) - │ ├── data_types.json (generated by enrichment) - │ ├── policy_types.json (generated by enrichment) - │ ├── node_types.json (generated by enrichment) - │ ├── relationship_types.json (generated by enrichment) - │ ├── resources_definition_types.json (generated by enrichment, based on Data Dictionaries) - │ └── *-mapping.json One per Template - │ - ├── Environments Contains *.properties files as required by the service - │ - ├── Plans Contains Directed Graph - │ - ├── Tests Contains uat.yaml file for testing cba actions within a cba package - │ - ├── Scripts Contains scripts - │ ├── python Python scripts - │ └── kotlin Kotlin scripts - │ - ├── TOSCA-Metadata - │ └── TOSCA.meta Meta-data of overall package - │ - └── Templates Contains combination of mapping and template - -To process a CBA for any service we need to enrich it first. This will gather all the node- type, data-type, -artifact-type, data-dictionary definitions provided in the blueprint.json. \ No newline at end of file +.. include:: ../cba/cba-description.rst \ No newline at end of file diff --git a/docs/modelingconcepts/index.rst b/docs/modelingconcepts/index.rst index d8ea3de4b..a7099954c 100644 --- a/docs/modelingconcepts/index.rst +++ b/docs/modelingconcepts/index.rst @@ -27,6 +27,8 @@ Most of the TOSCA modeled entity presented in the bellow documentation can be found `here `_. + + .. toctree:: :caption: Table of Contents :maxdepth: 1 diff --git a/docs/userguide/designtime.rst b/docs/userguide/designtime.rst deleted file mode 100644 index 805cfa89c..000000000 --- a/docs/userguide/designtime.rst +++ /dev/null @@ -1,50 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 -.. Copyright (C) 2019 IBM. - -Design Time Tools Guide -======================= - -Below are the requirements to enable automation for a service within ONAP. - -For instantiation, the goal is to be able to automatically resolve all the HEAT/Helm variables, called cloud parameters. - -For post-instantiation, the goal is to configure the VNF with initial configuration. - -Prerequisite ------------- - -* Gather the cloud parameters: - -Instantiation: -~~~~~~~~~~~~~~ - -Have the HEAT template along with the HEAT environment file (or) Have the Helm chart along with the Values.yaml file - -(CDS supports, but whether SO → Multicloud support for Helm/K8S is different story) - - -Post-instantiation: -~~~~~~~~~~~~~~~~~~~ - -Have the configuration template to apply on the VNF. - -* XML for NETCONF -* JSON / XML for RESTCONF -* not supported yet - CLI -* JSON for Ansible [not supported yet] -* Identify which template parameters are static and dynamic -* Create and fill-in the a table for all the dynamic values - -While doing so, identify the resources using the same process to be resolved; for instance, if two IPs has to be resolved through the same IPAM, the process the resolve the IP is the same. - - -Services: ---------- - -.. toctree:: - :maxdepth: 2 - - ../cba/index - ../resourcedefinition/index - resourceassignment diff --git a/docs/userguide/developer-guide.rst b/docs/userguide/developer-guide.rst deleted file mode 100644 index be73f59c7..000000000 --- a/docs/userguide/developer-guide.rst +++ /dev/null @@ -1,34 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 -.. International License. http://creativecommons.org/licenses/by/4.0 -.. Copyright (C) 2020 Deutsche Telekom AG. - -Developer Guide -================= - -Blueprints Processor Microservice: ----------------------------------- - -Micro service to Manage Controller Blueprint Models, such as Resource Dictionary, Service Models, Velocity Templates etc, which will serve service for Controller Design Studio and Controller runtimes. - -This microservice is used to deploy Controller Blueprint Archive file in Run time database. This also helps to test the Valid CBA. - -.. toctree:: - :maxdepth: 1 - - running-bp-processor-in-ide - -Architecture: -~~~~~~~~~~~~~ - -|image0| - -.. |image0| image:: media/blueprintprocessor.jpg - :width: 400pt - - -Testing in local environment: ------------------------------ - -Point your browser to http://localhost:8000/api/v1/execution-service/ping (please note that the port is 8000, not 8080) - -To authenticate, use ccsdkapps/ccsdkapps login user id and password. \ No newline at end of file diff --git a/docs/userguide/installation.rst b/docs/userguide/installation.rst deleted file mode 100644 index 10997294c..000000000 --- a/docs/userguide/installation.rst +++ /dev/null @@ -1,91 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 -.. Copyright (C) 2019 IBM. - - -Installation Guide -================== - -Installation ------------- - -ONAP is meant to be deployed within a Kubernetes environment. Hence, the de-facto way to deploy CDS is through Kubernetes. - -ONAP also package Kubernetes manifest as Chart, using Helm. - -Prerequisite ------------- - -https://docs.onap.org/en/latest/guides/onap-developer/settingup/index.html - -Setup local Helm ----------------- - -helm repo - -* helm serve & -* helm repo add local http://127.0.0.1:8879 - -Get the chart -------------- - -Make sure to checkout the release to use, by replacing $release-tag in bellow command - -git clone https://gerrit.onap.org/r/oom -git checkout tags/$release-tag -cd oom/kubernetes -make cds - -Install CDS ------------ - -helm install --name cds cds - -Result ------- - -.. code-block:: bash - :linenos: - - $ kubectl get all --selector=release=cds - NAME READY STATUS RESTARTS AGE - pod/cds-blueprints-processor-54f758d69f-p98c2 0/1 Running 1 2m - pod/cds-cds-6bd674dc77-4gtdf 1/1 Running 0 2m - pod/cds-cds-db-0 1/1 Running 0 2m - pod/cds-controller-blueprints-545bbf98cf-zwjfc 1/1 Running 0 2m - - NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE - service/blueprints-processor ClusterIP 10.43.139.9 8080/TCP,9111/TCP 2m - service/cds NodePort 10.43.254.69 3000:30397/TCP 2m - service/cds-db ClusterIP None 3306/TCP 2m - service/controller-blueprints ClusterIP 10.43.207.152 8080/TCP 2m - - NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE - deployment.apps/cds-blueprints-processor 1 1 1 0 2m - deployment.apps/cds-cds 1 1 1 1 2m - deployment.apps/cds-controller-blueprints 1 1 1 1 2m - - NAME DESIRED CURRENT READY AGE - replicaset.apps/cds-blueprints-processor-54f758d69f 1 1 0 2m - replicaset.apps/cds-cds-6bd674dc77 1 1 1 2m - replicaset.apps/cds-controller-blueprints-545bbf98cf 1 1 1 2m - - NAME DESIRED CURRENT AGE - statefulset.apps/cds-cds-db 1 1 2m - - - -Running CDS UI: ---------------- - -Client: -~~~~~~~ -Install Node.js and angularCLI. Refer https://angular.io/guide/quickstart -npm install in the directory cds/cds-ui/client -npm run build - to build UI module - -Loopback Server: -~~~~~~~~~~~~~~~~ - -npm install in the directory cds/cds-ui/server -npm start should bring you the CDS UI page in your local machine with the link https://127.0.0.1:3000/ diff --git a/docs/userguide/media/blueprintprocessor.jpg b/docs/userguide/media/blueprintprocessor.jpg deleted file mode 100644 index 429876a13..000000000 Binary files a/docs/userguide/media/blueprintprocessor.jpg and /dev/null differ diff --git a/docs/userguide/media/build_logs.png b/docs/userguide/media/build_logs.png deleted file mode 100644 index 558fd60a8..000000000 Binary files a/docs/userguide/media/build_logs.png and /dev/null differ diff --git a/docs/userguide/media/create_run_config_java.png b/docs/userguide/media/create_run_config_java.png deleted file mode 100644 index 5d006e2ac..000000000 Binary files a/docs/userguide/media/create_run_config_java.png and /dev/null differ diff --git a/docs/userguide/media/create_run_config_kt.png b/docs/userguide/media/create_run_config_kt.png deleted file mode 100644 index 566ff609c..000000000 Binary files a/docs/userguide/media/create_run_config_kt.png and /dev/null differ diff --git a/docs/userguide/media/expand_vm_options.PNG b/docs/userguide/media/expand_vm_options.PNG deleted file mode 100644 index 9cb98d3f9..000000000 Binary files a/docs/userguide/media/expand_vm_options.PNG and /dev/null differ diff --git a/docs/userguide/media/import_project.png b/docs/userguide/media/import_project.png deleted file mode 100644 index ce7eb3ac5..000000000 Binary files a/docs/userguide/media/import_project.png and /dev/null differ diff --git a/docs/userguide/media/reimport_maven.png b/docs/userguide/media/reimport_maven.png deleted file mode 100644 index bc49b3dc8..000000000 Binary files a/docs/userguide/media/reimport_maven.png and /dev/null differ diff --git a/docs/userguide/media/run-config-set-up.png b/docs/userguide/media/run-config-set-up.png deleted file mode 100644 index 3c2e5fb4f..000000000 Binary files a/docs/userguide/media/run-config-set-up.png and /dev/null differ diff --git a/docs/userguide/media/run_config_java.png b/docs/userguide/media/run_config_java.png deleted file mode 100644 index 4da5d7f34..000000000 Binary files a/docs/userguide/media/run_config_java.png and /dev/null differ diff --git a/docs/userguide/media/run_config_kt.png b/docs/userguide/media/run_config_kt.png deleted file mode 100644 index 4e88d2d0a..000000000 Binary files a/docs/userguide/media/run_config_kt.png and /dev/null differ diff --git a/docs/userguide/media/run_debug.png b/docs/userguide/media/run_debug.png deleted file mode 100644 index 3aa90577f..000000000 Binary files a/docs/userguide/media/run_debug.png and /dev/null differ diff --git a/docs/userguide/media/vsc_logs.png b/docs/userguide/media/vsc_logs.png deleted file mode 100644 index 886d1b3c5..000000000 Binary files a/docs/userguide/media/vsc_logs.png and /dev/null differ diff --git a/docs/userguide/resourceassignment.rst b/docs/userguide/resourceassignment.rst deleted file mode 100644 index aa4f6b559..000000000 --- a/docs/userguide/resourceassignment.rst +++ /dev/null @@ -1,74 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 -.. Copyright (C) 2019 IBM. - -Resource Assignment -=================== -.. toctree:: - :maxdepth: 1 - - -Component executor: -------------------- -Workflow: -~~~~~~~~~ - -A workflow defines an overall action to be taken for the service; it can be composed of a set of sub-actions to execute. Currently, workflows are backed by Directed Graph engine. - -A CBA can have as many workflow as needed. - -Template: -~~~~~~~~~ - -A template is an artifact. - -A template is parameterized and each parameter must be defined in a corresponding mapping file. - -In order to know which mapping correlate to which template, the file name must start with an artifact-prefix, serving as identifier to the overall template + mapping. - -The requirement is as follow: - -${artifact-prefix}-template -${artifact-prefix}-mapping - -A template can represent anything, such as device config, payload to interact with 3rd party systems, resource-accumulator template, etc... - -Mapping: -~~~~~~~~ -Defines the contract of each resource to be resolved. Each placeholder in the template must have a corresponding mapping definition. - -A mapping is comprised of: - -- name -- required / optional -- type (support complex type) -- dictionary-name -- dictionary-source - -Dependencies: -~~~~~~~~~~~~~ - -This allows to make sure given resources get resolved prior the resolution of the resources defining the dependency. -The dictionary fields reference to a specific data dictionary. - - -Resource accumulator: ---------------------- - -In order to resolve HEAT environment variables, resource accumulator templates are being in used for Dublin. - -These templates are specific to the pre-instantiation scenario, and relies on GR-API within SDNC. - -It is composed of the following sections: - -resource-accumulator-resolved-data: defines all the resources that can be resolved directly from the context. It expresses a direct mapping between the name of the resource and its value. - -capability-data: defines what capability to use to create a specific resource, along with the ingredients required to invoke the capability and the output mapping. - -- Scripts -- Library -- NetconfClient - -In order to facilitate NETCONF interaction within scripts, a python NetconfClient binded to our Kotlin implementation is made available. This NetconfClient can be used when using the netconf-component-executor. - -The client can be find here: https://github.com/onap/ccsdk-apps/blob/master/components/scripts/python/ccsdk_netconf/netconfclient.py \ No newline at end of file diff --git a/docs/userguide/running-bp-processor-in-ide.rst b/docs/userguide/running-bp-processor-in-ide.rst deleted file mode 100644 index 3cbcc18b1..000000000 --- a/docs/userguide/running-bp-processor-in-ide.rst +++ /dev/null @@ -1,424 +0,0 @@ -.. This work is a derivative of https://wiki.onap.org/display/DW/Running+Blueprints+Processor+Microservice+in+an+IDE -.. This work is licensed under a Creative Commons Attribution 4.0 -.. International License. http://creativecommons.org/licenses/by/4.0 -.. Copyright (C) 2020 Deutsche Telekom AG. - -Running Blueprints Processor Microservice in an IDE -==================================================== - -Objective -~~~~~~~~~~~~ - -Run the blueprint processor locally in an IDE, while having the database running in a container. -This way, code changes can be conveniently tested and debugged. - -Check out the code -~~~~~~~~~~~~~~~~~~~ - -Check out the code from Gerrit: https://gerrit.onap.org/r/#/admin/projects/ccsdk/cds - -Build it locally -~~~~~~~~~~~~~~~~~~ - -In the checked out directory, type - -.. code-block:: bash - - mvn clean install -Pq -Dadditionalparam=-Xdoclint:none - -Wait for the maven install command to finish until you go further. - -Spin up a Docker container with the database -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The Blueprints Processor project uses a database to store information about the blueprints -and therefore it needs to be online before attempting to run it. - -One way to create the database is by using the :file:`docker-compose.yaml` file. -This database will require a local directory to mount a volume, therefore before running docker-compose create following directory: - -.. code-block:: bash - - mkdir -p -m 755 /opt/app/cds/mysql/data - -Navigate to the docker-compose file in the distribution module: - -.. tabs:: - - .. group-tab:: Frankfurt - Latest - - .. code-block:: bash - - cd ms/blueprintsprocessor/application/src/main/dc - - .. group-tab:: El Alto - Dublin - - .. code-block:: bash - - ms/blueprintsprocessor/distribution/src/main/dc - -And run docker-composer: - -.. code-block:: bash - - docker-compose up -d db - -This should spin up a container of the MariaDB image in the background. -To check if it has worked, this command can be used: - -.. code-block:: bash - - docker-compose logs -f - -The phrase ``mysqld: ready for connections`` indicates that the database was started correctly. - -From now on, the Docker container will be available on the computer; if it ever gets stopped, -it can be started again by the command: - -.. code-block:: bash - - docker start - -Set permissions on the local file system -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Blueprints processor uses the local file system for some operations and, therefore, -need some existing and accessible paths to run properly. - -Execute the following commands to create the needed directories, and grant access to the current user to modify them: - -.. code-block:: bash - - mkdir -p -m 755 /opt/app/onap/blueprints/archive - mkdir -p -m 755 /opt/app/onap/blueprints/deploy - mkdir -p -m 755 /opt/app/onap/scripts - sudo chown -R $(id -u):$(id -g) /opt/app/onap/ - -Import the project into the IDE -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. tabs:: - - .. tab:: IntelliJ IDEA - - .. note:: - This is the recommended IDE for running CDS blueprint processor. - - Go to *File | Open* and choose the :file:`pom.xml` file of the cds/ms/blueprintprocessor directory: - - |imageImportProject| - - Import as a project. Sometimes it may be necessary to reimport Maven project, e.g. if some dependencies can't be found: - - |imageReimportMaven| - - **Override some application properties:** - - Next steps will create a run configuration profile overriding some application properties with custom values, - to reflect the local environment characteristics. - - .. tabs:: - - .. group-tab:: Frankfurt - Latest - - Navigate to the main class of the Blueprints Processor, the BlueprintProcessorApplication class: - - ``ms/blueprintsprocessor/application/src/main/kotlin/org/onap/ccsdk/cds/blueprintsprocessor/BlueprintProcessorApplication.kt``. - - After dependencies are imported and indexes are set up you will see a green arrow - next to main function of BlueprintProcessorApplication class, indicating that the run configuration can now be - created. Right-click inside the class at any point to load the context menu and select create - a run configuration from context: - - |imageCreateRunConfigKt| - - **The following window will open:** - - |imageRunConfigKt| - - **Add the following in the field `VM Options`:** - - .. code-block:: bash - :caption: **Custom values for properties** - - -Dspring.profiles.active=dev - - Optional: You can override any value from **application-dev.properties** file here. In this case use the following pattern: - - .. code-block:: java - - -D= - - .. group-tab:: El Alto - - Navigate to the main class of the Blueprints Processor, the BlueprintProcessorApplication class: - - ``ms/blueprintsprocessor/application/src/main/java/org/onap/ccsdk/cds/blueprintsprocessor/BlueprintProcessorApplication.java.`` - - After dependencies are imported and indexes are set up you will see a green arrow - next to main function of BlueprintProcessorApplication class, indicating that the run configuration can now be - created. Right-click inside the class at any point to load the context menu and select create - a run configuration from context: - - |imageCreateRunConfigJava| - - **The following window will open:** - - |imageRunConfigJava| - - **Add the following in the field `VM Options`:** - - .. code-block:: bash - :caption: **Custom values for properties** - - -Dspring.profiles.active=dev - - Optional: You can override any value from **application-dev.properties** file here. In this case use the following pattern: - - .. code-block:: java - - -D= - - .. group-tab:: Dublin - - Navigate to the main class of the Blueprints Processor, the BlueprintProcessorApplication class: - - ``ms/blueprintsprocessor/application/src/main/java/org/onap/ccsdk/cds/blueprintsprocessor/BlueprintProcessorApplication.java``. - - After dependencies are imported and indexes are set up you will see a green arrow - next to main function of BlueprintProcessorApplication class, indicating that the run configuration can now be - created. Right-click inside the class at any point to load the context menu and select create - a run configuration from context: - - |imageCreateRunConfigJava| - - **The following window will open:** - - |imageRunConfigJava| - - **Add the following in the field `VM Options`** - - .. code-block:: java - :caption: **Custom values for properties** - - -DappName=ControllerBluePrints - -Dms_name=org.onap.ccsdk.apps.controllerblueprints - -DappVersion=1.0.0 - -Dspring.config.location=opt/app/onap/config/ - -Dspring.datasource.url=jdbc:mysql://127.0.0.1:3306/sdnctl - -Dspring.datasource.username=sdnctl - -Dspring.datasource.password=sdnctl - -Dcontrollerblueprints.loadInitialData=true - -Dblueprintsprocessor.restclient.sdncodl.url=http://localhost:8282/ - -Dblueprintsprocessor.db.primary.url=jdbc:mysql://localhost:3306/sdnctl - -Dblueprintsprocessor.db.primary.username=sdnctl - -Dblueprintsprocessor.db.primary.password=sdnctl - -Dblueprintsprocessor.db.primary.driverClassName=org.mariadb.jdbc.Driver - -Dblueprintsprocessor.db.primary.hibernateHbm2ddlAuto=update - -Dblueprintsprocessor.db.primary.hibernateDDLAuto=none - -Dblueprintsprocessor.db.primary.hibernateNamingStrategy=org.hibernate.cfg.ImprovedNamingStrategy - -Dblueprintsprocessor.db.primary.hibernateDialect=org.hibernate.dialect.MySQL5InnoDBDialect - -Dblueprints.processor.functions.python.executor.executionPath=./components/scripts/python/ccsdk_blueprints - -Dblueprints.processor.functions.python.executor.modulePaths=./components/scripts/python/ccsdk_blueprints,./components/scripts/python/ccsdk_netconf,./components/scripts/python/ccsdk_restconf - -Dblueprintsprocessor.restconfEnabled=true - -Dblueprintsprocessor.restclient.sdncodl.type=basic-auth - -Dblueprintsprocessor.restclient.sdncodl.url=http://localhost:8282/ - -Dblueprintsprocessor.restclient.sdncodl.username=admin - -Dblueprintsprocessor.restclient.sdncodl.password=Kp8bJ4SXszM0WXlhak3eHlcse2gAw84vaoGGmJvUy2U - -Dblueprintsprocessor.grpcEnable=false - -Dblueprintsprocessor.grpcPort=9111 - -Dblueprintsprocessor.blueprintDeployPath=/opt/app/onap/blueprints/deploy - -Dblueprintsprocessor.blueprintArchivePath=/opt/app/onap/blueprints/archive - -Dblueprintsprocessor.blueprintWorkingPath=/opt/app/onap/blueprints/work - -Dsecurity.user.password={bcrypt}$2a$10$duaUzVUVW0YPQCSIbGEkQOXwafZGwQ/b32/Ys4R1iwSSawFgz7QNu - -Dsecurity.user.name=ccsdkapps - -Dblueprintsprocessor.messageclient.self-service-api.kafkaEnable=false - -Dblueprintsprocessor.messageclient.self-service-api.topic=producer.t - -Dblueprintsprocessor.messageclient.self-service-api.type=kafka-basic-auth - -Dblueprintsprocessor.messageclient.self-service-api.bootstrapServers=127.0.0.1:9092 - -Dblueprintsprocessor.messageclient.self-service-api.consumerTopic=receiver.t - -Dblueprintsprocessor.messageclient.self-service-api.groupId=receiver-id - -Dblueprintsprocessor.messageclient.self-service-api.clientId=default-client-id - -Dspring.profiles.active=dev - -Dblueprintsprocessor.httpPort=8080 - -Dserver.port=55555 - - - **In the field 'Working Directory' browse to your application path** ``.../cds/ms/blueprintsprocessor/application`` - **if path is not already specified correctly.** - - Run configuration should now look something like this: - - |imageRunConfigSetUp| - - **Add/replace the following in Blueprint's application-dev.properties file.** - - .. code-block:: java - - blueprintsprocessor.grpcclient.remote-python.type=token-auth - blueprintsprocessor.grpcclient.remote-python.host=localhost - blueprintsprocessor.grpcclient.remote-python.port=50051 - blueprintsprocessor.grpcclient.remote-python.token=Basic Y2NzZGthcHBzOmNjc2RrYXBwcw== - - blueprintprocessor.remoteScriptCommand.enabled=true - - Take care that if a parameter already exist you need to change the value of the existing parameter to avoid duplicates. - - - **Run the application:** - - Before running Blueprint Processor check that you use the correct Java version in IntelliJ. - Select either run or debug for the created Run Configuration to start the Blueprints Processor: - - |imageRunDebug| - - |imageBuildLogs| - - .. tab:: Visual Studio Code - - .. tabs:: - - .. group-tab:: Frankfurt - Latest - - * **Step #1** - Make sure your installation of Visual Studio Code is up to date. This guide was writen using version 1.48 - * **Step #2** - Install `Kotlin extension from the Visual Studio Code Marketplace `_ - * **Step #3** - On the top menu click *Run | Open Configurations* - - .. warning:: This should open the file called `launch.json` but in some cases you'll need to wait for the Kotlin Language Server to be installed before you can do anything. - Please watch the bottom bar in Visual Studio Code for messages about things getting installed. - - * **Step #4** - add configuration shown below to your configurations list. - - .. code-block:: json - - { - "type": "kotlin", - "request": "launch", - "name": "Blueprint Processor", - "projectRoot": "${workspaceFolder}/ms/blueprintsprocessor/application", - "mainClass": "-Dspring.profiles.active=dev org.onap.ccsdk.cds.blueprintsprocessor.BlueprintProcessorApplicationKt" - } - - .. warning:: The `projectRoot` path assumes that you created your Workspace in the main CDS repository folder. If not - please change the path accordingly - - .. note:: The `mainClass` contains a spring profile param before the full class name. This is done because `args` is not supported by Kotlin launch.json configuration. - If you have a cleaner idea how to solve this - please let us know. - - **Add/replace the following in Blueprint's application-dev.properties file:** - - .. code-block:: java - - blueprintsprocessor.grpcclient.remote-python.type=token-auth - blueprintsprocessor.grpcclient.remote-python.host=localhost - blueprintsprocessor.grpcclient.remote-python.port=50051 - blueprintsprocessor.grpcclient.remote-python.token=Basic Y2NzZGthcHBzOmNjc2RrYXBwcw== - - blueprintprocessor.remoteScriptCommand.enabled=true - - **Currently the following entries need to be added in VSC too:** - - .. code-block:: java - - logging.level.web=DEBUG - logging.level.org.springframework.web: DEBUG - - #Encrypted username and password for health check service - endpoints.user.name=eHbVUbJAj4AG2522cSbrOQ== - endpoints.user.password=eHbVUbJAj4AG2522cSbrOQ== - - #BaseUrls for health check blueprint processor services - blueprintprocessor.healthcheck.baseUrl=http://localhost:8080/ - blueprintprocessor.healthcheck.mapping-service-name-with-service-link=[Execution service,/api/v1/execution-service/health-check],[Resources service,/api/v1/resources/health-check],[Template service,/api/v1/template/health-check] - - #BaseUrls for health check Cds Listener services - cdslistener.healthcheck.baseUrl=http://cds-sdc-listener:8080/ - cdslistener.healthcheck.mapping-service-name-with-service-link=[SDC Listener service,/api/v1/sdclistener/healthcheck] - - #Actuator properties - management.endpoints.web.exposure.include=* - management.endpoint.health.show-details=always - management.info.git.mode=full - - In VSC the properties are read from target folder, thats why the following maven command needs to be rerun: - - .. code-block:: bash - - mvn clean install -DskipTests=true -Dmaven.test.skip=true -Dmaven.javadoc.skip=true -Dadditionalparam=-Xdoclint:none - - Click Run in Menu bar. - - |imageLogsVSC| - - -Testing the application -~~~~~~~~~~~~~~~~~~~~~~~ - -There are two main features of the Blueprints Processor that can be of interest of a developer: -blueprint publish and blueprint process. - -To upload custom blueprints, the endpoint ``api/v1/execution-service/publish`` is used. - -To process, the endpoint is ``api/v1/execution-service/process``. - -Postman is a software that can be used to send these request, and an example of -them is present on https://www.getpostman.com/collections/b99863b0cde7565a32fc. - -A detailed description of the usage of different APIs of CDS will follow. - - -Possible Fixes -~~~~~~~~~~~~~~ - -Imported packages or annotiations are not found, Run Config not available? -***************************************************************************** - -1. Rebuild with ``maven install ...`` (see above) -2. Potentially change Maven home directory in Settings -3. Maven reimport in IDE - -Compilation error? -******************* -* Change Java Version to 11 - - -.. image alignment inside tabs doesn't work - -.. |imageRunConfigJava| image:: media/run_config_java.png - :width: 500pt - :align: middle - -.. |imageRunConfigKt| image:: media/run_config_kt.png - :width: 500pt - :align: middle - -.. |imageCreateRunConfigJava| image:: media/create_run_config_java.png - :width: 500pt - :align: middle - -.. |imageCreateRunConfigKt| image:: media/create_run_config_kt.png - :width: 500pt - :align: middle - -.. |imageImportProject| image:: media/import_project.png - :width: 300pt - :align: middle - -.. |imageReimportMaven| image:: media/reimport_maven.png - :width: 400pt - :align: middle - -.. |imageRunDebug| image:: media/run_debug.png - :width: 500pt - :align: middle - -.. |imageBuildLogs| image:: media/build_logs.png - :width: 500pt - :align: middle - -.. |imageLogsVSC| image:: media/vsc_logs.png - :width: 500pt - :align: middle - -.. |imageRunConfigSetUp| image:: media/run-config-set-up.png - :width: 500pt - :align: middle diff --git a/docs/userguides/design-time-guide/designtime.rst b/docs/userguides/design-time-guide/designtime.rst new file mode 100644 index 000000000..52b6e55b9 --- /dev/null +++ b/docs/userguides/design-time-guide/designtime.rst @@ -0,0 +1,50 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright (C) 2019 IBM. + +Design Time Tools Guide +======================= + +Below are the requirements to enable automation for a service within ONAP. + +For instantiation, the goal is to be able to automatically resolve all the HEAT/Helm variables, called cloud parameters. + +For post-instantiation, the goal is to configure the VNF with initial configuration. + +Prerequisite +------------ + +* Gather the cloud parameters: + +Instantiation: +~~~~~~~~~~~~~~ + +Have the HEAT template along with the HEAT environment file (or) Have the Helm chart along with the Values.yaml file + +(CDS supports, but whether SO → Multicloud support for Helm/K8S is different story) + + +Post-instantiation: +~~~~~~~~~~~~~~~~~~~ + +Have the configuration template to apply on the VNF. + +* XML for NETCONF +* JSON / XML for RESTCONF +* not supported yet - CLI +* JSON for Ansible [not supported yet] +* Identify which template parameters are static and dynamic +* Create and fill-in the a table for all the dynamic values + +While doing so, identify the resources using the same process to be resolved; for instance, if two IPs has to be resolved through the same IPAM, the process the resolve the IP is the same. + + +Services: +--------- + +.. toctree:: + :maxdepth: 2 + + ../../cba/index + ../../resourcedefinition/index + resourceassignment diff --git a/docs/userguides/design-time-guide/resourceassignment.rst b/docs/userguides/design-time-guide/resourceassignment.rst new file mode 100644 index 000000000..aa4f6b559 --- /dev/null +++ b/docs/userguides/design-time-guide/resourceassignment.rst @@ -0,0 +1,74 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright (C) 2019 IBM. + +Resource Assignment +=================== +.. toctree:: + :maxdepth: 1 + + +Component executor: +------------------- +Workflow: +~~~~~~~~~ + +A workflow defines an overall action to be taken for the service; it can be composed of a set of sub-actions to execute. Currently, workflows are backed by Directed Graph engine. + +A CBA can have as many workflow as needed. + +Template: +~~~~~~~~~ + +A template is an artifact. + +A template is parameterized and each parameter must be defined in a corresponding mapping file. + +In order to know which mapping correlate to which template, the file name must start with an artifact-prefix, serving as identifier to the overall template + mapping. + +The requirement is as follow: + +${artifact-prefix}-template +${artifact-prefix}-mapping + +A template can represent anything, such as device config, payload to interact with 3rd party systems, resource-accumulator template, etc... + +Mapping: +~~~~~~~~ +Defines the contract of each resource to be resolved. Each placeholder in the template must have a corresponding mapping definition. + +A mapping is comprised of: + +- name +- required / optional +- type (support complex type) +- dictionary-name +- dictionary-source + +Dependencies: +~~~~~~~~~~~~~ + +This allows to make sure given resources get resolved prior the resolution of the resources defining the dependency. +The dictionary fields reference to a specific data dictionary. + + +Resource accumulator: +--------------------- + +In order to resolve HEAT environment variables, resource accumulator templates are being in used for Dublin. + +These templates are specific to the pre-instantiation scenario, and relies on GR-API within SDNC. + +It is composed of the following sections: + +resource-accumulator-resolved-data: defines all the resources that can be resolved directly from the context. It expresses a direct mapping between the name of the resource and its value. + +capability-data: defines what capability to use to create a specific resource, along with the ingredients required to invoke the capability and the output mapping. + +- Scripts +- Library +- NetconfClient + +In order to facilitate NETCONF interaction within scripts, a python NetconfClient binded to our Kotlin implementation is made available. This NetconfClient can be used when using the netconf-component-executor. + +The client can be find here: https://github.com/onap/ccsdk-apps/blob/master/components/scripts/python/ccsdk_netconf/netconfclient.py \ No newline at end of file diff --git a/docs/userguides/developer-guide/index.rst b/docs/userguides/developer-guide/index.rst new file mode 100644 index 000000000..129ff7cd6 --- /dev/null +++ b/docs/userguides/developer-guide/index.rst @@ -0,0 +1,35 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 +.. International License. http://creativecommons.org/licenses/by/4.0 +.. Copyright (C) 2020 Deutsche Telekom AG. + +Developer Guide +================= + +Blueprints Processor Microservice +---------------------------------- + +Micro service to Manage Controller Blueprint Models, such as Resource Dictionary, Service Models, Velocity Templates etc, which will serve service for Controller Design Studio and Controller runtimes. + +This microservice is used to deploy Controller Blueprint Archive file in Run time database. This also helps to test the Valid CBA. + +.. toctree:: + :caption: Guide how to run Blueprint Processor in an IDE: + :maxdepth: 1 + + running-bp-processor-in-ide + +Architecture +~~~~~~~~~~~~~ + +|image0| + +.. |image0| image:: media/blueprintprocessor.jpg + :width: 400pt + + +Testing in local environment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Point your browser to http://localhost:8000/api/v1/execution-service/ping (please note that the port is 8000, not 8080) + +To authenticate, use ccsdkapps/ccsdkapps login user id and password. \ No newline at end of file diff --git a/docs/userguides/developer-guide/media/blueprintprocessor.jpg b/docs/userguides/developer-guide/media/blueprintprocessor.jpg new file mode 100644 index 000000000..429876a13 Binary files /dev/null and b/docs/userguides/developer-guide/media/blueprintprocessor.jpg differ diff --git a/docs/userguides/developer-guide/media/build_logs.png b/docs/userguides/developer-guide/media/build_logs.png new file mode 100644 index 000000000..558fd60a8 Binary files /dev/null and b/docs/userguides/developer-guide/media/build_logs.png differ diff --git a/docs/userguides/developer-guide/media/create_run_config_java.png b/docs/userguides/developer-guide/media/create_run_config_java.png new file mode 100644 index 000000000..5d006e2ac Binary files /dev/null and b/docs/userguides/developer-guide/media/create_run_config_java.png differ diff --git a/docs/userguides/developer-guide/media/create_run_config_kt.png b/docs/userguides/developer-guide/media/create_run_config_kt.png new file mode 100644 index 000000000..566ff609c Binary files /dev/null and b/docs/userguides/developer-guide/media/create_run_config_kt.png differ diff --git a/docs/userguides/developer-guide/media/expand_vm_options.PNG b/docs/userguides/developer-guide/media/expand_vm_options.PNG new file mode 100644 index 000000000..9cb98d3f9 Binary files /dev/null and b/docs/userguides/developer-guide/media/expand_vm_options.PNG differ diff --git a/docs/userguides/developer-guide/media/import_project.png b/docs/userguides/developer-guide/media/import_project.png new file mode 100644 index 000000000..ce7eb3ac5 Binary files /dev/null and b/docs/userguides/developer-guide/media/import_project.png differ diff --git a/docs/userguides/developer-guide/media/reimport_maven.png b/docs/userguides/developer-guide/media/reimport_maven.png new file mode 100644 index 000000000..bc49b3dc8 Binary files /dev/null and b/docs/userguides/developer-guide/media/reimport_maven.png differ diff --git a/docs/userguides/developer-guide/media/run_config_java.png b/docs/userguides/developer-guide/media/run_config_java.png new file mode 100644 index 000000000..4da5d7f34 Binary files /dev/null and b/docs/userguides/developer-guide/media/run_config_java.png differ diff --git a/docs/userguides/developer-guide/media/run_config_kt.png b/docs/userguides/developer-guide/media/run_config_kt.png new file mode 100644 index 000000000..4e88d2d0a Binary files /dev/null and b/docs/userguides/developer-guide/media/run_config_kt.png differ diff --git a/docs/userguides/developer-guide/media/run_config_set_up.png b/docs/userguides/developer-guide/media/run_config_set_up.png new file mode 100644 index 000000000..3c2e5fb4f Binary files /dev/null and b/docs/userguides/developer-guide/media/run_config_set_up.png differ diff --git a/docs/userguides/developer-guide/media/run_debug.png b/docs/userguides/developer-guide/media/run_debug.png new file mode 100644 index 000000000..3aa90577f Binary files /dev/null and b/docs/userguides/developer-guide/media/run_debug.png differ diff --git a/docs/userguides/developer-guide/media/vsc_logs.png b/docs/userguides/developer-guide/media/vsc_logs.png new file mode 100644 index 000000000..886d1b3c5 Binary files /dev/null and b/docs/userguides/developer-guide/media/vsc_logs.png differ diff --git a/docs/userguides/developer-guide/running-bp-processor-in-ide.rst b/docs/userguides/developer-guide/running-bp-processor-in-ide.rst new file mode 100644 index 000000000..ab6ae2314 --- /dev/null +++ b/docs/userguides/developer-guide/running-bp-processor-in-ide.rst @@ -0,0 +1,428 @@ +.. This work is a derivative of https://wiki.onap.org/display/DW/Running+Blueprints+Processor+Microservice+in+an+IDE +.. This work is licensed under a Creative Commons Attribution 4.0 +.. International License. http://creativecommons.org/licenses/by/4.0 +.. Copyright (C) 2020 Deutsche Telekom AG. + +Running Blueprints Processor Microservice in an IDE +==================================================== + +Objective +~~~~~~~~~~~~ + +Run the blueprint processor locally in an IDE, while having the database running in a container. +This way, code changes can be conveniently tested and debugged. + +Check out the code +~~~~~~~~~~~~~~~~~~~ + +Check out the code from Gerrit: https://gerrit.onap.org/r/#/admin/projects/ccsdk/cds + +Build it locally +~~~~~~~~~~~~~~~~~~ + +In the checked out directory, type + +.. code-block:: bash + + mvn clean install -Pq -Dadditionalparam=-Xdoclint:none + +.. note:: + If an error ``invalid flag: --release`` appears when executing the maven install command, you need to upgrade Java version of your local + Maven installation. Use something like ``export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64``. + +Wait for the maven install command to finish until you go further. + +Spin up a Docker container with the database +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Blueprints Processor project uses a database to store information about the blueprints +and therefore it needs to be online before attempting to run it. + +One way to create the database is by using the :file:`docker-compose.yaml` file. +This database will require a local directory to mount a volume, therefore before running docker-compose create following directory: + +.. code-block:: bash + + mkdir -p -m 755 /opt/app/cds/mysql/data + +Navigate to the docker-compose file in the distribution module: + +.. tabs:: + + .. group-tab:: Frankfurt - Latest + + .. code-block:: bash + + cd ms/blueprintsprocessor/application/src/main/dc + + .. group-tab:: El Alto - Dublin + + .. code-block:: bash + + ms/blueprintsprocessor/distribution/src/main/dc + +And run docker-composer: + +.. code-block:: bash + + docker-compose up -d db + +This should spin up a container of the MariaDB image in the background. +To check if it has worked, this command can be used: + +.. code-block:: bash + + docker-compose logs -f + +The phrase ``mysqld: ready for connections`` indicates that the database was started correctly. + +From now on, the Docker container will be available on the computer; if it ever gets stopped, +it can be started again by the command: + +.. code-block:: bash + + docker start + +Set permissions on the local file system +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Blueprints processor uses the local file system for some operations and, therefore, +need some existing and accessible paths to run properly. + +Execute the following commands to create the needed directories, and grant access to the current user to modify them: + +.. code-block:: bash + + mkdir -p -m 755 /opt/app/onap/blueprints/archive + mkdir -p -m 755 /opt/app/onap/blueprints/deploy + mkdir -p -m 755 /opt/app/onap/scripts + sudo chown -R $(id -u):$(id -g) /opt/app/onap/ + +Import the project into the IDE +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. tabs:: + + .. tab:: IntelliJ IDEA + + .. note:: + This is the recommended IDE for running CDS blueprint processor. + + Go to *File | Open* and choose the :file:`pom.xml` file of the cds/ms/blueprintprocessor directory: + + |imageImportProject| + + Import as a project. Sometimes it may be necessary to reimport Maven project, e.g. if some dependencies can't be found: + + |imageReimportMaven| + + **Override some application properties:** + + Next steps will create a run configuration profile overriding some application properties with custom values, + to reflect the local environment characteristics. + + .. tabs:: + + .. group-tab:: Frankfurt - Latest + + Navigate to the main class of the Blueprints Processor, the BlueprintProcessorApplication class: + + ``ms/blueprintsprocessor/application/src/main/kotlin/org/onap/ccsdk/cds/blueprintsprocessor/BlueprintProcessorApplication.kt``. + + After dependencies are imported and indexes are set up you will see a green arrow + next to main function of BlueprintProcessorApplication class, indicating that the run configuration can now be + created. Right-click inside the class at any point to load the context menu and select create + a run configuration from context: + + |imageCreateRunConfigKt| + + **The following window will open:** + + |imageRunConfigKt| + + **Add the following in the field `VM Options`:** + + .. code-block:: bash + :caption: **Custom values for properties** + + -Dspring.profiles.active=dev + + Optional: You can override any value from **application-dev.properties** file here. In this case use the following pattern: + + .. code-block:: java + + -D= + + .. group-tab:: El Alto + + Navigate to the main class of the Blueprints Processor, the BlueprintProcessorApplication class: + + ``ms/blueprintsprocessor/application/src/main/java/org/onap/ccsdk/cds/blueprintsprocessor/BlueprintProcessorApplication.java.`` + + After dependencies are imported and indexes are set up you will see a green arrow + next to main function of BlueprintProcessorApplication class, indicating that the run configuration can now be + created. Right-click inside the class at any point to load the context menu and select create + a run configuration from context: + + |imageCreateRunConfigJava| + + **The following window will open:** + + |imageRunConfigJava| + + **Add the following in the field `VM Options`:** + + .. code-block:: bash + :caption: **Custom values for properties** + + -Dspring.profiles.active=dev + + Optional: You can override any value from **application-dev.properties** file here. In this case use the following pattern: + + .. code-block:: java + + -D= + + .. group-tab:: Dublin + + Navigate to the main class of the Blueprints Processor, the BlueprintProcessorApplication class: + + ``ms/blueprintsprocessor/application/src/main/java/org/onap/ccsdk/cds/blueprintsprocessor/BlueprintProcessorApplication.java``. + + After dependencies are imported and indexes are set up you will see a green arrow + next to main function of BlueprintProcessorApplication class, indicating that the run configuration can now be + created. Right-click inside the class at any point to load the context menu and select create + a run configuration from context: + + |imageCreateRunConfigJava| + + **The following window will open:** + + |imageRunConfigJava| + + **Add the following in the field `VM Options`** + + .. code-block:: java + :caption: **Custom values for properties** + + -DappName=ControllerBluePrints + -Dms_name=org.onap.ccsdk.apps.controllerblueprints + -DappVersion=1.0.0 + -Dspring.config.location=opt/app/onap/config/ + -Dspring.datasource.url=jdbc:mysql://127.0.0.1:3306/sdnctl + -Dspring.datasource.username=sdnctl + -Dspring.datasource.password=sdnctl + -Dcontrollerblueprints.loadInitialData=true + -Dblueprintsprocessor.restclient.sdncodl.url=http://localhost:8282/ + -Dblueprintsprocessor.db.primary.url=jdbc:mysql://localhost:3306/sdnctl + -Dblueprintsprocessor.db.primary.username=sdnctl + -Dblueprintsprocessor.db.primary.password=sdnctl + -Dblueprintsprocessor.db.primary.driverClassName=org.mariadb.jdbc.Driver + -Dblueprintsprocessor.db.primary.hibernateHbm2ddlAuto=update + -Dblueprintsprocessor.db.primary.hibernateDDLAuto=none + -Dblueprintsprocessor.db.primary.hibernateNamingStrategy=org.hibernate.cfg.ImprovedNamingStrategy + -Dblueprintsprocessor.db.primary.hibernateDialect=org.hibernate.dialect.MySQL5InnoDBDialect + -Dblueprints.processor.functions.python.executor.executionPath=./components/scripts/python/ccsdk_blueprints + -Dblueprints.processor.functions.python.executor.modulePaths=./components/scripts/python/ccsdk_blueprints,./components/scripts/python/ccsdk_netconf,./components/scripts/python/ccsdk_restconf + -Dblueprintsprocessor.restconfEnabled=true + -Dblueprintsprocessor.restclient.sdncodl.type=basic-auth + -Dblueprintsprocessor.restclient.sdncodl.url=http://localhost:8282/ + -Dblueprintsprocessor.restclient.sdncodl.username=admin + -Dblueprintsprocessor.restclient.sdncodl.password=Kp8bJ4SXszM0WXlhak3eHlcse2gAw84vaoGGmJvUy2U + -Dblueprintsprocessor.grpcEnable=false + -Dblueprintsprocessor.grpcPort=9111 + -Dblueprintsprocessor.blueprintDeployPath=/opt/app/onap/blueprints/deploy + -Dblueprintsprocessor.blueprintArchivePath=/opt/app/onap/blueprints/archive + -Dblueprintsprocessor.blueprintWorkingPath=/opt/app/onap/blueprints/work + -Dsecurity.user.password={bcrypt}$2a$10$duaUzVUVW0YPQCSIbGEkQOXwafZGwQ/b32/Ys4R1iwSSawFgz7QNu + -Dsecurity.user.name=ccsdkapps + -Dblueprintsprocessor.messageclient.self-service-api.kafkaEnable=false + -Dblueprintsprocessor.messageclient.self-service-api.topic=producer.t + -Dblueprintsprocessor.messageclient.self-service-api.type=kafka-basic-auth + -Dblueprintsprocessor.messageclient.self-service-api.bootstrapServers=127.0.0.1:9092 + -Dblueprintsprocessor.messageclient.self-service-api.consumerTopic=receiver.t + -Dblueprintsprocessor.messageclient.self-service-api.groupId=receiver-id + -Dblueprintsprocessor.messageclient.self-service-api.clientId=default-client-id + -Dspring.profiles.active=dev + -Dblueprintsprocessor.httpPort=8080 + -Dserver.port=55555 + + + **In the field 'Working Directory' browse to your application path** ``.../cds/ms/blueprintsprocessor/application`` + **if path is not already specified correctly.** + + Run configuration should now look something like this: + + |imageRunConfigSetUp| + + **Add/replace the following in Blueprint's application-dev.properties file.** + + .. code-block:: java + + blueprintsprocessor.grpcclient.remote-python.type=token-auth + blueprintsprocessor.grpcclient.remote-python.host=localhost + blueprintsprocessor.grpcclient.remote-python.port=50051 + blueprintsprocessor.grpcclient.remote-python.token=Basic Y2NzZGthcHBzOmNjc2RrYXBwcw== + + blueprintprocessor.remoteScriptCommand.enabled=true + + Take care that if a parameter already exist you need to change the value of the existing parameter to avoid duplicates. + + + **Run the application:** + + Before running Blueprint Processor check that you use the correct Java version in IntelliJ. + Select either run or debug for the created Run Configuration to start the Blueprints Processor: + + |imageRunDebug| + + |imageBuildLogs| + + .. tab:: Visual Studio Code + + .. tabs:: + + .. group-tab:: Frankfurt - Latest + + * **Step #1** - Make sure your installation of Visual Studio Code is up to date. This guide was writen using version 1.48 + * **Step #2** - Install `Kotlin extension from the Visual Studio Code Marketplace `_ + * **Step #3** - On the top menu click *Run | Open Configurations* + + .. warning:: This should open the file called `launch.json` but in some cases you'll need to wait for the Kotlin Language Server to be installed before you can do anything. + Please watch the bottom bar in Visual Studio Code for messages about things getting installed. + + * **Step #4** - add configuration shown below to your configurations list. + + .. code-block:: json + + { + "type": "kotlin", + "request": "launch", + "name": "Blueprint Processor", + "projectRoot": "${workspaceFolder}/ms/blueprintsprocessor/application", + "mainClass": "-Dspring.profiles.active=dev org.onap.ccsdk.cds.blueprintsprocessor.BlueprintProcessorApplicationKt" + } + + .. warning:: The `projectRoot` path assumes that you created your Workspace in the main CDS repository folder. If not - please change the path accordingly + + .. note:: The `mainClass` contains a spring profile param before the full class name. This is done because `args` is not supported by Kotlin launch.json configuration. + If you have a cleaner idea how to solve this - please let us know. + + **Add/replace the following in Blueprint's application-dev.properties file:** + + .. code-block:: java + + blueprintsprocessor.grpcclient.remote-python.type=token-auth + blueprintsprocessor.grpcclient.remote-python.host=localhost + blueprintsprocessor.grpcclient.remote-python.port=50051 + blueprintsprocessor.grpcclient.remote-python.token=Basic Y2NzZGthcHBzOmNjc2RrYXBwcw== + + blueprintprocessor.remoteScriptCommand.enabled=true + + **Currently the following entries need to be added in VSC too:** + + .. code-block:: java + + logging.level.web=DEBUG + logging.level.org.springframework.web: DEBUG + + #Encrypted username and password for health check service + endpoints.user.name=eHbVUbJAj4AG2522cSbrOQ== + endpoints.user.password=eHbVUbJAj4AG2522cSbrOQ== + + #BaseUrls for health check blueprint processor services + blueprintprocessor.healthcheck.baseUrl=http://localhost:8080/ + blueprintprocessor.healthcheck.mapping-service-name-with-service-link=[Execution service,/api/v1/execution-service/health-check],[Resources service,/api/v1/resources/health-check],[Template service,/api/v1/template/health-check] + + #BaseUrls for health check Cds Listener services + cdslistener.healthcheck.baseUrl=http://cds-sdc-listener:8080/ + cdslistener.healthcheck.mapping-service-name-with-service-link=[SDC Listener service,/api/v1/sdclistener/healthcheck] + + #Actuator properties + management.endpoints.web.exposure.include=* + management.endpoint.health.show-details=always + management.info.git.mode=full + + In VSC the properties are read from target folder, thats why the following maven command needs to be rerun: + + .. code-block:: bash + + mvn clean install -DskipTests=true -Dmaven.test.skip=true -Dmaven.javadoc.skip=true -Dadditionalparam=-Xdoclint:none + + Click Run in Menu bar. + + |imageLogsVSC| + + +Testing the application +~~~~~~~~~~~~~~~~~~~~~~~ + +There are two main features of the Blueprints Processor that can be of interest of a developer: +blueprint publish and blueprint process. + +To upload custom blueprints, the endpoint ``api/v1/execution-service/publish`` is used. + +To process, the endpoint is ``api/v1/execution-service/process``. + +Postman is a software that can be used to send these request, and an example of +them is present on https://www.getpostman.com/collections/b99863b0cde7565a32fc. + +A detailed description of the usage of different APIs of CDS will follow. + + +Possible Fixes +~~~~~~~~~~~~~~ + +Imported packages or annotiations are not found, Run Config not available? +***************************************************************************** + +1. Rebuild with ``maven install ...`` (see above) +2. Potentially change Maven home directory in Settings +3. Maven reimport in IDE + +Compilation error? +******************* +* Change Java Version to 11 + + +.. image alignment inside tabs doesn't work + +.. |imageRunConfigJava| image:: media/run_config_java.png + :width: 500pt + :align: middle + +.. |imageRunConfigKt| image:: media/run_config_kt.png + :width: 500pt + :align: middle + +.. |imageCreateRunConfigJava| image:: media/create_run_config_java.png + :width: 500pt + :align: middle + +.. |imageCreateRunConfigKt| image:: media/create_run_config_kt.png + :width: 500pt + :align: middle + +.. |imageImportProject| image:: media/import_project.png + :width: 300pt + :align: middle + +.. |imageReimportMaven| image:: media/reimport_maven.png + :width: 400pt + :align: middle + +.. |imageRunDebug| image:: media/run_debug.png + :width: 500pt + :align: middle + +.. |imageBuildLogs| image:: media/build_logs.png + :width: 500pt + :align: middle + +.. |imageLogsVSC| image:: media/vsc_logs.png + :width: 500pt + :align: middle + +.. |imageRunConfigSetUp| image:: media/run_config_set_up.png + :width: 500pt + :align: middle diff --git a/docs/userguides/installation.rst b/docs/userguides/installation.rst new file mode 100644 index 000000000..10997294c --- /dev/null +++ b/docs/userguides/installation.rst @@ -0,0 +1,91 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright (C) 2019 IBM. + + +Installation Guide +================== + +Installation +------------ + +ONAP is meant to be deployed within a Kubernetes environment. Hence, the de-facto way to deploy CDS is through Kubernetes. + +ONAP also package Kubernetes manifest as Chart, using Helm. + +Prerequisite +------------ + +https://docs.onap.org/en/latest/guides/onap-developer/settingup/index.html + +Setup local Helm +---------------- + +helm repo + +* helm serve & +* helm repo add local http://127.0.0.1:8879 + +Get the chart +------------- + +Make sure to checkout the release to use, by replacing $release-tag in bellow command + +git clone https://gerrit.onap.org/r/oom +git checkout tags/$release-tag +cd oom/kubernetes +make cds + +Install CDS +----------- + +helm install --name cds cds + +Result +------ + +.. code-block:: bash + :linenos: + + $ kubectl get all --selector=release=cds + NAME READY STATUS RESTARTS AGE + pod/cds-blueprints-processor-54f758d69f-p98c2 0/1 Running 1 2m + pod/cds-cds-6bd674dc77-4gtdf 1/1 Running 0 2m + pod/cds-cds-db-0 1/1 Running 0 2m + pod/cds-controller-blueprints-545bbf98cf-zwjfc 1/1 Running 0 2m + + NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE + service/blueprints-processor ClusterIP 10.43.139.9 8080/TCP,9111/TCP 2m + service/cds NodePort 10.43.254.69 3000:30397/TCP 2m + service/cds-db ClusterIP None 3306/TCP 2m + service/controller-blueprints ClusterIP 10.43.207.152 8080/TCP 2m + + NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE + deployment.apps/cds-blueprints-processor 1 1 1 0 2m + deployment.apps/cds-cds 1 1 1 1 2m + deployment.apps/cds-controller-blueprints 1 1 1 1 2m + + NAME DESIRED CURRENT READY AGE + replicaset.apps/cds-blueprints-processor-54f758d69f 1 1 0 2m + replicaset.apps/cds-cds-6bd674dc77 1 1 1 2m + replicaset.apps/cds-controller-blueprints-545bbf98cf 1 1 1 2m + + NAME DESIRED CURRENT AGE + statefulset.apps/cds-cds-db 1 1 2m + + + +Running CDS UI: +--------------- + +Client: +~~~~~~~ +Install Node.js and angularCLI. Refer https://angular.io/guide/quickstart +npm install in the directory cds/cds-ui/client +npm run build - to build UI module + +Loopback Server: +~~~~~~~~~~~~~~~~ + +npm install in the directory cds/cds-ui/server +npm start should bring you the CDS UI page in your local machine with the link https://127.0.0.1:3000/ -- cgit 1.2.3-korg