1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
|
ECOMP Control Loop Policy v2.0.0
A control loop policy is a YAML specification for creating and chaining policies for ControlLoop.
1707 ECOMP Control Loop Policy Features:
* Backward compatible with 1610 ECOMP Control Loop Policy
* A single DCAE Closed Loop Event is the trigger for the overall Control Loop Policy.
* An overall timeout for the Control Loop Policy must be provided.
* An abatement flag indicating whether Policy will receive abatement event for the Control Loop could be provided.
* The Control Loop Policy can contain zero or more Operational Policies each chained together via outcomes of each policy.
* If there are zero Operational Policies, i.e. no automated action is to be taken, then the policy is an Open Loop policy.
* Operational policies can have target, retries and timeout's given to control how they are processed.
* Type and resourceID of the target could be provided to support the target in operational policies.
* Payload could be provided to support the recipe.
* 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.
| Actor | Recipe | Target | Payload |
| -------------|:---------------------------:| ---------| ------------:|
| APPC | Restart | VM | AICVServerSelfLink, AICIdentity |
| APPC | Rebuild | VM | AICVServerSelfLink, AICIdentity |
| APPC | Migrate | VM | AICVServerSelfLink, AICIdentity |
| APPC | ModifyConfig | VFC | generic-vnf.vnf-id |
| MSO | VF Module Create | VFC | optional |
| SDNO | health-diagnostic-type | VM | health-diagnostic-code, health-diagnostic-code-parameters |
| SDNO | health-diagnostic | VM | optional |
| SDNO | health-diagnostic-history | VM | optional |
| SDNO | health-diagnostic-commands | VM | optional |
| SDNO | health-diagnostic-aes | VM | optional |
| SDNR | Reset | PNF | optional |
| AOTS | checkMaintenanceWindow | VM | optional |
| AOTS | checkENodeBTicketHours | VM | timeWindow |
| AOTS | checkEquipmentStatus | VM | optional |
| AOTS | checkEimStatus | VM | optional |
This SDK helps build the YAML specification for 1707 ECOMP Control Loop Polices.
# Create Builder Object
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.
```java
ControlLoopPolicyBuilder builder = ControlLoopPolicyBuilder.Factory.buildControlLoop(
UUID.randomUUID().toString(),
2400,
new Resource("vCTS", ResourceType.VF),
new Service("vUSP")
);
```
# Define the Trigger Policy
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.
```java
Policy triggerPolicy = builder.setTriggerPolicy(
"Restart the VM",
"Upon getting the trigger event, restart the VM",
"APPC",
new Target(TargetType.VM),
"Restart",
null,
2,
300);
```
# Set the Abatement Flag for the Control Loop
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.
```java
builder = builder.setAbatement(false);
```
# Chain Operational Policies Together Using Operational Results
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
setPolicyForPolicyResult() method.
```java
Policy onRestartFailurePolicy = builder.setPolicyForPolicyResult(
"Rebuild VM",
"If the restart fails, rebuild it.",
"APPC",
new Target(TargetType.VM),
"Rebuild",
null,
1,
600,
triggerPolicy.id,
PolicyResult.FAILURE,
PolicyResult.FAILURE_RETRIES,
PolicyResult.FAILURE_TIMEOUT,
PolicyResult.FAILURE_GUARD);
```
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.
# Build the YAML Specification
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)
```java
Results results = builder.buildSpecification();
if (results.isValid()) {
System.out.println(results.getSpecification());
} else {
System.err.println("Builder failed");
for (Message message : results.getMessages()) {
System.err.println(message.getMessage());
}
}
```
# Sample Code
Sample code is available in this project: https://codecloud.web.att.com/projects/ST_POLICY/repos/com.att.ecomp.policy.controlloop.sample/browse
# Use the YAML Specification to call the Create Policy API
Now that you have a valid YAML specification, call the createPolicy API via the ECOMP Policy Platform API.
# YAML Specification
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).
## controlLoop Object
| Field Name | Type | Required | Description |
| ------------- |:-------------:| -----------| ------------:|
| controlLoopName | string | required | Unique ID for the control Loop |
| version | string | required | Value for this release if 1.0.0 |
| services | array of [service](#service-object) objects | optional | Zero or more services associated with this Control Loop |
| resources | array of [resource](#resource-object) object | required (If NOT a pnf control loop) | The resource's associated with this Control Loop. |
| pnf | [pnf](#pnf-object) object | required (If NOT a resource control loop) | The physical network function associated with this Control Loop. |
| trigger_policy | string | required | Either this is the ID of an Operation Policy (see policy object), or "Final_OpenLoop" indicating an Open Loop |
| 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 |
| abatement | boolean | optional | This is an abatement flag indicating if DCAE will send abatement event to Policy for this Control Loop |
### resource Object
This object was derived via ASDC Catalog API and ASDC Data Dictionary (POC) in an attempt to use common naming conventions.
| Field Name | Type | Required | Description |
| ------------- |:-------------:| -----------| ------------:|
| resourceInvariantUUID | string - UUID | optional | via ASDC, the unique ID for the resource version |
| resourceName | string | required if NO resourceUUID available | Name of the resource, ideally from ASDC catalog. But if not available, use well-known name. |
| resourceType | string | optional | Use values defined by ASDC: VF, VFC, VL, CP. |
| resourceUUID | string - UUID | required IF available, else populate resourceName | Unique ID for the resource as assigned via ASDC.
| resourceVersion | string | optional | string version of the resource via ASDC catalog
### service Object
This object was derived via ASDC Catalog API and ASDC Data Dictionary (POC) in an attempt to use common naming conventions.
| Field Name | Type | Required | Description |
| ---------------:| -------------:| ----------:| ------------:|
| serviceInvariantUUID | string - UUID | optional | via ASDC catalog, the unique ID for the service version |
| serviceName | string | required if NO serviceUUID available | Name of the service, ideally from ASDC catalog. But if not available, use well-known name. |
| serviceUUID | string - UUID | required IF available, else populate serviceName | Unique ID fort he service as assigned via ASDC
| serviceVersion | string | optional | string version of the service via ASDC catalog
### pnf Object
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.
| Field Name | Type | Required | Description |
| ------------- |:-------------:| -----------| ------------:|
| PNFName | string | required | Name of the PNF. Should be supplied via A&AI. If not available use a well-known name. |
| PNFType | string | optional | Type of PNF if available. |
## policies array
The policies section is an array of [Policy objects](#policy-object).
### Policy Object
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.
| Field Name | Type | Required | Description |
| ------------- |:-------------:| -----------| ------------:|
| id | string | required | Unique ID for the policy.
| name | string | required | Policy name |
| description | string | optional | Policy description |
| actor | string | required | Name of the actor for this operation: Example: APPC |
| recipe | string | required | Name of recipe to be performed. Example "Restart" |
| target | [target](#target-object) object | required | Entity being targeted. Example: VM |
| timeout | int | required | Timeout for the actor to perform the recipe. |
| retry | int | optional | Optional number of retries for ECOMP Policy to invoke the recipe on the actor. |
| 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.
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
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.
#### target Object
This object is used for defining a target entity of a recipe.
| Field Name | Type | Required | Description |
| ------------- |:-------------:| -----------| ------------:|
| type | enums of VM, PNF and VNC | required | Type of the target. |
| resourceID | string | optional | Resource ID of the target. Should be supplied via ASDC Catalog. |
## Examples of YAML Control Loops for 1707
[1707-vUSP](src/test/resources/v2.0.0/policy_vUSP_1707.yaml)
[1707-eNodeB-Ericsson](src/test/resources/v2.0.0/policy_eNodeB_Ericsson_1707.yaml)
[1707-eNodeB-ALU](src/test/resources/v2.0.0/policy_eNodeB_ALU_1707.yaml)
[OpenECOMP-vFirewall](src/test/resources/v2.0.0/policy_OpenECOMP_demo_vFirewall.yaml)
[OpenECOMP-vDNS](src/test/resources/v2.0.0/policy_OpenECOMP_demo_vDNS.yaml)
### 1707 vUSP
```
controlLoop:
version: 2.0.0
controlLoopName: ControlLoop-vUSP-vCTS-cbed919f-2212-4ef7-8051-fe6308da1bda
services:
- serviceName: vUSP
resources:
- resourceName: vCTS
resourceType: VFC
- resourceName: vCOM
resourceType: VFC
- resourceName: vRAR
resourceType: VFC
- resourceName: vLCS
resourceType: VFC
- resourceName: v3CB
resourceType: VFC
trigger_policy: unique-policy-id-1-restart
timeout: 1200
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 SDNO Health Diagnostic
description:
actor: SDNO
recipe: health-diagnostic
payload:
health-diagnostic-code: HC99
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 SDNO Health Diagnostic
description:
actor: SDNO
recipe: health-diagnostic
payload:
health-diagnostic-code: HC99
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
```
### 1707 eNodeB Ericsson
```
controlLoop:
version: 2.0.0
controlLoopName: ControlLoop-eNodeB-Ericsson-0732e76a-4228-42d1-8185-972510be388c
services:
resources:
pnf:
PNFName: eNodeB.Ericsson
trigger_policy: unique-policy-id-1-check-aots-ticket
timeout: 2400
policies:
- id: unique-policy-id-1-check-aots-ticket
name: Check AOTS CTS
description: Discard sleeping cell based on the new signature if it appears in recent CTS tickets
actor: AOTS
recipe: checkENodeBTicketHours
payload:
timeWindow: 5
retry: 2
timeout: 300
success: unique-policy-id-2-check-aots-cts
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-2-check-aots-cts
name: Check AOTS CTS Equipment
description: Discard sleeping cell based on the new signature if it is not active in CTS equipment data
actor: AOTS
recipe: checkEquipmentStatus
payload:
retry: 2
timeout: 300
success: unique-policy-id-3-check-aots-eim
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-3-check-aots-eim
name: Check AOTS EIM_RT
description: Discard sleeping cell based on the new signature if it appears in EIM_RT data
actor: AOTS
recipe: checkEimStatus
retry: 2
timeout: 300
success: unique-policy-id-3-check-aots-maintenance
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-4-check-aots-maintenance
name: Check AOTS MAINTENANCE
description: Discard sleeping cell based on the new signature if it appears in Maintenance
actor: AOTS
recipe: checkMaintenanceWindow
retry: 2
timeout: 300
success: unique-policy-id-5-sdnr-reset
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-5-sdnr-reset
name: Have SDNR Reset
description: SDNR should now reset this sleeper
actor: SDNR
recipe: Reset
operationsAccumulateParams:
period: 15m
limit: 5
retry: 2
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
```
### 1707 eNodeB ALU
```
controlLoop:
version: 2.0.0
controlLoopName: ControlLoop-eNodeB-ALU-3ee91181-6f05-4cd3-8437-cad5f58653ca
services:
resources:
pnf:
PNFName: eNodeB.ALU
trigger_policy: unique-policy-id-1-check-aots
timeout: 2400
policies:
- id: unique-policy-id-1-check-aots
name: Check AOTS CTS
description: Discard sleeping cell based on the new signature if it appears in recent CTS tickets
actor: AOTS
recipe: checkENodeBTicketHours
payload:
timeWindow: 5
retry: 2
timeout: 300
success: unique-policy-id-2-check-aots-cts
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-2-check-aots-cts
name: Check AOTS CTS Equipment
description: Discard sleeping cell based on the new signature if it is not active in CTS equipment data
actor: AOTS
recipe: checkEquipmentStatus
retry: 2
timeout: 300
success: unique-policy-id-3-check-aots-eim
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-3-check-aots-eim
name: Check AOTS EIM_RT
description: Discard sleeping cell based on the new signature if it appears in EIM_RT data
actor: AOTS
recipe: checkEimStatus
retry: 2
timeout: 300
success: unique-policy-id-4-sdnr-reset
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-4-sdnr-reset
name: Have SDNR Reset
description: SDNR should now reset this sleeper
actor: SDNR
recipe: Reset
operationsAccumulateParams:
period: 15m
limit: 5
retry: 2
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
```
### OpenECOMP vFirewall
```
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: Change the Load Balancer
description:
actor: APPC
recipe: ModifyConfig
target:
resourceID: Eace933104d443b496b8.nodes.heat.vpg
payload:
generic-vnf.vnf-id: {generic-vnf.vnf-id}
ref$: pgstreams.json
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
```
### OpenECOMP vDNS
```
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:
resourceID: 59a2ee3fB58045feB5a1.nodes.heat.vdns
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
```
# Control Loop Final Results Explained
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.
|
