1 ECOMP Control Loop Policy v2.0.0
3 A control loop policy is a YAML specification for creating and chaining policies for ControlLoop.
5 1707 ECOMP Control Loop Policy Features:
7 * Backward compatible with 1610 ECOMP Control Loop Policy
8 * A single DCAE Closed Loop Event is the trigger for the overall Control Loop Policy.
9 * An overall timeout for the Control Loop Policy must be provided.
10 * An abatement flag indicating whether Policy will receive abatement event for the Control Loop could be provided.
11 * The Control Loop Policy can contain zero or more Operational Policies each chained together via outcomes of each policy.
12 * If there are zero Operational Policies, i.e. no automated action is to be taken, then the policy is an Open Loop policy.
13 * Operational policies can have target, retries and timeout's given to control how they are processed.
14 * Type and resourceID of the target could be provided to support the target in operational policies.
15 * Payload could be provided to support the recipe.
16 * Multiple actors along with their supported recipes can be specified in operational policies that Policy will interact with. The following table summarizes the supported actors and recipes.
18 | Actor | Recipe | Target | Payload |
19 | -------------|:---------------------------:| ---------| ------------:|
20 | APPC | Restart | VM | AICVServerSelfLink, AICIdentity |
21 | APPC | Rebuild | VM | AICVServerSelfLink, AICIdentity |
22 | APPC | Migrate | VM | AICVServerSelfLink, AICIdentity |
23 | APPC | ModifyConfig | VFC | generic-vnf.vnf-id |
24 | MSO | VF Module Create | VFC | optional |
25 | SDNO | health-diagnostic-type | VM | health-diagnostic-code, health-diagnostic-code-parameters |
26 | SDNO | health-diagnostic | VM | optional |
27 | SDNO | health-diagnostic-history | VM | optional |
28 | SDNO | health-diagnostic-commands | VM | optional |
29 | SDNO | health-diagnostic-aes | VM | optional |
30 | SDNR | Reset | PNF | optional |
31 | AOTS | checkMaintenanceWindow | VM | optional |
32 | AOTS | checkENodeBTicketHours | VM | timeWindow |
33 | AOTS | checkEquipmentStatus | VM | optional |
34 | AOTS | checkEimStatus | VM | optional |
38 This SDK helps build the YAML specification for 1707 ECOMP Control Loop Polices.
40 # Create Builder Object
42 To begin with, the ControlLoopPolicyBuilder.Factory class has static methods that one should use to begin building a Control Loop Policy. It will return a [ControlLoopPolicyBuilder object](src/main/java/com/att/ecomp/policy/controlloop/policy/builder/ControlLoopPolicyBuilder.java) that can then be used to continue to build and define the Control Loop Policy.
45 ControlLoopPolicyBuilder builder = ControlLoopPolicyBuilder.Factory.buildControlLoop(
46 UUID.randomUUID().toString(),
48 new Resource("vCTS", ResourceType.VF),
53 # Define the Trigger Policy
55 After the name of the Control Loop and the resource and services have been defined, the next step would be to define the Operation Policy that is first to respond to an incoming DCAE Closed Loop Event. Use the setTriggerPolicy() method to do so.
58 Policy triggerPolicy = builder.setTriggerPolicy(
60 "Upon getting the trigger event, restart the VM",
62 new Target(TargetType.VM),
69 # Set the Abatement Flag for the Control Loop
71 After the trigger policy, the name, the resource(s) and services of the Control Loop have been defined, the next optional step would be to set the abatement flag that indicates whether DCAE will send Policy the abatement event for this Control Loop. If the abatement is not explicitly set, it is assumed that Policy will not receive the abatement event. Use the setAbatement() method to do so.
74 builder = builder.setAbatement(false);
77 # Chain Operational Policies Together Using Operational Results
79 Operational Policies are chained together using the results of each Operational Policy. The results are defined in [PolicyResult.java](src/main/java/com/att/ecomp/policy/controlloop/policy/PolicyResult.java). To create an Operational Policy that is tied to the result of another, use the
80 setPolicyForPolicyResult() method.
83 Policy onRestartFailurePolicy = builder.setPolicyForPolicyResult(
85 "If the restart fails, rebuild it.",
87 new Target(TargetType.VM),
94 PolicyResult.FAILURE_RETRIES,
95 PolicyResult.FAILURE_TIMEOUT,
96 PolicyResult.FAILURE_GUARD);
99 An Operational Policy MUST have place to go for every one of its results. By default, each result type goes to a Final Result. Optionally, using the setPolicyForPolicyResult() method is what allows the chaining of policies. Be aware of creating loops and set the overall Control Loop timeout to reasonable value. All paths MUST lead to a Final Result.
103 # Build the YAML Specification
105 When finished defining the Policies, build the specification and analyze the [Results.java](src/main/java/com/att/ecomp/policy/controlloop/policy/builder/Results.java)
108 Results results = builder.buildSpecification();
109 if (results.isValid()) {
110 System.out.println(results.getSpecification());
112 System.err.println("Builder failed");
113 for (Message message : results.getMessages()) {
114 System.err.println(message.getMessage());
121 Sample code is available in this project: https://codecloud.web.att.com/projects/ST_POLICY/repos/com.att.ecomp.policy.controlloop.sample/browse
125 # Use the YAML Specification to call the Create Policy API
127 Now that you have a valid YAML specification, call the createPolicy API via the ECOMP Policy Platform API.
132 The YAML specification has 2 sections to it: [controlLoop](#controlloop-object) and [policies](#policies-array). The [controlLoop section](#controlloop-object) section is simply a header defining the Control Loop Policy, what services its for, which resource its for, or if its for a pnf, the overall timeout, the abatement flag, and which Operational Policy is triggered upon receiving the event. The [policies section](#policies-array) is simply an array of [Policy Objects](#policy-object).
134 ## controlLoop Object
136 | Field Name | Type | Required | Description |
137 | ------------- |:-------------:| -----------| ------------:|
138 | controlLoopName | string | required | Unique ID for the control Loop |
139 | version | string | required | Value for this release if 1.0.0 |
140 | services | array of [service](#service-object) objects | optional | Zero or more services associated with this Control Loop |
141 | resources | array of [resource](#resource-object) object | required (If NOT a pnf control loop) | The resource's associated with this Control Loop. |
142 | pnf | [pnf](#pnf-object) object | required (If NOT a resource control loop) | The physical network function associated with this Control Loop. |
143 | trigger_policy | string | required | Either this is the ID of an Operation Policy (see policy object), or "Final_OpenLoop" indicating an Open Loop |
144 | timeout | int | required | This is the overall timeout for the Control Loop Policy. It can be 0 for an Open Loop, but otherwise should total more than the timeouts specified in any Operational Policies |
145 | abatement | boolean | optional | This is an abatement flag indicating if DCAE will send abatement event to Policy for this Control Loop |
149 This object was derived via ASDC Catalog API and ASDC Data Dictionary (POC) in an attempt to use common naming conventions.
151 | Field Name | Type | Required | Description |
152 | ------------- |:-------------:| -----------| ------------:|
153 | resourceInvariantUUID | string - UUID | optional | via ASDC, the unique ID for the resource version |
154 | resourceName | string | required if NO resourceUUID available | Name of the resource, ideally from ASDC catalog. But if not available, use well-known name. |
155 | resourceType | string | optional | Use values defined by ASDC: VF, VFC, VL, CP. |
156 | resourceUUID | string - UUID | required IF available, else populate resourceName | Unique ID for the resource as assigned via ASDC.
157 | resourceVersion | string | optional | string version of the resource via ASDC catalog
162 This object was derived via ASDC Catalog API and ASDC Data Dictionary (POC) in an attempt to use common naming conventions.
164 | Field Name | Type | Required | Description |
165 | ---------------:| -------------:| ----------:| ------------:|
166 | serviceInvariantUUID | string - UUID | optional | via ASDC catalog, the unique ID for the service version |
167 | serviceName | string | required if NO serviceUUID available | Name of the service, ideally from ASDC catalog. But if not available, use well-known name. |
168 | serviceUUID | string - UUID | required IF available, else populate serviceName | Unique ID fort he service as assigned via ASDC
169 | serviceVersion | string | optional | string version of the service via ASDC catalog
174 This object is used for a physical network function. In the case of 1707, eNodeB is the use case supported. Expect this object to change in the future when ECOMP Policy fully integrates with A&AI.
176 | Field Name | Type | Required | Description |
177 | ------------- |:-------------:| -----------| ------------:|
178 | PNFName | string | required | Name of the PNF. Should be supplied via A&AI. If not available use a well-known name. |
179 | PNFType | string | optional | Type of PNF if available. |
184 The policies section is an array of [Policy objects](#policy-object).
188 This is an Operation Policy. It is used to instruct an actor (eg. APPC) to invoke a recipe (eg. "Restart") on a target entity (eg. a "VM"). For 1707, there are 5 actors: APPC, MSO, SDNO, SDNR and AOTS. An operation is simply defined as performing a recipe (or operation) on an actor.
190 | Field Name | Type | Required | Description |
191 | ------------- |:-------------:| -----------| ------------:|
192 | id | string | required | Unique ID for the policy.
193 | name | string | required | Policy name |
194 | description | string | optional | Policy description |
195 | actor | string | required | Name of the actor for this operation: Example: APPC |
196 | recipe | string | required | Name of recipe to be performed. Example "Restart" |
197 | target | [target](#target-object) object | required | Entity being targeted. Example: VM |
198 | timeout | int | required | Timeout for the actor to perform the recipe. |
199 | retry | int | optional | Optional number of retries for ECOMP Policy to invoke the recipe on the actor. |
200 | success | string | required | By default, this value should be FINAL_SUCCESS. Otherwise this can be the ID of the operational Policy (included in this specification) to invoke upon successfully completing the recipe on the actor.
201 | failure | string | required | By default, this value should be FINAL_FAILURE. Otherwise this can be the ID of the operational Policy (included in this specification) to invoke upon failure to perform the operation. |
202 | failure_exception | string | required | By default, this value should be FINAL_FAILURE_EXCEPTION. Otherwise this can be the ID of an Operational Policy (included in this specification) to invoke upon an exception occurring while attempting to perform the operation. |
203 | failure_retries | string | required | By default, this value should be the FINAL_FAILURE_RETRIES. Otherwise this can be the ID of an Operational Policy (included in this specification) to invoke upon maxing out on retries while attempting to perform the operation. |
204 | failure_timeout | string | required | By default, this value should be FINAL_FAILURE_TIMEOUT. Otherwise this can be the ID of the operational Policy (included in this specification) to invoke upon a timeout occuring while performing an operation. |
205 | failure_guard | string | required | By default, this value should be FINAL_FAILURE_GUARD. Otherwise this can be the ID of the operational Policy (included in this specification) to invoke upon Guard denies this operation. |
207 Every Operational Policy MUST have a place to go for every possible result (success, failure, failure_retries, failure_timeout, failure_exception, failure_guard). By default, all the results are final results.
211 This object is used for defining a target entity of a recipe.
213 | Field Name | Type | Required | Description |
214 | ------------- |:-------------:| -----------| ------------:|
215 | type | enums of VM, PNF and VNC | required | Type of the target. |
216 | resourceID | string | optional | Resource ID of the target. Should be supplied via ASDC Catalog. |
219 ## Examples of YAML Control Loops for 1707
221 [1707-vUSP](src/test/resources/v2.0.0/policy_vUSP_1707.yaml)
222 [1707-eNodeB-Ericsson](src/test/resources/v2.0.0/policy_eNodeB_Ericsson_1707.yaml)
223 [1707-eNodeB-ALU](src/test/resources/v2.0.0/policy_eNodeB_ALU_1707.yaml)
224 [OpenECOMP-vFirewall](src/test/resources/v2.0.0/policy_OpenECOMP_demo_vFirewall.yaml)
225 [OpenECOMP-vDNS](src/test/resources/v2.0.0/policy_OpenECOMP_demo_vDNS.yaml)
231 controlLoopName: ControlLoop-vUSP-vCTS-cbed919f-2212-4ef7-8051-fe6308da1bda
245 trigger_policy: unique-policy-id-1-restart
250 - id: unique-policy-id-1-restart
259 success: unique-policy-id-1-healthdiagnostic
260 failure: unique-policy-id-2-rebuild
261 failure_timeout: unique-policy-id-2-rebuild
262 failure_retries: unique-policy-id-2-rebuild
263 failure_exception: final_failure_exception
264 failure_guard: unique-policy-id-2-rebuild
266 - id: unique-policy-id-2-rebuild
275 success: unique-policy-id-2-healthdiagnostic
276 failure: unique-policy-id-3-migrate
277 failure_timeout: unique-policy-id-3-migrate
278 failure_retries: unique-policy-id-3-migrate
279 failure_exception: final_failure_exception
280 failure_guard: unique-policy-id-3-migrate
282 - id: unique-policy-id-3-migrate
291 success: final_success
292 failure: final_failure
293 failure_timeout: final_failure_timeout
294 failure_retries: final_failure_retries
295 failure_exception: final_failure_exception
296 failure_guard: final_failure_guard
298 - id: unique-policy-id-1-healthdiagnostic
299 name: Do SDNO Health Diagnostic
302 recipe: health-diagnostic
304 health-diagnostic-code: HC99
305 health-diagnostic-code-parameters: "{\"Junk\":\"--version\",\"Junk2\":\"--help\"}"
310 success: final_success
311 failure: unique-policy-id-2-rebuild
312 failure_timeout: unique-policy-id-2-rebuild
313 failure_retries: unique-policy-id-2-rebuild
314 failure_exception: final_failure_exception
315 failure_guard: unique-policy-id-2-rebuild
317 - id: unique-policy-id-2-healthdiagnostic
318 name: Do SDNO Health Diagnostic
321 recipe: health-diagnostic
323 health-diagnostic-code: HC99
324 health-diagnostic-code-parameters: "{\"Junk\":\"--version\",\"Junk2\":\"--help\"}"
329 success: final_success
330 failure: final_failure
331 failure_timeout: final_failure_timeout
332 failure_retries: final_failure_retries
333 failure_exception: final_failure_exception
334 failure_guard: final_failure_guard
337 ### 1707 eNodeB Ericsson
341 controlLoopName: ControlLoop-eNodeB-Ericsson-0732e76a-4228-42d1-8185-972510be388c
345 PNFName: eNodeB.Ericsson
346 trigger_policy: unique-policy-id-1-check-aots-ticket
350 - id: unique-policy-id-1-check-aots-ticket
352 description: Discard sleeping cell based on the new signature if it appears in recent CTS tickets
354 recipe: checkENodeBTicketHours
359 success: unique-policy-id-2-check-aots-cts
360 failure: final_failure
361 failure_timeout: final_failure_timeout
362 failure_retries: final_failure_retries
363 failure_exception: final_failure_exception
364 failure_guard: final_failure_guard
366 - id: unique-policy-id-2-check-aots-cts
367 name: Check AOTS CTS Equipment
368 description: Discard sleeping cell based on the new signature if it is not active in CTS equipment data
370 recipe: checkEquipmentStatus
374 success: unique-policy-id-3-check-aots-eim
375 failure: final_failure
376 failure_timeout: final_failure_timeout
377 failure_retries: final_failure_retries
378 failure_exception: final_failure_exception
379 failure_guard: final_failure_guard
381 - id: unique-policy-id-3-check-aots-eim
382 name: Check AOTS EIM_RT
383 description: Discard sleeping cell based on the new signature if it appears in EIM_RT data
385 recipe: checkEimStatus
388 success: unique-policy-id-3-check-aots-maintenance
389 failure: final_failure
390 failure_timeout: final_failure_timeout
391 failure_retries: final_failure_retries
392 failure_exception: final_failure_exception
393 failure_guard: final_failure_guard
395 - id: unique-policy-id-4-check-aots-maintenance
396 name: Check AOTS MAINTENANCE
397 description: Discard sleeping cell based on the new signature if it appears in Maintenance
399 recipe: checkMaintenanceWindow
402 success: unique-policy-id-5-sdnr-reset
403 failure: final_failure
404 failure_timeout: final_failure_timeout
405 failure_retries: final_failure_retries
406 failure_exception: final_failure_exception
407 failure_guard: final_failure_guard
409 - id: unique-policy-id-5-sdnr-reset
410 name: Have SDNR Reset
411 description: SDNR should now reset this sleeper
414 operationsAccumulateParams:
419 success: final_success
420 failure: final_failure
421 failure_timeout: final_failure_timeout
422 failure_retries: final_failure_retries
423 failure_exception: final_failure_exception
424 failure_guard: final_failure_guard
431 controlLoopName: ControlLoop-eNodeB-ALU-3ee91181-6f05-4cd3-8437-cad5f58653ca
436 trigger_policy: unique-policy-id-1-check-aots
440 - id: unique-policy-id-1-check-aots
442 description: Discard sleeping cell based on the new signature if it appears in recent CTS tickets
444 recipe: checkENodeBTicketHours
449 success: unique-policy-id-2-check-aots-cts
450 failure: final_failure
451 failure_timeout: final_failure_timeout
452 failure_retries: final_failure_retries
453 failure_exception: final_failure_exception
454 failure_guard: final_failure_guard
456 - id: unique-policy-id-2-check-aots-cts
457 name: Check AOTS CTS Equipment
458 description: Discard sleeping cell based on the new signature if it is not active in CTS equipment data
460 recipe: checkEquipmentStatus
463 success: unique-policy-id-3-check-aots-eim
464 failure: final_failure
465 failure_timeout: final_failure_timeout
466 failure_retries: final_failure_retries
467 failure_exception: final_failure_exception
468 failure_guard: final_failure_guard
470 - id: unique-policy-id-3-check-aots-eim
471 name: Check AOTS EIM_RT
472 description: Discard sleeping cell based on the new signature if it appears in EIM_RT data
474 recipe: checkEimStatus
477 success: unique-policy-id-4-sdnr-reset
478 failure: final_failure
479 failure_timeout: final_failure_timeout
480 failure_retries: final_failure_retries
481 failure_exception: final_failure_exception
482 failure_guard: final_failure_guard
484 - id: unique-policy-id-4-sdnr-reset
485 name: Have SDNR Reset
486 description: SDNR should now reset this sleeper
489 operationsAccumulateParams:
494 success: final_success
495 failure: final_failure
496 failure_timeout: final_failure_timeout
497 failure_retries: final_failure_retries
498 failure_exception: final_failure_exception
499 failure_guard: final_failure_guard
502 ### OpenECOMP vFirewall
506 controlLoopName: ControlLoop-vFirewall-d0a1dfc6-94f5-4fd4-a5b5-4630b438850a
508 - serviceInvariantUUID: 5cfe6f4a-41bc-4247-8674-ebd4b98e35cc
509 serviceUUID: 0f40bba5-986e-4b3c-803f-ddd1b7b25f24
510 serviceName: 57e66ea7-0ed6-45c7-970f
511 trigger_policy: unique-policy-id-1-modifyConfig
515 - id: unique-policy-id-1-modifyConfig
516 name: Change the Load Balancer
521 resourceID: Eace933104d443b496b8.nodes.heat.vpg
523 generic-vnf.vnf-id: {generic-vnf.vnf-id}
527 success: final_success
528 failure: final_failure
529 failure_timeout: final_failure_timeout
530 failure_retries: final_failure_retries
531 failure_exception: final_failure_exception
532 failure_guard: final_failure_guard
539 controlLoopName: ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3
541 - serviceName: d4738992-6497-4dca-9db9
542 serviceInvariantUUID: dc112d6e-7e73-4777-9c6f-1a7fb5fd1b6f
543 serviceUUID: 2eea06c6-e1d3-4c3a-b9c4-478c506eeedf
544 trigger_policy: unique-policy-id-1-scale-up
548 - id: unique-policy-id-1-scale-up
549 name: Create a new VF Module
552 recipe: VF Module Create
554 resourceID: 59a2ee3fB58045feB5a1.nodes.heat.vdns
557 success: final_success
558 failure: final_failure
559 failure_timeout: final_failure_timeout
560 failure_retries: final_failure_retries
561 failure_exception: final_failure_exception
562 failure_guard: final_failure_guard
566 # Control Loop Final Results Explained
568 A Control Loop Policy has the following set of final results, as defined in [FinalResult.java](src/main/java/com/att/ecomp/policy/controlloop/policy/FinalResult.java). A final result indicates when a Control Loop Policy has finished execution and is finished processing a Closed Loop Event. All paths must lead to a Final Result.