Skip to end of metadata
Go to start of metadata

Control Loop Operational Policies are used to specify what policy(s) should be executed in response to a DCAE generated Control Loop Event. These policies are built in the CLAMP GUI environment during design time. The language used to express these policies is Policy YAML language and there is a Java SDK that can be used to compile and parse these abstract policies.

Control Loop Policy YAML Specification

Link to Gerrit Repo for Policy YAML SDK


Example Operational Policy for vFirewall Use Case
controlLoop:

  version: 2.0.0
  controlLoopName: ControlLoop-vFirewall-d0a1dfc6-94f5-4fd4-a5b5-4630b438850a
  services:
    - serviceInvariantUUID: 5cfe6f4a-41bc-4247-8674-ebd4b98e35cc
      serviceUUID: 0f40bba5-986e-4b3c-803f-ddd1b7b25f24
      serviceName: 57e66ea7-0ed6-45c7-970f
  trigger_policy: unique-policy-id-1-modifyConfig
  timeout: 1200


policies:
  - id: unique-policy-id-1-modifyConfig
    name: modify packet gen config
    description:
    actor: APPC
    recipe: ModifyConfig
    target:
      resourceID: Eace933104d443b496b8.nodes.heat.vpg
	  type: VNF	
    retry: 0
    timeout: 300
    success: final_success
    failure: final_failure
    failure_timeout: final_failure_timeout
    failure_retries: final_failure_retries
    failure_exception: final_failure_exception
    failure_guard: final_failure_guard

Example Operational Policy for vDNS Use Case
controlLoop:
  version: 2.0.0
  controlLoopName: ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3
  services: 
    - serviceName: d4738992-6497-4dca-9db9
      serviceInvariantUUID: dc112d6e-7e73-4777-9c6f-1a7fb5fd1b6f
      serviceUUID: 2eea06c6-e1d3-4c3a-b9c4-478c506eeedf
  trigger_policy: unique-policy-id-1-scale-up
  timeout: 1200

policies:
  - id: unique-policy-id-1-scale-up
    name: Create a new VF Module
    description:
    actor: MSO
    recipe: VF Module Create
    target:
      type: VNF
    retry: 0
    timeout: 1200
    success: final_success
    failure: final_failure
    failure_timeout: final_failure_timeout
    failure_retries: final_failure_retries
    failure_exception: final_failure_exception
    failure_guard: final_failure_guard
Example Operational Policy for VOLTE Use Case
controlLoop:

  version: 2.0.0
  controlLoopName: ControlLoop-VOLTE-2179b738-fd36-4843-a71a-a8c24c70c55b
  trigger_policy: unique-policy-id-1-restart
  timeout: 3600

policies:

  - id: unique-policy-id-1-restart
    name: Restart the VM
    description:
    actor: VFC
    recipe: Restart
    target:
      type: VM
    retry: 3
    timeout: 1200
    success: final_success
    failure: final_failure
    failure_timeout: final_failure_timeout
    failure_retries: final_failure_retries
    failure_exception: final_failure_exception
    failure_guard: final_failure_guard
Example Operational Policy for vCPE Use Case
controlLoop:
  version: 2.0.0
  controlLoopName: ControlLoop-vCPE-48f0c2c3-a172-4192-9ae3-052274181b6e
  trigger_policy: unique-policy-id-1-restart
  timeout: 3600

policies:

  - id: unique-policy-id-1-restart
    name: Restart the VM
    description:
    actor: APPC
    recipe: Restart
    target:
      type: VM
    retry: 3
    timeout: 1200
    success: final_success
    failure: final_failure
    failure_timeout: final_failure_timeout
    failure_retries: final_failure_retries
    failure_exception: final_failure_exception
    failure_guard: final_failure_guard
Example Open Loop Operational Policy
controlLoop:
  version: 2.0.0
  controlLoopName: ControlLoop-Open-fac4ae3d-c3f5-4bab-8e54-0a8581ede132
  trigger_policy: final_openloop
  timeout: 0

