Warning |
---|
This page is no longer updated or kept current. For Istanbul, please see the ONAP documentation For Jakarta, please see Defining Control Loops in TOSCA for CLAMP (Jakarta) |
The following TOSCA concepts are the fundamental concepts in a TOSCA Service Template for defining control loops.
The following TOSCA concepts are the fundamental concepts in a TOSCA Service Template for defining control loops.
The TOSCA concepts above may be declared in the TOSCA Service Template of a control loop. If the concepts already exist in the Design Time Catalogue or the Runtime Inventory, they may be omitted from a TOSCA service template that defines a control loop type.
...
The Yaml file that holds the Definition of TOSCA fundamental Control Loop Types is available in Github and is the canonical definition of the Control Loop concepts.
Warning |
---|
Updated for Istanbul to this point, the material below may or may not be correct. |
Property: Metadata defined in TOSCA that is associated with a Control Loop, a Control Loop Element, or a Participant.
TOSCA Property Type: The TOSCA defintion of the type of a property. A property can have a generic type such as string or integer or can have a user defined TOSCA data type.
TOSCA Property Value: The value of a Property Type. Property values are assigned at run time in CLAMP.
Common Property Type: Property Types that apply to all instances of a Control Loop Type.
Common Property Value: The value of a Property Type. It is assigned at run time once for all instances of a Control Loop Type.
Instance Specific Property Type: Property Types that apply to an individual instance of a Control Loop Type.
Instance Specific Property Value: The value of a Property Type that applies to an individual instance of a Control Loop Type. The value is assigned at run time for each control loop instance.
node_templates
which makes up the loop itself.
Applications can be a DCAE microservice, an operational policy, or any other application as long as it can be modeled, and the targeted ecosystem to has a participant client waiting for the event distributions from CLAMP via DMaaP Message Router.
1. Control Loop TOSCA file definition
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 | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
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 |
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.
Warning |
---|
The below example doesn't explicitly include any order, ordering of control loop execution is to be considered in the future which likely would lead to changes to this |
1.2 TOSCA Concepts for Control Loop Elements delivered by ONAP
1.2.1 Policy Control Loop Element
The Policy Participant runs Policy Control Loop Elements. Each Policy Control Loop Element manages the deployment of the policy specified in the Policy Control Loop Element definition. The Yaml file that holds the Policy Control Loop Element Type definition is available in Github and is the canonical definition of the Policy Control Loop Element type. For a description of the Policy Control Loop Element and Policy Participant, please see The CLAMP Policy Framework Participant page.
1.2.2 HTTP Control Loop Element
The HTTP Participant runs HTTP Control Loop Elements. Each HTTP Control Loop Element manages REST communication towards a REST endpoint using the REST calls a user has specified in the configuration of the HTTP Control Loop Element. The Yaml file that holds the HTTP Control Loop Element Type definition is available in Github and is the canonical definition of the HTTP Control Loop Element type. For a description of the HTTP Control Loop Element and HTTP Participant, please see The CLAMP HTTP Participant page.
1.2.3 Kubernetes Control Loop Element
The Kubernetes Participant runs Kubernetes Control Loop Elements. Each Kubernetes Control Loop Element manages a Kubernetes microservice using Helm. The user defines the Helm chart for the Kubernetes microservice as well as other properties that the microservice requires in order to execute. The Yaml file that holds the Kubernetes Control Loop Element Type defintion is available in Github and is the canonical definition of the Kubernetes Control Loop Element type. For a description of the Kubernetes Control Loop Element and Kubernetes Participant, please see The CLAMP Kubernetes Participant page.
2 Common and Instance Specific Properties
Properties are used to define the configuration for Control Loops and Control Loop Elements. At design time, the types, constraints, and descriptions of the properties are specified. The values for properties are specified in the CLAMP GUI at runtime. TOSCA provides support for defining properties, see Section 3.6.10: TOSCA Property Definition in the TOSCA documentation.
2.1 Terminology for Properties
Property: Metadata defined in TOSCA that is associated with a Control Loop, a Control Loop Element, or a Participant.
TOSCA Property Type: The TOSCA definition of the type of a property. A property can have a generic type such as string or integer or can have a user defined TOSCA data type.
TOSCA Property Value: The value of a Property Type. Property values are assigned at run time in CLAMP.
Common Property Type: Property Types that apply to all instances of a Control Loop Type.
Common Property Value: The value of a Property Type. It is assigned at run time once for all instances of a Control Loop Type.
Instance Specific Property Type: Property Types that apply to an individual instance of a Control Loop Type.
Instance Specific Property Value: The value of a Property Type that applies to an individual instance of a Control Loop Type. The value is assigned at run time for each control loop instance.
Code Block | ||
---|---|---|
| ||
startPhase:
type: integer
required: false
constraints:
- greater-or-equal: 0
description: A value indicating the start phase in which this control loop element will be started, the
first start phase is zero. Control Loop Elements are started in their start_phase order and stopped
in reverse start phase order. Control Loop Elements with the same start phase are started and
stopped simultaneously
metadata:
common: true
|
The "common: true" value in the metadata of the startPhase property identifies that property as being a common property. This property will be set on the CLAMP GUI during control loop commissioning.
Code Block | ||
---|---|---|
| ||
# Definition that omits the common flag metadata
chart:
type: org.onap.datatypes.policy.clamp.controlloop.kubernetesControlLoopElement.Chart
typeVersion: 1.0.0
description: The helm chart for the microservice
required: true
# Definition that specifies the common flag metadata
chart:
type: org.onap.datatypes.policy.clamp.controlloop.kubernetesControlLoopElement.Chart
typeVersion: 1.0.0
description: The helm chart for the microservice
required: true
metadata:
common: false |
The "common: false" value in the metadata of the chart property identifies that property as being an instance specific property. This property will be set on the CLAMP GUI during control loop instantiation.
3. Writing a Control Loop Type Definition
The TOSCA definition of a control loop contains a TOSCA Node Template for the control loop itself, which contains TOSCA Node Templates for each Control Loop Element that makes up the Control Loop.
draw.io Diagram | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
To create a control loop, a user creates a TOSCA Topology Template. In the Topology Template, the user creates a TOSCA Node Template for each Control Loop Element that will be in the Control Loop Definition. Finally, the user creates the Node Template that defines the Control Loop itself, and references the Control Loop Element definitions that make up the Control Loop Definition.
3.1 The Gentle Guidance Control Loop
The best way to explain how to create a Control Loop Definition is by example.
draw.io Diagram | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
The example Gentle Guidance control loop is illustrated in the diagram above. The domain logic for the control loop is implemented in a microservice running in Kubernetes, a policy, and some configuration that is passed to the microservice over a REST endpoint. We want to manage the life cycle of the domain logic for our Gentle Guidance control loop using our TOSCA based Control Loop Life Cycle Management approach. To do this we create four Control Loop Element definitions, one for the Kubernetes microservice, one for the policy and one or the REST configuration.
3.2 The TOSCA Control Loop Definition
We use a TOSCA Topology Template to specify a Control Loop definition and the definitions of its Control Loop Elements. Optionally, we can specify default parameter values in the TOSCA Topology Template. The actual values of Control Loop common and instance specific parameters are set at run time in the CLAMP GUI.
In the case of the Gentle Guidance control loop, we define a Control Loop Element Node Template for each part of the domain logic we are managing. We then define the Control Loop Node Template for the control loop itself.
The code fragment below shows the TOSCA Topology Template for the Gentle Guidance domain when no parameters are defined. Please refer to the Yaml file in Github for the definitive Yaml specification.
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
tosca_definitions_version: tosca_simple_yaml_1_3
topology_template:
node_templates:
org.onap.domain.gentleguidance.KubernetesControlLoopElementDefinition:
version: 1.0.0
type: org.onap.policy.clamp.controlloop.KubernetesControlLoopElement
type_version: 1.0.1
description: Control loop element for the Gentle Guidance Kubernetes Microservice
org.onap.domain.gentleguidance.RestControlLoopElementDefinition:
version: 1.0.0
type: org.onap.policy.clamp.controlloop.HttpControlLoopElement
type_version: 1.0.1
description: Control loop element for the Gentle Guidance Microservice REST configuration
org.onap.domain.gentleguidance.PolicyControlLoopElementDefinition:
version: 1.0.0
type: | ||||||||
Code Block | ||||||||
| ||||||||
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:PolicyControlLoopElement type_version: 1.0.1 derived_from: tosca.nodetypes.Root properties: provider: type: string requred: false description: Control loop element for the Gentle Guidance Operational Policy blueprint org.onap.domain.gentleguidance.ControlLoopDefinition: version: 1.0.0 type: org.onap.policy.clamp.controlloop.ControlLoopElement:ControlLoop type_version: 1.0.1 derived_from: tosca.nodetypes.Root description: Control loop definition for the Gentle Guidance domain properties: elements: provider:- org.onap.domain.gentleguidance.KubernetesControlLoopElementDefinition:1.0.0 type: string- org.onap.domain.gentleguidance.RestControlLoopElementDefinition:1.0.0 - org.onap.domain.gentleguidance.PolicyControlLoopElementDefinition:1.0.0 |
The code fragment below shows the TOSCA Topology Template for the Gentle Guidance domain when the default values of parameters are defined. Please refer to the Yaml file in Github for the definitive Yaml specification.
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
tosca_definitions_version: tosca_simple_yaml_1_3 topology_template: node_templates: org.onap.domain.gentleguidance.KubernetesControlLoopElementDefinition: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 requredversion: false1.0.0 elements: type: org.onap.policy.clamp.controlloop.KubernetesControlLoopElement type_version: list 1.0.1 requireddescription: true Control loop element for the Gentle Guidance Kubernetes entry_schema:Microservice properties: type: onap.datatypes.ToscaConceptIdentifier org.onap.policy.clamp.controlloop.DCAEMicroserviceControlLoopElement: provider: Ericsson version: 1.0.1 derived_fromparticipantType: org.onap.policy.clamp.controlloop.ControlLoopElement.controlloop.participant.Kubernetes:1.0.0 properties: dcae_blueprint_id:startPhase: 2 typeuninitializedToPassiveTimeout: onap.datatypes.ToscaConceptIdentifier180 requredchart: true org.onap.policy.clamp.controlloop.PolicyTypeControlLoopElement: version: 1.0.1 derived_fromchartId: org.onap.policy.clamp.controlloop.ControlLoopElementGentleGuidance:1.0.0 properties: policy_type_id:releaseName: Istanbul type namespace: org.onap.policy.datatypescontrolloop.ToscaConceptIdentifiergentleguidance requred: true org.onap.policydomain.clampgentleguidance.controlloop.CDSControlLoopElementRestControlLoopElementDefinition: version: 1.0.10 derived_fromtype: org.onap.policy.clamp.controlloop.ControlLoopElement properties:.controlloop.HttpControlLoopElement cdstype_blueprint_id:version: 1.0.1 typedescription: onap.datatypes.ToscaConceptIdentifier requred: true topology_template: node_templates: org.onap.dcae.controlloop.DCAEMicroserviceControlLoopParticipant: Control loop element for the Gentle Guidance Microservice REST configuration properties: versionprovider: 2.3.4Ericsson type participantType: org.onap.policy.clamp.controlloop.Participant .controlloop.participant.Http:1.0.0 type_versionstartPhase: 1.0.1 baseUrl: https://10.10.10.10:12345/gentleguidancemicroservice descriptionhttpHeaders: Participant for DCAE microservices properties: "Content-Type": "application/json" provider"Accept": ONAP"application/json" org.onap.policy.controlloop.MonitoringPolicyControlLoopParticipant: configurationEntities: version: 2.3.1 type: org.onap.policy.clampcontrolloop.controlloop.Participant type_version: gentleguidance.setGentleGuidanceConfig:1.0.10: description: Participant for DCAE microservices properties:configurationEntityId: org.onap.policy.controlloop.gentleguidance.setGentleGuidanceConfig:1.0.0 provider: ONAP org.onap.policy.controlloop.OperationalPolicyControlLoopParticipantrestSequence: version: 3.2.1 - typerestRequestId: org.onap.policy.clamp.controlloop.Participant.controlloop.gentleguidance.setGentleGuidanceConfig.CreateGentle:1.0.0 type_version: 1.0.1 descriptionhttpMethd: ParticipantPOST for DCAE microservices properties: path: "gentle/create" provider: ONAP org.onap.ccsdk.cds.controlloop.CdsControlLoopParticipant: version: 2.2.1 body: type: org.onap.policy.clamp.controlloop.Participant type_versiongentleLevel: 1.0.1veryGentle description: Participant for DCAE microservices propertiesgentleType: softAndFurry provider: ONAP org.onap.domain.pmsh.PMSH_DCAEMicroservice: expectedResponse: 200 version: 1.2.3 type- restRequestId: org.onap.policy.clamp.controlloop.DCAEMicroserviceControlLoopElement controlloop.gentleguidance.setGentleGuidanceConfig.CreateGuidance:1.0.0 type_versionhttpMethd: 1.0.0 POST description: Control loop element for the DCAE microservice for Performance Management Subscription Handling path: "guidance/create" propertiesbody: provider: Ericsson participant_id: guidanceLevel: high name guidanceType: org.onap.dcae.controlloop.DCAEMicroserviceControlLoopParticipant subtle version expectedResponse: 2.3.4 200 dcae_blueprint_idorg.onap.policy.controlloop.gentleguidance.updateGentleGuidanceConfig:1.0.0: name configurationEntityId: org.onap.dcae.blueprints.PMSHBlueprint .policy.controlloop.gentleguidance.updateGentleGuidanceConfig:1.0.0 version: 1.0.0 org.onap.domain.pmsh.PMSH_MonitoringPolicyControlLoopElementrestSequence: version: 1.2.3 - typerestRequestId: org.onap.policy.clampcontrolloop.controlloop.PolicyTypeControlLoopElement type_version: gentleguidance.updateGentleGuidanceConfig.CreateGentle:1.0.0 description: Control loop element for the monitoring policy for Performance Management Subscription HandlinghttpMethd: PUT properties: provider: Ericsson participant_id:path: "gentle/update]" name: org.onap.policy.controlloop.PolicyControlLoopParticipant body: version: 2.3.1 policy_type_id: gentleLevel: robust namegentleType: onap.policies.monitoring.pm-subscription-handlerhardAndGritty version: 1.0.0 org.onap.domain.pmsh.PMSH_OperationalPolicyControlLoopElement: expectedResponse: 200 version: 1.2.3 - typerestRequestId: org.onap.policy.controlloop.clampgentleguidance.controlloop.PolicyTypeControlLoopElement type_version: updateGentleGuidanceConfig.CreateGuidance:1.0.0 description: Control loop element for the operational policy for Performance Management Subscription HandlinghttpMethd: PUT properties: providerpath: Ericsson"guidance/update" participant_id: body: name: org.onap.policy.controlloop.PolicyControlLoopParticipant versionguidanceLevel: 2.3.1low policy_type_id: guidanceType: terse name: onap.policies.operational.pm-subscription-handler versionexpectedResponse: 1.0.0200 org.onap.domain.pmsh.PMSH_CDS_ControlLoopElementgentleguidance.PolicyControlLoopElementDefinition: version: 1.20.30 type: org.onap.policy.clamp.controlloop.ControlLoopElementPolicyControlLoopElement type_version: 1.0.01 description: Control loop element for CDSthe forGentle PerformanceGuidance ManagementOperational Subscription HandlingPolicy properties: provider: Ericsson participant_Id: name: org.onap.ccsdk.cds.controlloop.CdsControlLoopParticipant provider: Ericsson versionparticipantType: 3.2.1org.onap.policy.controlloop.participant.Policy:1.0.0 cds_blueprint_id:startPhase: 0 namepolicyType: org.onap.ccsdk.cds.PMSHCdsBlueprint onap.policies.controlloop.operational.common.Apex:1.0.0 version: policyId: org.onap.domain.gentleguidance.policy.GentleGuidanceAssertive:1.0.0 org.onap.domain.pmshgentleguidance.PMSHControlLoopDefinitionControlLoopDefinition: version: 1.20.30 type: org.onap.policy.clamp.controlloop.ControlLoop type_version: 1.0.01 description: Control loop definition for Performancethe ManagementGentle SubscriptionGuidance Handlingdomain properties: provider: Ericsson Ericsson elements: - org.onap.domain.gentleguidance.KubernetesControlLoopElementDefinition:1.0.0 elements:- org.onap.domain.gentleguidance.RestControlLoopElementDefinition:1.0.0 - 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.2: Modelling from TOSCA to Commissioned Data in Run Time Inventory
org.onap.domain.gentleguidance.PolicyControlLoopElementDefinition:1.0.0
|
4. Creating Custom Control Loop Elements
Any organization can include their own component in the framework and use the framework and have the Policy Framework CLAMP manage the lifecycle of domain logic in their component as part of a Control Loop. To do this, a participant for the component must be developed that allows Control Loop Elements for that component to be run. To develop a participant, the participant must comply with the CLAMP Participants framework and in particular comply with The CLAMP Automation Composition Participant Protocol. The organization must also specify a new Control Loop Element type definition in TOSCA similar to those supplied in ONAP and described in Section 1.2. This Control Loop Element type tells the CLAMP Control Loop Lifecycle management that the Control Loop Element exists and can be included in control loops. It also specifies the properties that can be specified for the Control Loop Element.
An organization can supply the code for the Participant (for example as a Java jar file) and a TOSCA artifact with the Control Loop Element definition and it can be added to the platform. In future releases, support will be provided to include participants and their Control Loop Element definitions as packaged plugins that can be installed on the platform. draw.io Diagram