Page for general findings around the investigation of the optimal path for CLAMP and Tosca Control Loop Integration.

CLAMP Code Walkthrough videos can be found here

Tosca handling in CLAMP vs Tosca Control Loop - Findings

CLAMP

• CLAMP uses models defined within the repository for definition of various object types like: Loop and LoopElement.

• Javax persistence is used to define the entities that map to tables in the DB.

• Repository pattern is used for database access with JPARepository.

• GSON is used in some cases for serialization/deserialization.

CSAR from SDC Flow

1. CSAR contains the DCAE blueprint to be used to deploy to DCAE but also contains a reference to a microservice policy type. CLAMP, on startup, pulls all the policy types and pulls them periodically after that (+pulls the PDP group/subgroup accepted deployment per model). Clamp creates LOOP TEMPLATES from in its database from the blueprints. CLAMP uses the reference from the CSAR to associate the relevant microservice policy type with a loop template. Thus, CLAMP knows which monitoring policy type to use for creation of a Loop instance.

2. When deploying the SDC notif + CSAR, clamp does a get query to dcae to get the blueprint ID in the inventory. If it fails CLAMP rollbacks the transactions and aborts the SDC notification installation.

3. During the installation, CLAMP also installs in its DB service information, like UUID VNF associated ... this is used later by the UI to help the user to easily configure the different policies. It supports multiple blueprints per VNF (defined in SDC). The VNFs are retrieved by CLAMP from the SDC notification.