policies:


This is a more elaborate example of how an Operations/Service Designer could put together an Control Loop Operational Policy that can fine tune the service/resources. That can also take multiple actions based on success/failure of previous actions. As well as show example of a payload.

Example Operational Policy that shows more functionality.
controlLoop:
  version: 2.0.0
  controlLoopName: ControlLoop-GENERIC-64cdc9fa-6601-4989-9de7-8f47134aa043
  #
  # Example of how someone can fine-grain this
  # policy for a specific service and/or resources
  # contained within the service.
  #
  services: 
    - serviceName: vFooService

  resources: 
    - resourceName: vVNF1
      resourceType: VFC
    - resourceName: vVNF2
      resourceType: VFC
    - resourceName: vVNF3
      resourceType: VFC
    - resourceName: vVNF4
      resourceType: VFC

  trigger_policy: unique-policy-id-1-restart
  timeout: 1200
  #
  # Example of case where an abatement isn't possible
  # from DCAE to Policy. So Policy should NOT expect
  # 
  abatement: false

policies:

  - id: unique-policy-id-1-restart
    name: Restart Policy
    description:
    actor: APPC
    recipe: Restart
    target:
      type: VM
    retry: 2
    timeout: 300
    success: unique-policy-id-1-healthdiagnostic
    failure: unique-policy-id-2-rebuild
    failure_timeout: unique-policy-id-2-rebuild
    failure_retries: unique-policy-id-2-rebuild
    failure_exception: final_failure_exception
    failure_guard: unique-policy-id-2-rebuild
  

  - id: unique-policy-id-2-rebuild
    name: Rebuild Policy
    description:
    actor: APPC
    recipe: Rebuild
    target:
      type: VM 
    retry: 0
    timeout: 600
    success: unique-policy-id-2-healthdiagnostic
    failure: unique-policy-id-3-migrate
    failure_timeout: unique-policy-id-3-migrate
    failure_retries: unique-policy-id-3-migrate
    failure_exception: final_failure_exception
    failure_guard: unique-policy-id-3-migrate

  - id: unique-policy-id-3-migrate
    name: Migrate Policy
    description:
    actor: APPC
    recipe: Migrate
    target: 
      type: VM
    retry: 0
    timeout: 600
    success: final_success
    failure: final_failure
    failure_timeout: final_failure_timeout
    failure_retries: final_failure_retries
    failure_exception: final_failure_exception
    failure_guard: final_failure_guard

  - id: unique-policy-id-1-healthdiagnostic
    name: Do A Health Diagnostic
    description:
    actor: APPC
    recipe: health-diagnostic
    # Example of a payload
    payload: 
      health-diagnostic-code: HC01234
      health-diagnostic-code-parameters: "{\"Junk\":\"--version\",\"Junk2\":\"--help\"}"
    target: 
      type: VM 
    retry: 0
    timeout: 600
    success: final_success
    failure: unique-policy-id-2-rebuild
    failure_timeout: unique-policy-id-2-rebuild
    failure_retries: unique-policy-id-2-rebuild
    failure_exception: final_failure_exception
    failure_guard: unique-policy-id-2-rebuild


  - id: unique-policy-id-2-healthdiagnostic
    name: Do Health Diagnostic
    description:
    actor: APPC
    recipe: health-diagnostic
    payload: 
      health-diagnostic-code: HC01234
      health-diagnostic-code-parameters: "{\"Junk\":\"--version\",\"Junk2\":\"--help\"}" 
    target:
      type: VM
    retry: 0
    timeout: 600
    success: final_success
    failure: final_failure
    failure_timeout: final_failure_timeout
    failure_retries: final_failure_retries
    failure_exception: final_failure_exception
    failure_guard: final_failure_guard


Control Loop Policy Notifications

