Info
This page describes the Architecture and Design used for the Tosca Defined Control Loop PoCs executed in the Guilin and Honolulu releases. Please see TOSCA Defined Control Loops: Architecture and Design for the Architecture and Design being used in the Istanbul release.

Table of Contents

...

The idea of using control loops to automatically (or autonomously) perform network management has been the subject of much research in the Network Management research community, see this paper for some background. However, it is only with the advent of ONAP that we have a platform that supports control loops for network management. Before ONAP, Control Loops have been implemented by hard-coding components together and hard coding logic into components. ONAP has taken a step forward towards automatic implementation of Control Loops by allowing parameterization of Control Loops that work on the premise that the Control Loops use a set of analytic, policy, and control components connected together in set ways.

...

Once a control loop definition has been commissioned, instances of the control loop can be created, updated, and deleted. The system manages the lifecycle of control loops following the state transition diagram below.

draw.io Diagram

border	true

diagramName	Control Loop Instance States
simpleViewer	false
links	auto
tbstyle	top
lbox	true
diagramWidth	1051
revision	8

1: Overall Architecture

The diagram below shows an overview of the architecture of TOSCA based Control Loop management.

...

The Control Loop Runtime Management will use ONAP services for non-functional aspects such as inventory, topology and data delivery.

1.1: Class Diagrams

1.1.1 Design Time

draw.io Diagram

border	true
diagramName	Class Diagrams
simpleViewer	false
links	auto
tbstyle	top
lbox	true
diagramWidth	1182
revision	5

1.1.2 Runtime

Comment

draw.io Diagram

border	true
diagramName	Runtime Class diagram
simpleViewer	false
links	auto
tbstyle	top
lbox	true
diagramWidth	2152
revision	3

1.2: ERD

draw.io Diagram

border	true
diagramName	ERD
simpleViewer	false
links	auto
tbstyle	top
lbox	true
diagramWidth	1241
revision	3

2: Control Loop Modelling

Joseph O'Leary to pad out this section

...

Dynamic config on the other hand can be a monitoring policy, or any other resource that provides config to parts of the loop, can be updated after the run time phase has started and is supported by the components hosting the applications in the control loop.

2.1: Control Loop TOSCA file definition

2.1.1 Control Loop Component Definition

A Control Loop Component that can be part of a control loop, it defines the components that partake in a control loop, and are implemented at run time by participants. The control loop component definition is truly dynamic and, as long as the participant that the control loop component definition relates to understands its definition, it can be anything. However, we have designed a base control loop component attribute that's generic and that can act as a good starting point.

Code Block

language	yml
title	Control Loop Node Definition
linenumbers	true
collapse	true

node_types:
  org.onap.CL_Component:
    properties:
      component_name:
        type: string
        description: Human readable name for the component.
        required: true
      provider:
        type: string
        description: Provider of the component and of the descriptor.
        required: true
      component_version:
        type: string
        description: Software version of the component.
        required: true
      resource_id:
        type: string
        description: >The ID of the resource, 
          should be provided if the resource was uploaded to the entity's inventory already.
        required: false
      resource_content:
        type: string
        description: the contents of the component resource, to be uploaded during commssioning phase of loop.
        required: false
      monitoring_policy:
        type: string
        description: A reference to the monitoring policy if applicable.
        required: false
    version: 0.0.1
    derived_from: tosca.nodes.Root

2.1.2 Loop Definition

The loop definition is explicit in the node_templates within the topology_template, a Control Loop node template is specified and any node tempalte specified in the Control Loop node tepolcate is part of the control loop managed by CLAMP.

...

Code Block

language	yml
title	Loop Definition
linenumbers	true
collapse	true

tosca_definitions_version: tosca_simple_yaml_1_3
data_types:
  onap.datatypes.ToscaConceptIdentifier:
    derived_from: tosca.datatypes.Root
    properties:
      name:
        type: string
        required: true
      version:
        type: string
        required: true
node_types:
  org.onap.policy.clamp.controlloop.Participant:
    version: 1.0.1
    derived_from: tosca.nodetypes.Root
    properties:
      provider:
        type: string
        requred: false
  org.onap.policy.clamp.controlloop.ControlLoopElement:
    version: 1.0.1
    derived_from: tosca.nodetypes.Root
    properties:
      provider:
        type: string
        requred: false
      participant_id:
        type: onap.datatypes.ToscaConceptIdentifier
        requred: true
  org.onap.policy.clamp.controlloop.ControlLoop:
    version: 1.0.1
    derived_from: tosca.nodetypes.Root
    properties:
      provider:
        type: string
        requred: false
      elements:
        type: list
        required: true
        entry_schema:
          type: onap.datatypes.ToscaConceptIdentifier
  org.onap.policy.clamp.controlloop.DCAEMicroserviceControlLoopElement:
    version: 1.0.1
    derived_from: org.onap.policy.clamp.controlloop.ControlLoopElement
    properties:
      dcae_blueprint_id:
        type: onap.datatypes.ToscaConceptIdentifier
        requred: true
  org.onap.policy.clamp.controlloop.PolicyTypeControlLoopElement:
    version: 1.0.1
    derived_from: org.onap.policy.clamp.controlloop.ControlLoopElement
    properties:
      policy_type_id:
        type: onap.datatypes.ToscaConceptIdentifier
        requred: true
  org.onap.policy.clamp.controlloop.CDSControlLoopElement:
    version: 1.0.1
    derived_from: org.onap.policy.clamp.controlloop.ControlLoopElement
    properties:
      cds_blueprint_id:
        type: onap.datatypes.ToscaConceptIdentifier
        requred: true