4. Although there is a comment in "src/main/java/org/onap/policy/clamp/loop/deploy/DcaeDeployParameters.java" saying multiple microservices are not currently possible, +-90% () of clamp code "should" support the multi-mircoservices per blueprint. Code was initially written by Nokia to extract multiple microservices from the blueprint BUT Dcae did not and still does not support that. Normally the multi-microservices "should" come from the new DCAE architecture. (edited - hope that's ok)

5. The Blueprint Artifact in the CSAR is used to populate the "loop_template" db. These "loop_templates" are used to create instances. All interaction with the database is done using the SpringBoot "@Repository" pattern. Standard boilerplate db interaction is done in most cases with "JpaRepository" (find, save etc).

6. However, it should be noted that, databases and tables are not automatically created by Spring. SQL scripts are used in CLAMP to do this. A script "start-db.sh" runs the mariadb docker container. Part of the functionality of the MariaDB image from DockerHub is that any scripts with extensions:  .sh, .sql, .sql.gz, and .sql.xz that are found in /docker-entrypoint-initdb.d are executed on startup... So, CLAMP has several scripts for creation of databases, users, tables and test data. The "create-tables.sql" script is generated at build-time by the "hibernate52-ddl-maven-plugin" in the pom.xml.

7. CLAMP also gets the policy type (based on the policy type id in the Blueprint) from the database. The types are then added to the "loop_element_models" table. The relationship between "loop_element_models" and "policy_models" is recorded in the "loopelementmodels_to_policymodels" table.

8. The relationship between the loop element models and the loop templates is also recorded in the "looptemplates_to_loopelementmodels" table. In this way, the blueprint templates is associated with a microservice policy.

Loop Creation Flow

When a loop is created in UI or directly in backend:

1. The loop is saved in the "loops" table.

2. The microservice policy is created (with a generated name) in the "micro_service_policies" table along with the policy type associated with it and the json representation of the policy type.

3. The relationship between the microservice policies and the loops is recorded in the "loops_to_microservicepolicies" table. This contains the loop names and the microservice policy names.

Update Loop Flow

It is possible to update a loop that has been created. This allows configuration of the policies attached to the microservice.

1. Updating a microservice policy or an operational policy can be done in the the UI or by accessing the CLAMP backend directly.

2. For the microservice policy, you can:

   1. Click on the SVG and a convenience JSON editor will popup and allow properties to be added and removed from the JSON policy configuration template.

   2. Send the JSON configuration of the policy directly to the CLAMP backend endpoint at "/updateMicroservicePolicy".

3. In both cases, this populates the "configurations_json" field for the microservice in the "micro_service_policies" table.

4. Serialization and Deserialization of the JSON going into the database is handled by MicroServicePolicies.java, which extends Policy.java.

Policy Deployment Flow

Deployment of the policy from the loop can be triggered by:

1. Using the SUBMIT option in the frontend.

2. Using the backend submit endpoint.

No body has to be provided to the endpoint. The payload for the policy endpoint is generated internally in CLAMP from data already present in the database. Among other things, a call to the CAMEL submit endpoint retrieves the relevant microservice policies from the "micro_service_policies" table in the database. This is passed to another flow responsible for creating the policy in the policy engine. The policy payload is generated with all of the relevant tosca parameters in "src/main/java/org/onap/policy/clamp/policy/PolicyPayload.java". Another flow calls the endpoint on the policy engine and sends the payload in the correct format.

Tosca Control Loop

Firstly, Tosca Control Loop (TCL) is a different idiom. To deploy policies and services, we commission and instantiate control loops in TCL. The state of these control loops is managed by the runtime, which distributes messages to the participants. The participants are then responsible for actually carrying out the actions on the relevant components - based on the instructions received from the runtime.

Throughout the Tosca Control Loop code and policy models:

1. GSON is used for serialization/deserialization.

2. JPA persistence is used for database interaction.

3. Lombok is used to create boilerplate POJO code.

4. DAO pattern is used for database access.

5. Models unique to Tosca Control Loop are within the repository, others are in policy models.

Commissioning Tosca Handling

1. In the Runtime, once the commissioning API receives a new Tosca template at the "/commission" endpoint, a call is made to the DatabasePolicyModelsProviderImpl in the "models" repo to deserialize the TOSCA and save it to the "controlloop" database.

2. The database credentials and persistence units specified in the runtime configuration file are used for DB access.

3. The TOSCA is written to the relevant table "ToscaServiceTemplate" and also to related tables. -Note that this table (along with many others) is created in the DB at startup as specified in the persistence.xml.

4. In addition to being able to add a new service template via the "/commission" endpoint, it is also possible to add a "fragment" of a template to an existing one through the same endpoint. An example of a tosca file to be sent to commissioning is below.

5. The Tosca defines types that will be used during the instantiation of the control loops.

example tosca service template

Control Loop Instantiation

1. The "/instantiation" endpoint is responsible for creating the control loops. It doesn't start the loops but does create them, based on the types that are defined in the Tosca Service Template.

2. Once the control loops from the control loop list are validated, they are written to the "ControlLoop" table in the "controlloop" database. The control loop elements are also written to the "controlloopelement" table.

3. Control Loops can be made "PASSIVE" (or ordered to move to some other state) by making a PUT call to the "instantiation/command" endpoint.

4. Supervision sends the command to DMAAP, for the participants to consume.

5. The participants send a message back through DMAAP with their IDs and other details. Supervision listens for these messages and registers the participants in the database.

6. Regular status messages are sent by the participants to tell the runtime report the state of the policy or microservice. These statuses are updated in the control loop database.

Participant Tosca Handling

1. Each Participant uses a Participant-Intermediary to listen for creation and update messages from the Runtime. These can be updates to the state of the participant or the state of control loops and control loop elements.

2. If an update to a control loop is received, the participant parses the required elements from the Tosca Template using the models present in the policy/models repo and writes the relevant parts to the correct database.

   1. In the case of the Policy-Participant, the "controlLoopElementUpdate" of "ControlLoopElementHandler.java" is used to write policies and policy types to the Policy API database.

   2. Similarly, in the DCAE-Participant, the "controlLoopElementUpdate" of "ControlLoopElementHandler.java", carries out (in the current iteration from POC demo) "deploy" and "undeploy" actions in CLAMP for the microservice instance. CLAMP, in turn, writes the new data to the CLAMP database.

Tosca Handling Observations, Difficulties and Recommendations

1. CLAMP is built around the fact that it would be receiving its blueprints and policy type information from SDC , in the form of a CSAR. Received components are then parsed and written to the database. This procedure could be aligned with Tosca Control Loop in the following ways:

   1. Alter the CSAR installer to construct the Tosca in a similar way to how the Tosca Control Loop does - so that it can be saved to the ControlLoop database.

   2. Having this installer as a separate, but accessible library might be better than just leaving it in CLAMP. In this way, other modules can access it.

   3. For example, the Runtime could access it and add the resultant Tosca to the Control Loop database. Instructions could then be distributed to the participants.

   4. If the DCAE participant is still using CLAMP, then the Runtime could pass the Blueprint from the CSAR to it - CLAMP could then deploy to DCAE.

   5. Alternatively, the DCAE participant could deploy directly to DCAE - but must have some method to adjust the configuration of the blueprint being deployed. At the moment, the CLAMP GUI provides that functionality but perhaps, in the future, Bruno's adjusted GUI could do the same.

2. At the moment, the CLAMP UI is capable of making changes to loops' configuration with an JSON schema-based editor. CAMEL endpoints are then called to persist the changes in the DB. The service, if already deployed, must then be redeployed (Also provided by the GUI). Similar behaviour should be available in Tosca Control Loop. A commissioned Control Loop should be capable of being altered and updated using REST endpoints. If we want to use the UI to make the update in Tosca Control Loop, we would need to consider the following:

   1. The UI would have to have some convenient mechanism for altering the template. As templates can be very large, this could become unwieldy very quickly and not a pleasant experience for the user.

   2. A form-based JSON editor would be nice: https://jsonforms.io/

   3. Again, we should consider whether we will use the CLAMP BE for this. If we do, should we consider having a CLAMP participant. Runtime should be aware of all of the changes made to control loops. If we do not, the UI can make changes by calling the Runtime endpoints.

   4. This goes for policy editing as well as microservice configuration editing.

3. From the database point of view, CLAMP uses Spring's "@Repository" pattern - where as Toscal Control Loop uses the "DAO" pattern - as does the policy framework. It does not make sense to use both of these.

   1. It makes more sense to use the one pattern and it is possible to use the DAO pattern in SpringBoot https://www.baeldung.com/java-dao-pattern

4. As is now, Control Loops are represented in a different way in CLAMP and Tosca Control Loop. They use different databases and the database schemas are in no way similar

   1. The architecture of Tosca Control Loop should be the all changes, updates and alterations to control loops are made through the Runtime endpoints. CLAMP does not "fit" in this context - its backend acts an overall manager of the control loops and tosca templates. CLAMP and the Runtime would effectively be 2 managers - where only one is needed.

   2. Possible solutions:

      1. The CLAMP backend could be altered to access the Runtime endpoints - this would require extensive restructuring of response handling.

      2. Tosca Control Loop could be altered to use the CLAMP database/model structure. This would require rewriting and rearchitecting of Runtime, Participants and all other components.

5. DCAE participant's current use of CLAMP

   1. At the moment and in the POC, the DCAE Participant accesses DCAE through CLAMP - taking template and control loop data from the Runtime, altering it and then passing it on to CLAMP endpoints. The Policy Participant accesses the Policy Framework. DCAE participant, arguably, should do the same.

   2. CLAMP has facillity to create and alter both miscroservices and policies. Should the Policy participant then interact with the Policy Framework through CLAMP?

   3. Possible solutions:

      1. Have DCAE Participant interact with DCAE directly.

      2. Continue to use CLAMP for this purpose - see also number 4 above for difficulties associated with this.

REST in CLAMP vs REST in Control Loop PoC

Findings 

1. LoopService and MicroservicePolicyService classes resemble our PoC Provider classes, such as Commissioning and Instantiation Provider where java code in regards to CRUD resides

   1.  Examples:

      LoopService.getLoop()

      public Loop getLoop(String loopName) { return loopsRepository.findById(loopName).orElse(null); }

      
      
      

      ControlLoopInstantiationProvider.GetControlLoops()

      public ControlLoops getControlLoops(String name, String version) throws PfModelException { ControlLoops controlLoops = new ControlLoops(); controlLoops.setControlLoopList(controlLoopProvider.getControlLoops(name, version)); return controlLoops; }

      
      
      

   2.  The differences start here, as CLAMP uses the Spring Framework Repository Interfaces to handle database calls, where as PoC is using the code defined in policy-models in regards to Tosca and our own models and JPA classes for ControlLoop related objects. 
      i.e LoopsRepository extends JpaRepository (Spring Framework). Our providers are either created by us or use policy ones i.e. PolicyModelsProvider.

   3.  There seems to be a lot of specific methods for updating the loop templates, such as updateDcaeDeploymentFields() and addOperationalPolicy(). In our case that is handled within the TOSCA service template itself, by mending the template where these objects can be added as nodeTemplates(ControlLoopElements), without having to be specific to a DCAE control loop. Further info in TOSCA handling.
      
      
      

2.  Actual REST code is handled rather differently. In CLAMP LoopController class serves as a class to introduce Springboot Framework with the "@Controller" annotation, and methods defined in this class are just calling the LoopService Methods. This is to allow these methods to be more easily called by the CAMEL flows using :
   e.g. "<to uri="bean:org.onap.policy.clamp.loop.LoopController?method=getLoop(${header.loopName})"/". In CAMEL the response, logging and error handling occurs, with the code just throwing the exception.
   In our case, our REST code along with annotations, definitions and responses is in our Controllers, which call the provider methods to do the actual interaction. e.g. CommissioningController, which defines the path along with other java.wx.rs inputs.

   1. Examples:

      LoopController.getLoop()

      
      
      

      CAMEL for getLoop

      
      
      

      Java Code for PoC way of handling REST

      
      
      

   2. My knowledge on Spring is limited. Overall it seems more of a preference. Switching PoC way to handle REST to Spring/CAMEL as is in CLAMP should not be a massive hurdle, unless if Spring can only handle database queries which are defined by Spring Interfaces, and we cannot create "@Controller" for our provider(Service) code which uses our own JPA code for interacting with the DB

   3. I also want to mention that Spring/Camel is handling the DB transactions for US. Each time an endpoint is hit, the transaction is automatically opened, you can therefore (with specific annotations) abort, open new transac within the first one, control the transac if needed ....etc ... When no exception is raised the commit is done when the call ends. I see SpringBoot as an enterprise java Container that comes with JPA/JTA/Beans/Rest +..... functionalities out of the box (like JBOSS).
      
      

Potential Difficulties/Issues to be discussed

1. While it is possible to convert Tosca PoC code into spring, it uses Policy Models Code to interact with Tosca Service Templates. This causes several difficulties:

   1. To be properly used, that code base would need to be converted into spring as well, which would either:

      1. Have to duplicate work done in policy models to have a spring style code in our code base and policy style code in models to be used by other policy components.

      2. Adjust the code in policy models to be spring style, which would then cause other code changes to different policy components, possibly creating havoc : 

         1. Involves a lot of policy components, would need to be a project overhaul (Major decision)

         2. Would it really make sense on the policy project level, as code base now is rather small and works well (Tried and tested)

   2. If we only change our PoC code to Spring, it does not make much sense, as:

      1. We can not use Spring Transaction handling with some of the code base being done policy style (One of the main advantages of using Spring)

      2. We need to create a separate DB connection, meaning we would have two (Doesn't seem like a great way forward, but it would work)

   3. The code which does not use any policy models code, and is standalone can work, for example participant code. They run by themselves, with the code defined within the participant.

   4. I am not sure of Camel use for REST. While it does not seem to be majorly complicated, most of that code can we written in Java, in addition, using Spring Annotations. Looking in future general use, most of the "routes" such as dcae/policy will be handled by participants themselves, thus there will be no rest code in the main backend code for that, meaning there is even less incentive to use Camel for REST in the long run. 
      
      
      

2.  Possible potential solutions for back end code:

   1. Pull in and create a Spring version of policy-models/tosca in our project, leaving policy-models/tosca to be used by policy.

      1. This would allow for a fully Spring application, could implement spring way of models and DB interactions, fully utilising its functionality.

      2. This deviates from the other Policy Framework components, does not use any of the policy-common, etc, making it a standalone as such, similar to previous CLAMP

   2. Leave and use policy stuff as is, only convert our stuff to Spring.

      1. Would not affect policy components

      2. Rather awkward for our own code base, would need to make specific connections to join the dots between differences. (Example can be found in Francesco's reviews) 

   3. End up doing the code the policy framework way and take out Spring.

      1. Familiar code, although missing out on Spring features such as transaction handling 
         
         
         

3.  Possible potential solutions for REST code:

   1. Use Camel, as is done in CLAMP now.

      1. I believe camel can serve a purpose, but especially with the future use of participants, all the 'routes' will be gone, leaving less incentive for camel to be used, especially for definitions of rest endpoints

   2. If we decide to go with Spring for the code, then use Spring to define the REST end points, or if we decide to go to policy framework style code, define the REST end points as is defined there

Database population in CLAMP and Control Loop PoC

1. PoC uses persistence.xml files in which you can include the JPA classes defined to generate the ddl using eclipselink. Persistence unit gets defined in the config file, which then refers to the persitence.xml file and looks for the persistence unit name to create the tables of the jpa classes input within it. 

   1.  persistence.xml example

      persistence.xml example

      
      
      

2. CLAMP uses a hibernate maven plugin which generates a ddl from classes within a certain package. (org.onap.policy.clamp). It reads the packages and looks for classes "@Entity" and reads the defined table and column details from them. This plugin then outputs an sql file (create-tables.sql) which gets used in a bootstrap script to create tables along side the database.