While executing a Control Loop Policy, the policy platform will publish onto Dmaap a series of notification messages that notify how the policy is executing. This allows monitoring/auditing of the control loops to occur.

Notification Message Format

FieldRequiredSuppliedExample
version
YesThe version of the Control Loop event message. Should be '1.0.2'
closedLoopControlName
Yes

This is the unique ID for the Control Loop. It is created by the CLAMP platform during Control Loop design.

The DCAE Micro service that publishes this event structure MUST include this ID.

The Policy will copy this ID from the Control Loop Event.


requestID
Yes

For the control loop, when an instance of the Control Loop occurs, this unique ID must be created. The same ID

must be forwarded for both the ONSET and the ABATED control loop messages.

The Policy will copy this ID from the Control Loop Event.


closedLoopEventClient
No

For monitoring/logging/auditing purposes, if there is an instance ID of the DCAE micro service this field should be populated with it.

The Policy will copy this ID from the Control Loop Event


policyVersion
YesThe version of the Policy.
policyName
YesThe name of the Policy.
policyScope
YesThe scope of the Policy.
target_type
YesThe type of the target: VM or VNF. Future PNF(?)
target
YesThis is the name of the field within the A&AI sub-tag that indicates the actual entity Node details. There should be a matching node field within the A&AI subtag holding this value.
AAI
YesContains the A&AI Node-Attribute list.
notification
Yes

What the notification message type is. Must be one of these values:

ACTIVE

REJECTED

OPERATION

OPERATION: SUCCESS

OPERATION: FAILED

FINAL: FAILURE

FINAL: SUCCESS

FINAL: OPENLOOP


message
NoMore descriptive information regarding the notification.
notificationTime
YesUTC Time when the notification occurred.
OPS_CL_Timer
YesThe overall timeout for the Control Loop. This should be pulled from the Operational Policy controlloop/timeout section. Publishes so a 3rd party monitoring system can track the time for the control loop.
history
Yes - if the notification is FINAL: *Contains the history of operations performed via this Control Loop along with resulting success/failure and message codes.


Example Message

Notification Message Flow


Control Loop Event Messages

The control loop event messages are published by DCAE to Policy to indicate an occurrence of an event for a VM/VNF.

FieldRequiredDescription
version
YesThe version of the Control Loop event message. Should be '1.0.2'
closedLoopControlName
Yes

This is the unique ID for the Control Loop. It is created by the CLAMP platform during Control Loop design.

The DCAE Micro service that publishes this event structure MUST include this ID.

requestID
Yes

For the control loop, when an instance of the Control Loop occurs, this unique ID must be created. The same ID

must be forwarded for both the ONSET and the ABATED control loop messages.

closedLoopEventStatus
YesThis is the status of the closedLoopControlName/requestID pair. It can either ONSET or ABATED.
closedLoopAlarmStart
YesWhen the alarm was first detected.
closedLoopAlarmEnd
Yes - only for ABATEDWhen the alarm was cleared. This field need only be present in the ABATED message.
closedLoopEventClient
NoFor monitoring/logging/auditing purposes, if there is an instance ID of the DCAE micro service this field should be populated with it.
policyVersion

The version of the Policy driving the DCAE Micro service. Should be a part of the configuration policy setup by CLAMP and passed by DCAE controller
policyName

The name of the Policy driving the DCAE micro service. Should be a part of the configuration policy setup by CLAMP and passed by DCAE controller
policyScope

The scope of the Policy driving the DCAE micro service. Should be a part of the configuration policy setup by CLAMP and passed by DCAE controller
from
YesThe ONAP platform component publishing this message. If DCAE, then it should be 'DCAE'.
target_type
YesThe type of the target: VM or VNF. Future PNF(?)
target
YesThis is the name of the field within the A&AI sub-tag that indicates the actual entity Node details. There should be a matching node field within the A&AI subtag holding this value.
AAI
YesContains the A&AI Node-Attribute list.


Example