topology_template:
  node_templates:
    org.onap.dcae.controlloop.DCAEMicroserviceControlLoopParticipant:
      version: 2.3.4
      type: org.onap.policy.clamp.controlloop.Participant
      type_version: 1.0.1
      description: Participant for DCAE microservices
      properties:
        provider: ONAP
    org.onap.policy.controlloop.MonitoringPolicyControlLoopParticipant:
      version: 2.3.1
      type: org.onap.policy.clamp.controlloop.Participant
      type_version: 1.0.1
      description: Participant for DCAE microservices
      properties:
        provider: ONAP
    org.onap.policy.controlloop.OperationalPolicyControlLoopParticipant:
      version: 3.2.1
      type: org.onap.policy.clamp.controlloop.Participant
      type_version: 1.0.1
      description: Participant for DCAE microservices
      properties:
        provider: ONAP
    org.onap.ccsdk.cds.controlloop.CdsControlLoopParticipant:
      version: 2.2.1
      type: org.onap.policy.clamp.controlloop.Participant
      type_version: 1.0.1
      description: Participant for DCAE microservices
      properties:
        provider: ONAP
    org.onap.domain.pmsh.PMSH_DCAEMicroservice:
      version: 1.2.3
      type: org.onap.policy.clamp.controlloop.DCAEMicroserviceControlLoopElement
      type_version: 1.0.0
      description: Control loop element for the DCAE microservice for Performance Management Subscription Handling
      properties:
        provider: Ericsson
        participant_id:
          name: org.onap.dcae.controlloop.DCAEMicroserviceControlLoopParticipant
          version: 2.3.4
        dcae_blueprint_id:
          name: org.onap.dcae.blueprints.PMSHBlueprint
          version: 1.0.0
    org.onap.domain.pmsh.PMSH_MonitoringPolicyControlLoopElement:
      version: 1.2.3
      type: org.onap.policy.clamp.controlloop.PolicyTypeControlLoopElement
      type_version: 1.0.0
      description: Control loop element for the monitoring policy for Performance Management Subscription Handling
      properties:
        provider: Ericsson
        participant_id:
          name: org.onap.policy.controlloop.PolicyControlLoopParticipant
          version: 2.3.1
        policy_type_id:
          name: onap.policies.monitoring.pm-subscription-handler
          version: 1.0.0
    org.onap.domain.pmsh.PMSH_OperationalPolicyControlLoopElement:
      version: 1.2.3
      type: org.onap.policy.clamp.controlloop.PolicyTypeControlLoopElement
      type_version: 1.0.0
      description: Control loop element for the operational policy for Performance Management Subscription Handling
      properties:
        provider: Ericsson
        participant_id:
          name: org.onap.policy.controlloop.PolicyControlLoopParticipant
          version: 2.3.1
        policy_type_id:
          name: onap.policies.operational.pm-subscription-handler
          version: 1.0.0
    org.onap.domain.pmsh.PMSH_CDS_ControlLoopElement:
      version: 1.2.3
      type: org.onap.policy.clamp.controlloop.ControlLoopElement
      type_version: 1.0.0
      description: Control loop element for CDS for Performance Management Subscription Handling
      properties:
        provider: Ericsson
        participant_Id:
          name: org.onap.ccsdk.cds.controlloop.CdsControlLoopParticipant
          version: 3.2.1
        cds_blueprint_id:
          name: org.onap.ccsdk.cds.PMSHCdsBlueprint
          version: 1.0.0
    org.onap.domain.pmsh.PMSHControlLoopDefinition:
      version: 1.2.3
      type: org.onap.policy.clamp.controlloop.ControlLoop
      type_version: 1.0.0
      description: Control loop for Performance Management Subscription Handling
      properties:
        provider: Ericsson
        elements:
        - name: org.onap.domain.pmsh.PMSH_DCAEMicroservice
          version: 1.2.3
        - name: org.onap.domain.pmsh.PMSH_MonitoringPolicyControlLoopElement
          version: 1.2.3
        - name: org.onap.domain.pmsh.PMSH_OperationalPolicyControlLoopElement
          version: 1.2.3
        - name: org.onap.domain.pmsh.PMSH_CDS_ControlLoopElement
          version: 1.2.3

2.1.3 Example of two Control Loop instances

Code Block

language	yml
title	Example Control Loop Instances
linenumbers	true
collapse	true

