controlloop/common/policy-yaml/README- v1.0.0.md

   1 ECOMP Control Loop Policy
   2
   3 A control loop policy is a YAML specification for creating and chaining policies for ControlLoop.
   4
   5 1610 ECOMP Control Loop Policy Features:
   6
   7 * A single DCAE Closed Loop Event is the trigger for the overall Control Loop Policy
   8 * APPC is the only Actor that Policy will interact with. The operations available are: RESTART, REBUILD, MIGRATE.
   9 * An overall timeout for the Control Loop Policy must be provided
  10 * The Control Loop Policy can contain zero or more Operational Policies each chained together via outcomes of each policy.
  11 * If there are zero Operational Policies, i.e. no automated action is to be taken, then the policy is an Open Loop policy.
  12 * Operational Policies can have retries and timeout's given to control how they are processed.
  13
  14 This SDK helps build the YAML specification for 1610 ECOMP Control Loop Polices.
  15
  16 # Create Builder Object
  17
  18 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.
  19
  20 ```java
  21                 ControlLoopPolicyBuilder builder = ControlLoopPolicyBuilder.Factory.buildControlLoop(
  22                                 UUID.randomUUID().toString(),
  23                                 2400,
  24                                 new Resource("vCTS", ResourceType.VF),
  25                                 new Service("vUSP")
  26                                 );
  27 ```
  28
  29 # Define the Trigger Policy
  30
  31 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.
  32
  33 ```java
  34                 Policy triggerPolicy = builder.setTriggerPolicy(
  35                                 "Restart the VM",
  36                                 "Upon getting the trigger event, restart the VM",
  37                                 Actor.APPC,
  38                                 Target.VM,
  39                                 "Restart",
  40                                 2,
  41                                 300);
  42 ```
  43
  44 # Chain Operational Policies Together Using Operational Results
  45
  46 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
  47 setPolicyForPolicyResult() method.
  48
  49 ```java
  50                 Policy onRestartFailurePolicy = builder.setPolicyForPolicyResult(
  51                                 "Rebuild VM",
  52                                 "If the restart fails, rebuild it.",
  53                                 Actor.APPC,
  54                                 Target.VM,
  55                                 "Rebuild",
  56                                 1,
  57                                 600,
  58                                 triggerPolicy.id,
  59                                 PolicyResult.FAILURE,
  60                                 PolicyResult.FAILURE_RETRIES,
  61                                 PolicyResult.FAILURE_TIMEOUT);
  62 ```
  63
  64 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.
  65
  66 # Build the YAML Specification
  67
  68 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)
  69
  70 ```java
  71                 Results results = builder.buildSpecification();
  72                 if (results.isValid()) {
  73                         System.out.println(results.getSpecification());
  74                 } else {
  75                         System.err.println("Builder failed");
  76                         for (Message message : results.getMessages()) {
  77                                 System.err.println(message.getMessage());
  78                         }
  79                 }
  80 ```
  81
  82 # Sample Code
  83
  84 Sample code is available in this project: https://codecloud.web.att.com/projects/ST_POLICY/repos/com.att.ecomp.policy.controlloop.sample/browse
  85
  86
  87
  88 # Use the YAML Specification to call the Create Policy API
  89
  90 Now that you have a valid YAML specification, call the createPolicy API via the ECOMP Policy Platform API.
  91
  92 # YAML Specification
  93
  94 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, and which Operational Policy is triggered upon receiving the event. The [policies section](#policies-array) is simply an array of [Policy Objects](#policy-object).
  95
  96 ## controlLoop Object
  97
  98 | Field Name      | Type          | Required   | Description  |
  99 | -------------   |:-------------:| -----------| ------------:|
 100 | controlLoopName | string        | required | Unique ID for the control Loop |
 101 | version         | string        | required | Value for this release if 1.0.0 |
 102 | services        | array of [service](#service-object) objects | optional | Zero or more services associated with this Control Loop |
 103 | resources        | array of [resource](#resource-object) object | required (If NOT a pnf control loop) | The resource's associated with this Control Loop. |
 104 | pnf             | [pnf](#pnf-object) object | required (If NOT a resource control loop) | The physical network function associated with this Control Loop. |
 105 | trigger_policy  | string     | required | Either this is the ID of an Operation Policy (see policy object), or "Final_OpenLoop" indicating an Open Loop |
 106 | 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 |
 107
 108 ### resource Object
 109
 110 This object was derived via ASDC Catalog API and ASDC Data Dictionary (POC) in an attempt to use common naming conventions.
 111
 112 | Field Name      | Type          | Required   | Description  |
 113 | -------------   |:-------------:| -----------| ------------:|
 114 | resourceInvariantUUID | string - UUID | optional | via ASDC, the unique ID for the resource version |
 115 | resourceName | string | required if NO resourceUUID available | Name of the resource, ideally from ASDC catalog. But if not available, use well-known name. |
 116 | resourceType | string | optional | Use values defined by ASDC: VF, VFC, VL, CP. |
 117 | resourceUUID | string - UUID | required IF available, else populate resourceName | Unique ID for the resource as assigned via ASDC.
 118 | resourceVersion | string | optional | string version of the resource via ASDC catalog
 119
 120 Given in 1610 the ASDC catalog is not fully available and resources have not been defined yet, use resourceName. Eg. F5FW
 121
 122 ### service Object
 123
 124 This object was derived via ASDC Catalog API and ASDC Data Dictionary (POC) in an attempt to use common naming conventions.
 125
 126 | Field Name      | Type          | Required   | Description  |
 127 | -------------   |:-------------:| -----------| ------------:|
 128 | serviceInvariantUUID | string - UUID | optional | via ASDC catalog, the unique ID for the service version |
 129 | serviceName | string | required if NO serviceUUID available | Name of the service, ideally from ASDC catalog. But if not available, use well-known name. |
 130 | serviceUUID | string - UUID | required IF available, else populate serviceName | Unique ID fort he service as assigned via ASDC
 131 | serviceVersion | string | optional | string version of the service via ASDC catalog
 132
 133 Given in 1610 the ASDC catalog is not fully available and some services have not been defined yet, use resourceName. Eg. vUSP, vSCP, trinity.
 134
 135 ### pnf Object
 136
 137 This object is used for a physical network function. In the case of 1610, eNodeB is the use case supported. Expect this object to change in the future when ECOMP Policy fully integrates with A&AI.
 138
 139 | Field Name      | Type          | Required   | Description  |
 140 | -------------   |:-------------:| -----------| ------------:|
 141 | PNFName         | string        | required   | Name of the PNF. Should be supplied via A&AI. If not available use a well-known name. |
 142 | PNFType         | string        | optional   | Type of PNF if available. |
 143
 144
 145 ## policies array
 146
 147 The policies section is an array of [Policy objects](#policy-object).
 148
 149 ### Policy Object
 150
 151 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 1610, there are 2 actors: APPC and RAN. An operation is simply defined as performing a recipe (or operation) on an actor.
 152
 153 | Field Name      | Type          | Required   | Description  |
 154 | -------------   |:-------------:| -----------| ------------:|
 155 | id              | string        | required   | Unique ID for the policy.
 156 | name            | string        | required   | Policy name |
 157 | description     | string        | optional   | Policy description |
 158 | actor           | string        | required   | Name of the actor for this operation: Example: APPC |
 159 | recipe          | string        | required   | Name of recipe to be performed. Example "Restart" |
 160 | target          | string        | required   | Entity being targeted. Example: VM |
 161 | timeout         | int           | required   | Timeout for the actor to perform the recipe. |
 162 | retry           | int           | optional   | Optional number of retries for ECOMP Policy to invoke the recipe on the actor. |
 163 | 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.
 164 | 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. |
 165 | 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. |
 166 | 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. |
 167 | 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. |
 168
 169 Every Operational Policy MUST have a place to go for every possible result (success, failure, failure_retries, failure_timeout, failure_exception). By default, all the results are final results.
 170
 171 ## Examples of YAML Control Loops for 1610
 172
 173 [1607-F5](src/test/resources/v1.0.0/policy_vSCP_F5_1610.yaml)
 174 [1610-vUSP](src/test/resources/v1.0.0/policy_vUSP_1610.yaml)
 175 [1610-Open-Loop](src/test/resources/v1.0.0/policy_OpenLoop_1610.yaml)
 176 [1610-vProbes](src/test/resources/v1.0.0/policy_vProbes_1610.yaml)
 177 [VNF-with-Multiple-Services](src/test/resources/v1.0.0/policy_Test_MultipleService.yaml)
 178
 179 ### 1607 F5
 180 ```
 181 controlLoop:
 182   version: 1.0.0
 183   controlLoopName: ClosedLoop-FRWL-SIG-d925ed73-8231-4d02-9545-db4e101f88f8
 184   services:
 185     - serviceName: vSCP
 186     - serviceName: trinity
 187   resources:
 188     - resourceName: F5FW
 189       resourceType: VF
 190   trigger_policy: unique-policy-id-1-restart
 191   timeout: 1200
 192
 193 policies:
 194   - id: unique-policy-id-1-restart
 195     name: Restart Policy
 196     description:
 197     actor: APPC
 198     recipe: Restart
 199     target: VM
 200     retry: 2
 201     timeout: 300
 202     success: final_success
 203     failure: final_failure
 204     failure_timeout: final_failure_timeout
 205     failure_retries: final_failure_retries
 206     failure_exception: final_failure_exception
 207
 208 ```
 209
 210 ### 1610 vUSP
 211 ```
 212 controlLoop:
 213   version: 1.0.0
 214   controlLoopName: ControlLoop-vUSP-vCTS-cbed919f-2212-4ef7-8051-fe6308da1bda
 215   services:
 216     - serviceName: vUSP
 217   resources:
 218     - resourceName: vCTS
 219       resourceType: VF
 220     - resourceName: vCOM
 221       resourceType: VF
 222     - resourceName: vRAR
 223       resourceType: VF
 224     - resourceName: vLCS
 225       resourceType: VF
 226     - resourceName: v3CB
 227       resourceType: VF
 228   trigger_policy: unique-policy-id-1-restart
 229   timeout: 1200
 230
 231 policies:
 232   - id: unique-policy-id-1-restart
 233     name: Restart Policy
 234     description:
 235     actor: APPC
 236     recipe: Restart
 237     target: VM
 238     retry: 2
 239     timeout: 300
 240     success: final_success
 241     failure: unique-policy-id-2-rebuild
 242     failure_timeout: unique-policy-id-2-rebuild
 243     failure_retries: unique-policy-id-2-rebuild
 244     failure_exception: final_failure_exception
 245
 246   - id: unique-policy-id-2-rebuild
 247     name: Rebuild Policy
 248     description:
 249     actor: APPC
 250     recipe: Rebuild
 251     target: VM
 252     retry: 0
 253     timeout: 600
 254     success: final_success
 255     failure: unique-policy-id-3-migrate
 256     failure_timeout: unique-policy-id-3-migrate
 257     failure_retries: unique-policy-id-3-migrate
 258     failure_exception: final_failure_exception
 259
 260   - id: unique-policy-id-3-migrate
 261     name: Migrate Policy
 262     description:
 263     actor: APPC
 264     recipe: Migrate
 265     target: VM
 266     retry: 0
 267     timeout: 600
 268     success: final_success
 269     failure: final_failure
 270     failure_timeout: final_failure_timeout
 271     failure_retries: final_failure_retries
 272     failure_exception: final_failure_exception
 273
 274 ```
 275
 276 ### 1610 Open Loop
 277 ```
 278 controlLoop:
 279   version: 1.0.0
 280   controlLoopName: ControlLoop-Open-fac4ae3d-c3f5-4bab-8e54-0a8581ede132
 281   services:
 282     - serviceName: Service
 283   resources:
 284     - resourceType: VF
 285       resourceName: Example
 286   trigger_policy: final_openloop
 287   timeout: 0
 288
 289 policies:
 290 ```
 291
 292 ### 1610 vProbes
 293 ```
 294 controlLoop:
 295   version: 1.0.0
 296   controlLoopName: ControlLoop-vProbes-41aba939-9a93-4535-b193-973c68fc8763
 297   services:
 298   resources:
 299     - resourceName: vProbes
 300       resourceType: VF
 301   trigger_policy: unique-policy-id-1-restart
 302   timeout: 600
 303
 304 policies:
 305   - id: unique-policy-id-1-restart
 306     name: Restart Policy
 307     description:
 308     actor: APPC
 309     recipe: Restart
 310     target: VM
 311     retry: 2
 312     timeout: 300
 313     success: final_success
 314     failure: final_failure
 315     failure_timeout: final_failure_timeout
 316     failure_retries: final_failure_retries
 317     failure_exception: final_failure_exception
 318
 319 ```
 320
 321 ### VNF with Multiple Services
 322 ```
 323 controlLoop:
 324   version: 1.0.0
 325   controlLoopName: ClosedLoop-FRWL-SIG-d925ed73-8231-4d02-9545-db4e101f88f8
 326   services:
 327     - serviceName: vSCP
 328     - serviceName: vSBG
 329   resources:
 330     - resourceName: F5FW
 331       resourceType: VF
 332   trigger_policy: unique-policy-id-1-restart
 333   timeout: 1200
 334
 335 policies:
 336   - id: unique-policy-id-1-restart
 337     name: Restart Policy
 338     description:
 339     actor: APPC
 340     recipe: Restart
 341     target: VM
 342     retry: 2
 343     timeout: 300
 344     success: final_success
 345     failure: final_failure
 346     failure_timeout: final_failure_timeout
 347     failure_retries: final_failure_retries
 348     failure_exception: final_failure_exception
 349
 350 ```
 351
 352
 353 # Control Loop Final Results Explained
 354
 355 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.
 356