Example DCAE Event for vFirewall
{

                "closedLoopEventClient": "DCAE_INSTANCE_ID.dcae-tca",

                "policyVersion": "1.0.0.5",

                "policyName": "vLoadBalancer",

                "policyScope": "resource=SampleResource,service=SampleService,type=SampleType,closedLoopControlName=SampleClosedLoop",

                "target_type": "VM",

                "AAI": {

                                "vserver.vserver-name": "dfw1lb01lb01"

                },

                "closedLoopAlarmStart": 1484677482204798,

                "closedLoopEventStatus": "ONSET",

                "closedLoopControlName": "CL-DNS-LOW-TRAFFIC-SIG-d925ed73-8231-4d02-9545-db4e101f88f8",

                "version": "1.0.2",

                "target": "vserver.vserver-name",

                "requestID": "97964e10-686e-4790-8c45-bdfa61df770f",

                "from": "DCAE"

}
Example Dmaap Message Trace for vFirewall (DCAE->Policy->APPC)
### Dmaap Topic DCAE-CL-EVENT (DCAE publish to Policy)
{
  "closedLoopControlName": "CL-FRWL-LOW-TRAFFIC-SIG-d925ed73-8231-4d02-9545-db4e101f88f8",
  "closedLoopAlarmStart": 1463679805324,
  "closedLoopEventClient": "microservice.stringmatcher",
  "closedLoopEventStatus": "ONSET",
  "requestID": "664be3d2-6c12-4f4b-a3e7-c349acced200",
  "target_type": "VF",
  "target": "generic-vnf.vnf-id",
  "AAI": {
    "generic-vnf.vnf-id": "fw0001vm001fw001"
  },
  "from": "DCAE",
  "version": "1.0.2"
}

### Dmaap Topic POLICY-CL-MGT (Policy publish)
{
  "AAI": {
    "generic-vnf.vnf-id": "fw0001vm001fw001"
  },
  "closedLoopAlarmStart": 1463679805324,
  "closedLoopControlName": "CL-FRWL-LOW-TRAFFIC-SIG-d925ed73-8231-4d02-9545-db4e101f88f8",
  "version": "1.0.2",
  "requestID": "664be3d2-6c12-4f4b-a3e7-c349acced200",
  "closedLoopEventClient": "microservice.stringmatcher",
  "target_type": "VF",
  "target": "generic-vnf.vnf-id",
  "from": "policy",
  "policyScope": "service=test;resource=FRWL;type=configuration",
  "policyName": "FirewallDemo.EVENT",
  "policyVersion": "v0.0.1",
  "notification": "ACTIVE",
  "notificationTime": "2017-07-25 15:48:45.054000+00:00",
  "history": []
}


### Dmaap Topic POLICY-CL-MGT (Policy publish)
{
  "AAI": {
    "generic-vnf.vnf-id": "fw0001vm001fw001"
  },
  "closedLoopAlarmStart": 1463679805324,
  "closedLoopControlName": "CL-FRWL-LOW-TRAFFIC-SIG-d925ed73-8231-4d02-9545-db4e101f88f8",
  "version": "1.0.2",
  "requestID": "664be3d2-6c12-4f4b-a3e7-c349acced200",
  "closedLoopEventClient": "microservice.stringmatcher",
  "target_type": "VF",
  "target": "generic-vnf.vnf-id",
  "from": "policy",
  "policyScope": "service=test;resource=FRWL;type=configuration",
  "policyName": "FirewallDemo.EVENT.MANAGER",
  "policyVersion": "v0.0.1",
  "notification": "OPERATION",
  "notificationTime": "2017-07-25 15:48:45.299000+00:00",
  "history": []
}