{
    "controlLoops": [
        {
            "name": "PMSHInstance0",
            "version": "1.0.1",
            "definition": {
                "name": "org.onap.domain.pmsh.PMSHControlLoopDefinition",
                "version": "1.0.0"
            },
            "state": "UNINITIALISED",
            "orderedState": "UNINITIALISED",
            "description": "PMSH control loop instance 0",
            "elements": [
                {
                    "id": "709c62b3-8918-41b9-a747-d21eb79c6c20",
                    "definition": {
                        "name": "org.onap.domain.pmsh.PMSH_DCAEMicroservice",
                        "version": "1.2.3"
                    },
                    "participantId": {
                        "name": "DCAEParticipant0",
                        "version": "1.0.0"
                    },
                    "state": "UNINITIALISED",
                    "orderedState": "UNINITIALISED",
                    "description": "DCAE Control Loop Element for the PMSH instance 0 control loop"
                },
                {
                    "id": "709c62b3-8918-41b9-a747-d21eb79c6c21",
                    "definition": {
                        "name": "org.onap.domain.pmsh.PMSH_MonitoringPolicyControlLoopElement",
                        "version": "1.2.3"
                    },
                    "participantId": {
                        "name": "PolicyParticipant0",
                        "version": "1.0.0"
                    },
                    "state": "UNINITIALISED",
                    "orderedState": "UNINITIALISED",
                    "description": "Monitoring Policy Control Loop Element for the PMSH instance 0 control loop"
                },
                {
                    "id": "709c62b3-8918-41b9-a747-d21eb79c6c22",
                    "definition": {
                        "name": "org.onap.domain.pmsh.PMSH_OperationalPolicyControlLoopElement",
                        "version": "1.2.3"
                    },
                    "participantId": {
                        "name": "PolicyParticipant0",
                        "version": "1.0.0"
                    },
                    "state": "UNINITIALISED",
                    "orderedState": "UNINITIALISED",
                    "description": "Operational Policy Control Loop Element for the PMSH instance 0 control loop"
                },
                {
                    "id": "709c62b3-8918-41b9-a747-d21eb79c6c23",
                    "definition": {
                        "name": "org.onap.domain.pmsh.PMSH_CDS_ControlLoopElement",
                        "version": "1.2.3"
                    },
                    "participantId": {
                        "name": "CDSParticipant0",
                        "version": "1.0.0"
                    },
                    "state": "UNINITIALISED",
                    "orderedState": "UNINITIALISED",
                    "description": "CDS Control Loop Element for the PMSH instance 0 control loop"
                }
            ]
        },
        {
            "name": "PMSHInstance1",
            "version": "1.0.1",
            "definition": {
                "name": "org.onap.domain.pmsh.PMSHControlLoopDefinition",
                "version": "1.0.0"
            },
            "state": "UNINITIALISED",
            "orderedState": "UNINITIALISED",
            "description": "PMSH control loop instance 1",
            "elements": [
                {
                    "id": "709c62b3-8918-41b9-a747-e21eb79c6c24",
                    "definition": {
                        "name": "org.onap.domain.pmsh.PMSH_DCAEMicroservice",
                        "version": "1.2.3"
                    },
                    "participantId": {
                        "name": "DCAEParticipant0",
                        "version": "1.0.0"
                    },
                    "state": "UNINITIALISED",
                    "orderedState": "UNINITIALISED",
                    "description": "DCAE Control Loop Element for the PMSH instance 1 control loop"
                },
                {
                    "id": "709c62b3-8918-41b9-a747-e21eb79c6c25",
                    "definition": {
                        "name": "org.onap.domain.pmsh.PMSH_MonitoringPolicyControlLoopElement",
                        "version": "1.2.3"
                    },
                    "participantId": {
                        "name": "PolicyParticipant0",
                        "version": "1.0.0"
                    },
                    "state": "UNINITIALISED",
                    "orderedState": "UNINITIALISED",
                    "description": "Monitoring Policy Control Loop Element for the PMSH instance 1 control loop"
                },
                {
                    "id": "709c62b3-8918-41b9-a747-e21eb79c6c26",
                    "definition": {
                        "name": "org.onap.domain.pmsh.PMSH_OperationalPolicyControlLoopElement",
                        "version": "1.2.3"
                    },
                    "participantId": {
                        "name": "PolicyParticipant0",
                        "version": "1.0.0"
                    },
                    "state": "UNINITIALISED",
                    "orderedState": "UNINITIALISED",
                    "description": "Operational Policy Control Loop Element for the PMSH instance 1 control loop"
                },
                {
                    "id": "709c62b3-8918-41b9-a747-e21eb79c6c27",
                    "definition": {
                        "name": "org.onap.domain.pmsh.PMSH_CDS_ControlLoopElement",
                        "version": "1.2.3"
                    },
                    "participantId": {
                        "name": "CDSParticipant0",
                        "version": "1.0.0"
                    },
                    "state": "UNINITIALISED",
                    "orderedState": "UNINITIALISED",
                    "description": "CDS Control Loop Element for the PMSH instance 1 control loop"
                }
            ]
        }
    ]
}

2.2: Modelling from TOSCA to Commissioned Data in Run Time Inventory

draw.io Diagram

border	true
diagramName	Interactions
simpleViewer	false
links	auto
tbstyle	top
lbox	true
diagramWidth	1081
revision	1

2.3: Modelling from TOSCA to Instance Data Run Time Inventory

2.4: Swagger REST APIs for Control Loop

ControlLoop Runtime Swagger REST APIs:

ControlLoop_Runtime_Swagger_API.yml

Participant Swagger REST APIs:

Participant_Swagger_API.yml

3: APIs and Sequence Diagrams

3.1: Commissioning

Ajay Deep Singh to pad out this section

...

Warning
In future commissioning Rest Endpoint might be updated to push ControlLoops not only in RunTime Database but to the participants involved in ControlLoop.

3.1.1: Commissioning REST API

Code Block

language	yml
theme	Eclipse
title	Initial Swagger Draft for Deployment API
linenumbers	true
collapse	true

openapi: 3.0.3
info:
  description: >-
    The ControlLoop Commissioning API allows users to search and perform
    CRUD action on Controlloop Tosca exported data sets.
  version: 1.0.0
  title: Control Loop Commissioning API
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0'
  contact:
    email: lego@est.tech
servers:
  - url: '{scheme}://onap/controlloop/v2/'
    variables:
      scheme:
        description: 'The Data Set API is accessible via https and http'
        enum:
          - 'https'
          - 'http'
        default: 'http'
tags:
  - name: Control Loop 
    description: Commissioning API
  - name: design-catalogue
    description: CRUD actions on an designtime Control Loop data sets.
  - name: runtime-inventory
    description: CRUD actions on an runtime Control Loop data sets.