### Dmaap Topic APPC-CL (Policy publish to APPC)
{
  "CommonHeader": {
    "TimeStamp": 1500997725298,
    "APIver": "1.01",
    "RequestID": "664be3d2-6c12-4f4b-a3e7-c349acced200",
    "RequestTrack": [],
    "Flags": []
  },
  "Action": "ModifyConfig",
  "Payload": {
    "generic-vnf.vnf-id": "fw0001vm001fw001",
    "pg-streams": {
      "pg-stream": [
        {
          "id": "fw_udp1",
          "is-enabled": "true"
        },
        {
          "id": "fw_udp2",
          "is-enabled": "true"
        },
        {
          "id": "fw_udp3",
          "is-enabled": "true"
        },
        {
          "id": "fw_udp4",
          "is-enabled": "true"
        },
        {
          "id": "fw_udp5",
          "is-enabled": "true"
        }
      ]
    }
  }
}


## Dmaap Topic APPC-CL (APPC publish back to Policy)
{
	"Status": {
		"Value": "ACCEPTED",
		"Code": "100"
	},
	"Payload": {
		"pg-streams": "{\\\"pg-streams\\\": {\\\"pg-stream\\\":[{\\\"id\\\":\\\"fw_udp1\\\", \\\"is-enabled\\\":\\\"true\\\"},{\\\"id\\\":\\\"fw_udp2\\\", \\\"is-enabled\\\":\\\"true\\\"},{\\\"id\\\":\\\"fw_udp3\\\", \\\"is-enabled\\\":\\\"true\\\"},{\\\"id\\\":\\\"fw_udp4\\\", \\\"is-enabled\\\":\\\"true\\\"},{\\\"id\\\":\\\"fw_udp5\\\", \\\"is-enabled\\\":\\\"true\\\"}]}}",
		"generic-vnf.vnf-id": "fw0001vm001fw001"
	},
	"CommonHeader": {
		"TimeStamp": "1493841850199",
		"APIver": "1.01",
		"RequestID": "664be3d2-6c12-4f4b-a3e7-c349acced200",
		"SubrequestID": null,
		"OriginatorID": null
	}
}


## Dmaap Topic APPC-CL (APPC publish back to Policy)
{
	"Status": {
		"Value": "SUCCESS",
		"Code": "400"
	},
	"Payload": {
		"pg-streams": "{\\\"pg-streams\\\": {\\\"pg-stream\\\":[{\\\"id\\\":\\\"fw_udp1\\\", \\\"is-enabled\\\":\\\"true\\\"},{\\\"id\\\":\\\"fw_udp2\\\", \\\"is-enabled\\\":\\\"true\\\"},{\\\"id\\\":\\\"fw_udp3\\\", \\\"is-enabled\\\":\\\"true\\\"},{\\\"id\\\":\\\"fw_udp4\\\", \\\"is-enabled\\\":\\\"true\\\"},{\\\"id\\\":\\\"fw_udp5\\\", \\\"is-enabled\\\":\\\"true\\\"}]}}",
		"generic-vnf.vnf-id": "fw0001vm001fw001"
	},
	"CommonHeader": {
		"TimeStamp": "1493841850199",
		"APIver": "1.01",
		"RequestID": "664be3d2-6c12-4f4b-a3e7-c349acced200",
		"SubrequestID": null,
		"OriginatorID": null
	}
}
### Dmaap Topic POLICY-CL-MGT (Policy publish)
{
  "AAI": {
    "generic-vnf.vnf-id": "fw0001vm001fw001"
  },
  "closedLoopAlarmStart": 1463679805324,
  "closedLoopControlName": "CL-FRWL-LOW-TRAFFIC-SIG-d925ed73-8231-4d02-9545-db4e101f88f8",
  "version": "1.0.2",
  "requestID": "664be3d2-6c12-4f4b-a3e7-c349acced200",
  "closedLoopEventClient": "microservice.stringmatcher",
  "target_type": "VF",
  "target": "generic-vnf.vnf-id",
  "from": "policy",
  "policyScope": "service=test;resource=FRWL;type=configuration",
  "policyName": "FirewallDemo.APPC.RESPONSE",
  "policyVersion": "v0.0.1",
  "notification": "OPERATION: SUCCESS",
  "message": "actor=APPC,operation=ModifyConfig,target=generic-vnf.vnf-id,subRequestId=null",
  "notificationTime": "2017-07-25 15:50:12.550000+00:00",
  "history": [
    {
      "actor": "APPC",
      "operation": "ModifyConfig",
      "target": "generic-vnf.vnf-id",
      "start": 1500997725298,
      "outcome": "SUCCESS",
      "message": "actor=APPC,operation=ModifyConfig,target=generic-vnf.vnf-id,subRequestId=null"
    }
  ]
}
### Dmaap Topic POLICY-CL-MGT (Policy publish)
{
  "AAI": {
    "generic-vnf.vnf-id": "fw0001vm001fw001"
  },
  "closedLoopAlarmStart": 1463679805324,
  "closedLoopControlName": "CL-FRWL-LOW-TRAFFIC-SIG-d925ed73-8231-4d02-9545-db4e101f88f8",
  "version": "1.0.2",
  "requestID": "664be3d2-6c12-4f4b-a3e7-c349acced200",
  "closedLoopEventClient": "microservice.stringmatcher",
  "target_type": "VF",
  "target": "generic-vnf.vnf-id",
  "from": "policy",
  "policyScope": "service=test;resource=FRWL;type=configuration",
  "policyName": "FirewallDemo.APPC.RESPONSE",
  "policyVersion": "v0.0.1",
  "notification": "FINAL: SUCCESS",
  "message": "actor=APPC,operation=ModifyConfig,target=generic-vnf.vnf-id,subRequestId=null",
  "notificationTime": "2017-07-25 15:50:12.550000+00:00",
  "history": [
    {
      "actor": "APPC",
      "operation": "ModifyConfig",
      "target": "generic-vnf.vnf-id",
      "start": 1500997725298,
      "outcome": "SUCCESS",
      "message": "actor=APPC,operation=ModifyConfig,target=generic-vnf.vnf-id,subRequestId=null"
    }
  ]
}
 





  • No labels