paths:
  /design-catalogue/loops:
    get:
      tags:
        - design-catalogue
      operationId: getAllLoopsUsingGET
      summary: Returns a list of all available Control Loops.
      responses:
        '200':
          description: OK
          content:
            application/yaml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ControlLoop'
                  
  /design-catalogue/loop/{controlLoopId}:
    get:
      tags:
        - design-catalogue
      summary: >-
        Returns a specific control loop.
      description: >-
        This GET API returns a specific control loop.
      operationId: getLoopByIdUsingGET
      parameters:
        - name: controlLoopId
          in: path
          description: 'Id of the control loop.'
          required: true
          example: "org.onap.PM_CDS_Blueprint"
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/ControlLoop'
  
    delete:
      tags:
        - design-catalogue
      summary: Delete a specific Control Loop by ID.
      operationId: deleteLoopByIdUsingDELETE
      parameters:
        - name: controlLoopId
          in: path
          description: Identity for the control loop
          required: true
          style: simple
          schema:
            type: string
      responses:
        '200':
          description: OK
        '404':
          description: Control Loop not present

    post:
      tags:
        - design-catalogue
      summary: >-
        Accepts a Tosca Service Template representing a Control Loop.
      description: >-
        This API Create a Control Loop.
      operationId: createLoopWithIDUsingPOST
      parameters:
        - name: controlLoopId
          in: path
          description: Identity for the control loop
          required: true
          style: simple
          schema:
            type: string
      responses:
        '200':
          description: OK
        '409':
          description: Control Loop already exist.
     
    put:
      tags:
        - design-catalogue
      summary: Updates a Control Loop.
      operationId: updateLoopWithIDUsingPUT
      parameters:
        - name: controlLoopId
          in: path
          description: Identity for the control loop
          required: true
          style: simple
          schema:
            type: string
      responses:
        '200':
          description: OK
        '404':
          description: Control Loop not found
          
  /runtime-inventory/commission:
    post:
      tags:
        - runtime-inventory
      summary: >-
        Commissions Tosca Service Template in RunTime Inventory.
      description: >-
        This API commissions Tosca Service Template in RunTime Inventory DB.
      operationId: commissionLoopWithPOST
      responses:
        '200':
          description: OK
        '404':
          description: No matching record found for the given criteria.
          
  /runtime-inventory/loop/{controlLoopId}:
    get:
      tags:
        - runtime-inventory
      summary: >-
        Returns a specific control loop.
      description: >-
        This GET API returns a specific control loop.
      operationId: getLoopByIdUsing
      parameters:
        - name: controlLoopId
          in: path
          description: 'Id of the control loop.'
          required: true
          example: "org.onap.PM_CDS_Blueprint"
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/yaml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ControlLoop'
  
    delete:
      tags:
        - runtime-inventory
      summary: Delete a specific Control Loop by ID.
      operationId: deleteLoopByIdUsing
      parameters:
        - name: controlLoopId
          in: path
          description: Identity for the control loop
          required: true
          style: simple
          schema:
            type: string
      responses:
        '200':
          description: OK
        '404':
          description: Control Loop not present

    post:
      tags:
        - runtime-inventory
      summary: >-
        Accepts a Tosca Service Template representing a Control Loop.
      description: >-
        This API Create a Control Loop.
      operationId: createLoopWithIDUsing
      parameters:
        - name: controlLoopId
          in: path
          description: Identity for the control loop
          required: true
          style: simple
          schema:
            type: string
      responses:
        '200':
          description: OK
        '409':
          description: Control Loop already exist.
     
    put:
      tags:
        - runtime-inventory
      summary: Updates a Control Loop.
      operationId: updateLoopWithIDUsing
      parameters:
        - name: controlLoopId
          in: path
          description: Identity for the control loop
          required: true
          style: simple
          schema:
            type: string
      responses:
        '200':
          description: OK
        '404':
          description: Control Loop not found

components:
  schemas:
    ControlLoop:
      title: ControlLoop
      type: object
      properties:
        id:
          type: string
        ControlLoop:
          type: string

3.1.2: Commissioning Sequence Diagrams

GET, DELETE, CREATE API ControlLoop Sequence Diagram

PlantUML Macro

title	GET, DELETE, CREATE API Sequence Diag

@startuml

actor CLAMP
participant API_Gateway
database Database
note over Database: It can be DesiginTime Catalogue Or RunTime Inventory Database


CLAMP -> API_Gateway: Rest API Request (JSON/Yaml)
API_Gateway -> Database: Get, Delete Or Create ControlLoops
activate API_Gateway
note over API_Gateway,Database: Pull, Delete existing Or Create New ControlLoops in Database

alt successful case

    Database -> API_Gateway : Return List of ControlLoops Or able to Delete, Create ControlLoop in Database
    API_Gateway -> CLAMP: Return Success

else failure case

    API_Gateway <- Database: Return either Empty List for Get ControlLoops Or Failure Status for Delete, Create Request
	deactivate API_Gateway
    note over Database: No ControlLoops exist Or Failed in Deleting, Creating ControlLoops
    API_Gateway -> CLAMP : Return Failure

end
@enduml

Commission API ControlLoop Sequence Diagram

PlantUML Macro

title	Deploy API ControlLoop Sequence Diag

@startuml

actor CLAMP
participant API_Gateway
database DesignTime_Catalogue_Database
database RunTime_Inventory_Database
participant Dmaap
collections Participants

CLAMP -> API_Gateway: Rest Commission API Request (JSON/Yaml)
API_Gateway -> DesignTime_Catalogue_Database: Fetch ControlLoop from DesignTime Catalogue Database
activate API_Gateway
note over API_Gateway,DesignTime_Catalogue_Database: Fetch existing ControlLoops from DesignTime Catalogue Database

alt successful case
    DesignTime_Catalogue_Database -> API_Gateway : Return List of existing ControlLoops from DesignTime Catalogue Database
    note over DesignTime_Catalogue_Database, RunTime_Inventory_Database: Populate RunTime Inventory with ControlLoops existing in DesignTime Catalogue Database
    API_Gateway -> RunTime_Inventory_Database: Push ControlLoop to RunTime Inventory Database
    note over Dmaap: Putting ControlLoop Metadata for individual Participant
    API_Gateway -> Dmaap: Push ControlLoop to individual Participants(App) over Dmaap
    note over Dmaap,Participants: Asynchronous communication
    Dmaap -> Participants
    API_Gateway -> CLAMP: Return Success

else failure case

    API_Gateway <- DesignTime_Catalogue_Database: Return Empty ControlLoop List, No ControlLoop exist in DesignTime Catalogue
	deactivate API_Gateway
    note over API_Gateway, DesignTime_Catalogue_Database: DesignTime Catalogue Database is Empty, cannot commission ControLoop in RunTime Inventory Database 
    API_Gateway -> CLAMP : Return Failure

end
@enduml

3.2: Instantiation

Robertas Rimkus to pad out this section