4 Comments

  1. Hi Pam,

    Thanks for your example and clarification.

    Is this the final version of the message which is going to be published to DMaaP and taken as the input of Policy?

    1. Yes, we'd like to keep this for R1. The seed code in both DCAE and Policy use this structure, we want to avoid unnecessary changes happening for R1 to be successful.

      Going forward, there are talks of replacing this with a version of the VES format. Which sounds simple, but does require work within the Policy Platform. And my experience in the past is it does seem to take a lot of meetings to ensure all parties are in agreement on the fields required. (smile)

  2. Hi Pam,

    Another question: About the closedLoopControlName and requestID, where do they come from?

    From the table above, I know that the closedLoopControlName is defined during the design phase, then how could we get it's value during the run time? Regarding the requestID, when is it generated and how do we get it?

    Regards,

    Guangrong

    1. closedLoopControlName is a unique ID generated by CLAMP during design of the Control Loop. There are no semantics to it, it should be unique. This is why your configuration policy for Holmes is important, because there needs to be a field in there with the closedLoopControlName in it. If you look back to the example here:

      DCAE Component Policy (for Control Loop) You can see that the DCAE team adds name/value pairs for some of the fields required in the Control Loop Event Object (i.e controlLoopControlName, policyName, policyVersion, policyScope). So they have that information available during runtime. Again, some of these fields are for monitoring/auditing the control loop.

      The requestID MUST be generated by Holmes when a new instance of the Control Loop occurs for a specific VNF/VM. Holmes should maintain state (not hard since you use Drools), for this instance because when the condition has been abated this unique requestID should be passed to policy in the ABATED message. This unique ID also tracks how the Control Loop is taken care of throughout the platform. So a monitoring/auditing application can keep track of which component did what when a condition occurred for a specific VNF instance.

      I hope to add a full message flow sometime soon which will help show this a bit more clearly.