This section refers to Instantiation of a Commissioned control loop. A client, in this case CLAMP (potentially DCAEMOD, etc in the future) will render the commissioned control loops allowing selection of a particular control loop to be instantiated. User will then provide the configurations needed to instantiate the selected control loop which will be sent onto the CL_Instance_Control Service. The service will then distribute the configurations to DMaaP topic. Participants (agents) will pull the event containing the config and pick out their control loop components to be instantiated and start/set up those particular components. CL_Instance_Control Service will be waiting for a response back from all participants involved in the instantiation of the control loop, in regards to the state of instantiation. In successful response case the service will store the CL Instance LCM (Life Cycle management) data into the runtime DB as well as providing a message back to the client of the successful instantiation. In failure to receive the response case, a timeout will be called, which will result in a teardown event being sent to DMaaP. The participants will then receive the event and proceed to teardown the components that were instantiated or check that they have failed to instantiate in the first place and send a Teardown ACK back to the CL_Instance_Control Service. No CL Instance LCM data will be stored and a message indicating failure to instantiate the CL along side with the error will be sent back to the client (CLAMP).

3.2.1: Instantiation REST API

Code Block

language	yml
title	Initial Swagger for Initiation API
collapse	true

openapi: 3.0.3
info:
  title: Swagger Control Loop Instantiation
  description: ""
  version: 1.0.0
servers:
  - url: '{scheme}://onap/controlloop/v2/'
    variables:
      scheme:
        description: 'The Data Set API is accessible via https and http'
        enum:
          - 'https'
          - 'http'
        default: 'http'
tags:
- name: instantiate
  description: Control Loop Instantiation
paths:
  /runtime-inventory/instantiate:
    post:
      tags:
      - instantiate
      summary: Instantiate a commissioned control loop
      operationId: instantiateLoop
      requestBody:
        description: Control loop that is to be instantiated
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ControlLoop'
        required: true
      responses:
        200:
          description: OK
          content:            
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApiResponse'
        404:
          description: No Control Loop found
        405:
          description: Invalid input
  /runtime-inventory/loops/instantiated:
    get:
      tags:
      - instantiate
      summary: Get a list of instantiated control loops
      responses:
        200:
          description: Success
          content:            
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ControlLoop'
        404:
          description: No instantiated control loops found
  /runtime-inventory/loops/instantiated/{loop-id}:
    get:
      tags:
      - instantiate
      summary: Get an instantiated control loop by id
      parameters:
      - name: loop-id
        in: path
        description: ID of instantiated loop to return
        required: true
        schema:
          type: string
      responses:
        200:
          description: OK
          content:            
            application/json:
              schema:
                $ref: '#/components/schemas/ControlLoop'
        404:
          description: Control Loop not found
    put:
      tags:
      - instantiate
      summary: Update an instantiated control loop
      parameters:
      - name: loop-id
        in: path
        description: ID of instantiated loop
        required: true
        schema:
          type: string
      requestBody:
        description: Control loop to be updated
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ControlLoop'
        required: true
        
      responses:
        200:
          description: OK
          content:            
            application/json:
              schema:
                $ref: '#/components/schemas/ControlLoop'
        404:
          description: Control Loop not found
    delete:
      tags:
      - instantiate
      summary: Delete an instantiated control loop
      parameters:
      - name: loop-id
        in: path
        description: ID of instantiated loop
        required: true
        schema:
          type: string
      responses:
        200:
          description: OK
        404:
          description: Control Loop not found
components:
  schemas:
    ControlLoop:
      title: ControlLoop
      type: object
      properties:
        id:
          type: string
        controlLoopTosca:
          type: string
    ApiResponse:
      type: object
      properties:
        code:
          type: integer
          format: int32
        status:
          type: string

3.2.2: Instantiation Sequence Diagrams

PlantUML Macro

title	Instantiation

@startuml

actor CLAMP
participant Commissioning_API
database Runtime_DB
control CL_Instance_Control
participant DmaaP
collections Participants

CLAMP -> Commissioning_API : Fetch all Commissioned Control Loops
Commissioning_API -> Runtime_DB : Rest call to get the Commissioned Control Loops
Runtime_DB -> Commissioning_API : Return all Commissioned Loops which reside in the database
Commissioning_API -> CLAMP : Provide the data
CLAMP -> CLAMP : Select Control Loop to be instantiated and provide configurations for it
CLAMP -> CL_Instance_Control : Instantiate CL POST REST API call

alt case where CLAMP sends commissioned CL id instead of the full CL in the body

CL_Instance_Control -> Runtime_DB : Fetch the Commissioned Control Loop from Models table
Runtime_DB -> CL_Instance_Control : Return the requested Commissioned Control Loop data

end

CL_Instance_Control -> DmaaP : INSTANTIATE Event (JSON/Yaml)
note over CL_Instance_Control, DmaaP : List of Participant ID's containing Participant Metadata Blocks
Participants -> DmaaP : Pulls its part of CL and tries to Instantiate

alt failure case

note over CL_Instance_Control : TIMEOUT, Instantiation ACK not received by monitoring service \nSupervision_Service requests a teardown
CL_Instance_Control -> DmaaP : TEARDOWN Event (JSON/Yaml)
Participants -> DmaaP : Pulls its part of CL and starts Teardown

end
@enduml

3.2.3: Instantiation DMaaP API

Initial Thought for an event to be sent from CL_Instance_Control onto DMaaP for Participants to consume. The event would go onto an output topic which the Participants would be polling/subscribed to

...

*Preferred solution is to send TOSCA in the body. Meaning we could reuse the parsing code which is already present and provide it to the participant.

3.2.4: Instantiation Participant API

*Suggestion was to put JAVA API code in this section for the participant talking to DMaaP. TBD

3.3: Monitoring

In this case it refers to monitoring the data that the participants will provide to DMaaP. Participants will send events to DMaaP which will be pulled by the CL_MonitoringSupervision_Service in to the runtime database. Monitoring service provides APIs to display the statistics data from runtime database to the Monitoring GUI. The data provided should include a reference id to the control loops that are instantiated on the participant, as well as the applications that have been instantiated as a part of that control loop for that participant. Data should also include the time that the application has started, state of it (running/terminated) and any other critical information which would help to determine the health of an instantiated control loop and its components. Idea is for the participant to provide events every certain period of time, similar to a health-check, in order to provide consistent monitoring.

3.3.1: Monitoring REST API

Code Block

language	yml
title	Initial Swagger for Monitoring API
collapse	true

openapi: 3.0.3
info:
  title: Swagger Control Loop Monitoring
  description: ""
  version: 1.0.0
servers:
  - url: '{scheme}://onap/controlloop/v2/'
    variables:
      scheme:
        description: 'The Data Set API is accessible via https and http'
        enum:
          - 'https'
          - 'http'
        default: 'http'
tags:
- name: monitoring
  description: Control Loop Monitoring
paths:
  /runtime-inventory/monitoring:
    post:
      tags:
      - monitoring
      summary: Input monitoring data into the database
      requestBody:
        description: Monitoring data to be input
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MonitoringData'
        required: true
      responses:
        200:
          description: OK
        405:
          description: Invalid input
    get:
      tags:
      - monitoring
      summary: Get monitoring data for all participants
      responses:
        200:
          description: Success
          content:            
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MonitoringData'
        404:
          description: No monitoring data found
  /runtime-inventory/monitoring/{participant-id}:
    get:
      tags:
      - monitoring
      summary: Get monitoring data for a participant by participant id
      parameters:
      - name: participant-id
        in: path
        description: ID of a participant 
        required: true
        schema:
          type: string
      responses:
        200:
          description: OK
          content:            
            application/json:
              schema:
                $ref: '#/components/schemas/MonitoringData'
        404:
          description: Monitoring data for the participant not found
    put:
      tags:
      - monitoring
      summary: Update monitoring data for a participant by participant id
      parameters:
      - name: participant-id
        in: path
        description: ID of a participant
        required: true
        schema:
          type: string
      requestBody:
        description: Monitoring data to be updated
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MonitoringData'
        required: true
      responses:
        200:
          description: OK
          content:            
            application/json:
              schema:
                $ref: '#/components/schemas/MonitoringData'
        404:
          description: Monitoring data for the participant not found
    delete:
      tags:
      - monitoring
      summary: Delete monitoring data for a participant by participant id
      parameters:
      - name: participant-id
        in: path
        description: ID of a participant
        required: true
        schema:
          type: string
      responses:
        200:
          description: OK
        404:
          description: Monitoring data for the participant not found
components:
  schemas:
    MonitoringData:
      properties:
        participant-id:
          type: string
        control-loops:
          type: array
          items:
            properties:
              cl-instance-id:
                type: string
              applications:
                type: array
                items:
                  properties:
                    application-id:
                      type: string
                    status:
                      type: string
                      enum:
                        - INSTANTIATION_STARTED
                        - INSTANTIATED_RUNNING
                        - INSTANTIATED_FAILED
                    other-data:
                      type: string

3.3.2: Monitoring Sequence Diagrams

PlantUML Macro

title	Monitoring Sequence Diagram

@startuml

control CL_Instance_Control
database Runtime_DB
participant Monitoring_Service
participant DMaaP
collections Participants

CL_Instance_Control -> DMaaP : INSTANTIATE Event (JSON/Yaml)
Participants -> DMaaP : Pulls its part of CL and starts instantiation of components

Participants -> DMaaP : Starts sending monitoring events once instantiation of components begins
note over DMaaP : Events are sent at set intervals

MonitoringSupervision_Service service-> DMaaP : Consistently pulls events off the monitoring topic
Monitoring_Service -> Runtime_DB : Puts and updates the monitoring data on the DB

@enduml

3.3.3: Monitoring DMaaP API

Participants will send an event containing monitoring data to a DMaaP topic at a set interval after participant has received an event to instantiate a control loop

...

Code Block

language	yml
title	Example event from Participant to DmaaP
collapse	true

{
  "timestamp":"1605689254",
  "participant-id":"Participant_DCAE",
  "control-loops":[
    {
      "instance-id":"myCLInstance1",
      "applications":[
        {
          "application-id":"example.pmsh",
          "status":"INSTANTIATION_STARTED"
        },
        {
          "application-id":"example.dfc",
          "status":"INSTANTIATION_STARTED"
        }
      ]
    },
    {
      "instance-id":"myCLInstance2",
      "applications":[
        {
          "application-id":"example.pmsh",
          "status":"INSTANTIATED"
        }
      ]
    }
  ]
}

3.3.4: Monitoring Participant API

Presume similar thinking to Instantiation Participant API

*Suggestion was to put JAVA API code in this section for the participant talking to DMaaP. TBD

3.4: Supervision

Supervision is responsible for ensuring that

control loops are established once their initiation has been ordered
control loops are running correctly once their initiation is completed
control loops are correctly removed once their removal has been ordered

3.4.1: Supervision Sequence Diagrams

PlantUML Macro

title	Big Sequence Diagram

@startuml

actor Client
participant Commissioning_API
control CL_Instance_Control
database Runtime_DB
participant Supervision_Service
participant Monitoring_Service
participant DMaaP
collections Participants


==Instantation==

Client -> Commissioning_API : Fetch all Commissioned Control Loops
Commissioning_API -> Runtime_DB : Rest call to get Commissioned Control Loops
Runtime_DB -> Commissioning_API : Return Commissioned Control Loops
Commissioning_API -> Client : Provide the data
Client -> Client : Select CL for instantiation and provide config
Client -> CL_Instance_Control : Instantiate CL POST REST API call

alt case where Client sends commissioned CL id instead of the full CL in the body

CL_Instance_Control -> Runtime_DB : Fetch the Commissioned Control Loop from Models table
Runtime_DB -> CL_Instance_Control : Return the requested Commissioned Control Loop data

end

CL_Instance_Control -> DMaaP : INSTANTIATE Event (JSON/Yaml)
note over CL_Instance_Control, DMaaP : List of Participant ID's containing Participant Metadata Blocks
Participants -> DMaaP : Pulls its part of CL and tries to Instantiate


==Monitoring==

Participants -> DMaaP : Starts sending monitoring events \nOnce instantiation of components begins
note over DMaaP : Events are sent at set intervals, one per participant

MonitoringSupervision_Service -> DMaaP : Consistently pulls events off the monitoring topic
Monitoring_Service -> Runtime_DB : Puts and updates the monitoring data on the DB


==Supervision==

Supervision_Service -> Runtime_DBDMaap : Periodic check on monitoring data

alt CL successfully instantiated

Supervision_Service -> Client : Return Instantiation Successful

else CL failed to instantiate

... TIMEOUT CL state not changed to INSTANTIATED ...
Supervision_Service -> CL_Instance_Control : Timeout, error occured
CL_Instance_Control -> DMaaP : TEARDOWN Event (JSON/Yaml)
Participants -> DMaaP : Pulls its part of CL and starts Teardown
note over Monitoring_Service : Monitoring Service receives events and updates state
note over Supervision_Service : Supervision Service finds that status has changed
Supervision_Service -> Client : Return Instantiation Failed (http code and an error message) 

end
@enduml

3.4.2: Supervision APIs to other components

4: Design

4.1: Server Side

4.1.1 Database Schema and JPA

4.1.2: TOSCA Processing

4.1.3: Instance Control

4.1.4: Execution Monitoring

4.2: Participant Side

4.2.1: Participant Agent

4.2.2: Policy Participant Agent

4.2.3: CDS Participant Agent

...

Participant is a component that acts as a bridge between Runtime and components like Policy-framework, DCAE, Kubernetes cluster etc.
It listens to Dmaap to receive messages from runtime and performs operations towards control loop components.

Every participant has two parts Participant-Intermediary and a Participant-Impl.
Participant-Intermediary is a common component that listens to Dmaap and acts on the messages, participant-impl handles the logic towards
control loop element.

4.2.

...

1:

...

Participant

...

Message handling

4.3: Client Side

4.3.1: Client SDK: Composition of Control Loop Tosca

4.3.2: Client User Interface

4.4 Other Considerations

4.4.1 Upgrade

Performing a hot upgrade of the Control Loop at run time as well as handling an upgrade of the software in one or more of the participants in an Control Loop is a particularly challenging issue because upgrading must handle the following cases without tearing down the Control Loop:

...

Participant handles 4 types of messages

1. Participant State Change : This message handles states of a participant. Runtime can order participant for a state change.
ParticipantState can be set to one of the following
UNKNOWN : Control Loop execution is unknown.
PASSIVE : Control Loop execution is always rejected.
SAFE : Control Loop execution proceeds, but changes to domain state or context are not carried out.
The participant returns an indication that it is running in SAFE mode together with the action it would
have performed if it was operating in ACTIVE mode.
TEST : Control Loop execution proceeds and changes to domain and state are carried out in a test environment.
The participant returns an indication that it is running in TEST mode together with the action it has performed
on the test environment
ACTIVE : Control Loop execution is executed in the live environment by the participant.
TERMINATED : Control Loop execution is terminated and not available.

2. Control Loop Update: This message creates the control loop elements and brings them from UNINITIALIZED to PASSIVE state.
ControlLoopUpdate message contains full ToscaServiceTemplate describing all components participating in a control loop.
This acts as a template for any control loop to be created according to the template.
When participant-intermediary receives this message, it triggers creation of policy-types and policies in Policy-Framework by Policy-Participant,
and deploys DCAE from DCAE-participant

3. Control Loop State change: This message is used to order a state change in control loop element.
Runtime can order one of the following ordered states.
UNINITIALIZED : The control loop or control loop element should become uninitialized on participants, it should not exist on participants.
PASSIVE : The control loop or control loop element should initialized on the participants and be passive, that is,
it is not handling control loop messages yet.
RUNNING : The control loop or control loop element should running and is executing control loops. Once any of above states are ordered, then control loop element transitions into
UNINITIALIZED : The control loop or control loop element is not initialized on participants, it does not exist on participants.
UNINITIALIZED2PASSIVE : The control loop or control loop element is changing from uninitialized to passive,
it is being initialized onto participants.
PASSIVE : The control loop or control loop element is initialized on the participants but is passive, that is, it is not
handling control loop messages yet.
PASSIVE2RUNNING : The control loop or control loop element is changing from passive to running,
the participants are preparing to execute control loops.
RUNNING : The control loop or control loop element is running and is executing control loops.
RUNNING2PASSIVE : The control loop or control loop element is completing execution of current control loops but
will not start running any more control loops and will become passive.
PASSIVE2UNINITIALIZED : The control loop or control loop element is changing from passive to uninitialized,
the control loop is being removed from participants

4. Participant Healthcheck: This message is used to learn the health status of a participant.

As a response to any of the above message participant returns a Participant Status message, holding respective message response.
Runtime receives Participant Status message and stores relevant information in database, Or performs respective actions.

4.2.2: Policy Participant Agent

Policy participant receives messages through participant-intermediary common code, and handles them by invoking REST APIs towards policy-framework.

For example, When a ControlLoopUpdate message is received by policy participant, it contains full ToscaServiceTemplate describing all components
participating in a control loop. When the control loop element state changed from UNINITIALIZED to PASSIVE, Policy-participant triggers creation
of policy-types and policies in Policy-Framework.
When the state changes from PASSIVE to UNINITIALIZED, Policy-Participant deletes the policies, policy-types by invoking REST APIs towards policy-framework.

4.2.4: DCAE Participant Agent

DCAE participant receives messages through participant-intermediary common code, and handles them by invoking CLAMP DCAE methods,
which internally work towards DCAE.

For example, When a ControlLoopUpdate message is received by DCAE participant, it contains full ToscaServiceTemplate describing all components
participating in a control loop. When the control loop element state changed from UNINITIALIZED to PASSIVE, DCAE-participant triggers deploy
of DCAE.
When the state changes from PASSIVE to UNINITIALIZED, DCAE-Participant un-deploys DCAE by invoking methods towards CLAMP.

4.2.5: Kubernetes Participant Agent

Kubernetes participant receives messages through participant-intermediary common code, and handles them by invoking Kubernetes Open API.
For example, When a ControlLoopUpdate message is received by Kubernetes participant, When the control loop element state changed from UNINITIALIZED to PASSIVE, Kubernetes-participant triggers Kubernetes Open API and passes the HELM charts towards cluster.

4.3: Client Side

4.3.1: Client SDK: Composition of Control Loop Tosca

4.3.2: Client User Interface

4.4 Other Considerations

4.4.1 Upgrade

Performing a hot upgrade of the Control Loop at run time as well as handling an upgrade of the software in one or more of the participants in an Control Loop is a particularly challenging issue because upgrading must handle the following cases without tearing down the Control Loop:

Upgrade and changes of the configuration data of participants
Addition of or removal of participants in an Control Loop
Upgrade of software in one or more participants in an Control Loop
Maintenance of compatibility between participants when an update of more than one participant must be done together to ensure compatibility, for example, when a protocol being used by two participants to communicate is upgraded

4.4.2 Scalability

The system is designed to be inherently scalable. The control loop runtime server is stateless, all state is preserved in the run time inventory in the database. When the user requests a control loop operation (such as an instantiation, activation, passivation, or an ininitialization) the server broadcasts the request to participants over DMaaP and saves details of the request to the database. The server does not directly wait for responses to requests.

When a request is broadcast on DMaaP, the request is asynchronously picked up by participants of the types required for the control loop instance and those participants manage the life cycle of its control loop elements. Periodically, each participant reports back on the status of operations it has picked up for the control loop elements it controls, together with statistics on the control loop elements over DMaaP. On reception of these participant messages, the server stores this information to its database.

The server periodically runs a supervion function, which checks the status of all existing control loop instances and the status of outstanding requests. It builds a picture of the current status of each control loop instance from the reports on the elements of the control loop instances. Once the server has a full picture, it checks that the control loop instance is in the correct state as requested by the user of the system. If the control loop is not in the correct state, the supervision function can initiate actions such aas performing retries on operations or issuing alarms or notificaitons on control loop instances.

This approach makes it easy to scale control loop LCM. As control loop instance counts increase, more than one runtime server can be deployed and REST/supervision operations on control loop instances can run in parallel. The number of participants can scale because an asynchronous broadcast mechanism is used for server-participant communication and there is no direct connection or communication channel between participants and runtime servers. Participant state, control loop instance state, and control loop element state is held in the database, so any runtime server can handle operations for any participant. Because many participants of a particular type can be deployed and participant instances can load balance control loop element instances for different control loops of many types across themselves using a mechanism such as a Kubernetes cluster.

...

5: Goals

5.1: MVP

Jira

server	ONAP JIRA
columns	key,summary,assignee,priority,status
maximumIssues	1000
jqlQuery	"Epic Link" = REQ-478
serverId	425b2b0a-557c-3c0c-b515-579789cceedb

5.2: ControlLoop in Tosca LCM Istanbul Jiras

Jira

server	ONAP JIRA
columns	key,summary,assignee,priority,status
maximumIssues	1000
jqlQuery	"Epic Link" = REQ-716
serverId	425b2b0a-557c-3c0c-b515-579789cceedb

...

Space shortcuts

Page tree

Page History

Versions Compared

Old Version 168

New Version Current

Key

1: Overall Architecture

1.1: Class Diagrams

1.1.1 Design Time

1.1.2 Runtime

1.2: ERD

2: Control Loop Modelling

2.1: Control Loop TOSCA file definition

2.1.1 Control Loop Component Definition

2.1.2 Loop Definition

2.1.3 Example of two Control Loop instances

2.2: Modelling from TOSCA to Commissioned Data in Run Time Inventory

2.3: Modelling from TOSCA to Instance Data Run Time Inventory

2.4: Swagger REST APIs for Control Loop

3: APIs and Sequence Diagrams

3.1: Commissioning

3.1.1: Commissioning REST API

3.1.2: Commissioning Sequence Diagrams

3.2: Instantiation

3.2.1: Instantiation REST API

3.2.2: Instantiation Sequence Diagrams

3.2.3: Instantiation DMaaP API

3.2.4: Instantiation Participant API

3.3: Monitoring

3.3.1: Monitoring REST API

3.3.2: Monitoring Sequence Diagrams

3.3.3: Monitoring DMaaP API

3.3.4: Monitoring Participant API

3.4: Supervision

3.4.1: Supervision Sequence Diagrams

3.4.2: Supervision APIs to other components

4: Design

4.1: Server Side

4.1.1 Database Schema and JPA

4.1.2: TOSCA Processing

4.1.3: Instance Control

4.1.4: Execution Monitoring

4.2: Participant Side

4.2.1: Participant Agent

4.2.2: Policy Participant Agent

4.2.3: CDS Participant Agent

4.2.

1:

Participant

Message handling

4.3: Client Side

4.3.1: Client SDK: Composition of Control Loop Tosca

4.3.2: Client User Interface

4.4 Other Considerations

4.4.1 Upgrade

4.2.2: Policy Participant Agent

4.2.4: DCAE Participant Agent

4.2.5: Kubernetes Participant Agent

4.3: Client Side

4.3.1: Client SDK: Composition of Control Loop Tosca

4.3.2: Client User Interface

4.4 Other Considerations

4.4.1 Upgrade

4.4.2 Scalability

5: Goals

5.1: MVP

5.2: ControlLoop in Tosca LCM Istanbul Jiras