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

   1 ONAP Control Loop Policy v2.0.0
   2
   3 A control loop policy is a YAML specification for creating and chaining policies for ControlLoop.
   4
   5 Features of ONAP Control Loop Policy v2.0.0:
   6
   7 * Backward compatible with ONAP Control Loop Policy v1.0.0
   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.
  17
  18 | Actor        | Recipe                      | Target   | Payload  |
  19 | -------------|:---------------------------:| ---------| ------------:|
  20 | APPC         | Restart                     | VM       | CloudVServerSelfLink, CloudIdentity |
  21 | APPC         | Rebuild                     | VM       | CloudVServerSelfLink, CloudIdentity |
  22 | APPC         | Migrate                                 | VM           | CloudVServerSelfLink, CloudIdentity |
  23 | APPC         | ModifyConfig                            | VNF          | generic-vnf.vnf-id |
  24 | SO           | VF Module Create                        | VFC          | optional |
  25
  26
  27 This SDK helps build the YAML specification for ONAP Control Loop Policy v2.0.0.
  28
  29 # Create Builder Object
  30
  31 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/org/onap/policy/controlloop/policy/builder/ControlLoopPolicyBuilder.java) that can then be used to continue to build and define the Control Loop Policy.
  32
  33 ```java
  34                 ControlLoopPolicyBuilder builder = ControlLoopPolicyBuilder.Factory.buildControlLoop(
  35                                 UUID.randomUUID().toString(),
  36                                 2400,
  37                                 new Resource("sampleResource", ResourceType.VF),
  38                                 new Service("sampleService")
  39                                 );
  40 ```
  41
  42 # Define the Trigger Policy
  43
  44 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.
  45
  46 ```java
  47                 Policy triggerPolicy = builder.setTriggerPolicy(
  48                                 "Restart the VM",
  49                                 "Upon getting the trigger event, restart the VM",
  50                                 "APPC",
  51                                 new Target(TargetType.VM),
  52                                 "Restart",
  53                                 null,
  54                                 2,
  55                                 300);
  56 ```
  57
  58 # Set the Abatement Flag for the Control Loop
  59
  60 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.
  61
  62 ```java
  63             builder = builder.setAbatement(false);
  64 ```
  65
  66 # Chain Operational Policies Together Using Operational Results
  67
  68 Operational Policies are chained together using the results of each Operational Policy. The results are defined in [PolicyResult.java](src/main/java/org/onap/policy/controlloop/policy/PolicyResult.java). To create an Operational Policy that is tied to the result of another, use the
  69 setPolicyForPolicyResult() method.
  70
  71 ```java
  72                 Policy onRestartFailurePolicy = builder.setPolicyForPolicyResult(
  73                                 "Rebuild VM",
  74                                 "If the restart fails, rebuild it.",
  75                                 "APPC",
  76                                 new Target(TargetType.VM),
  77                                 "Rebuild",
  78                                 null,
  79                                 1,
  80                                 600,
  81                                 triggerPolicy.id,
  82                                 PolicyResult.FAILURE,
  83                                 PolicyResult.FAILURE_RETRIES,
  84                                 PolicyResult.FAILURE_TIMEOUT,
  85                                 PolicyResult.FAILURE_GUARD);
  86 ```
  87
  88 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.
  89
  90
  91
  92 # Build the YAML Specification
  93
  94 When finished defining the Policies, build the specification and analyze the [Results.java](src/main/java/org/onap/policy/controlloop/policy/builder/Results.java)
  95
  96 ```java
  97                 Results results = builder.buildSpecification();
  98                 if (results.isValid()) {
  99                         System.out.println(results.getSpecification());
 100                 } else {
 101                         System.err.println("Builder failed");
 102                         for (Message message : results.getMessages()) {
 103                                 System.err.println(message.getMessage());
 104                         }
 105                 }
 106 ```
 107
 108
 109 # Use the YAML Specification to call the Create Policy API
 110
 111 Now that you have a valid YAML specification, call the createPolicy API via the ONAP Policy Platform API.
 112
 113
 114 # YAML Specification
 115
 116 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).
 117
 118 ## controlLoop Object
 119
 120 | Field Name      | Type          | Required   | Description  |
 121 | -------------   |:-------------:| -----------| ------------:|
 122 | controlLoopName | string        | required | Unique ID for the control Loop |
 123 | version         | string        | required | Value for this release if 1.0.0 |
 124 | services        | array of [service](#service-object) objects | optional | Zero or more services associated with this Control Loop |
 125 | resources        | array of [resource](#resource-object) object | required (If NOT a pnf control loop) | The resource's associated with this Control Loop. |
 126 | pnf             | [pnf](#pnf-object) object | required (If NOT a resource control loop) | The physical network function associated with this Control Loop. |
 127 | trigger_policy  | string     | required | Either this is the ID of an Operation Policy (see policy object), or "Final_OpenLoop" indicating an Open Loop |
 128 | 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 |
 129 | abatement       | boolean       | optional | This is an abatement flag indicating if DCAE will send abatement event to Policy for this Control Loop |
 130
 131 ### resource Object
 132
 133 This object was derived via SDC Catalog API and SDC Data Dictionary (POC) in an attempt to use common naming conventions.
 134
 135 | Field Name      | Type          | Required   | Description  |
 136 | -------------   |:-------------:| -----------| ------------:|
 137 | resourceInvariantUUID | string - UUID | optional | via SDC, the unique ID for the resource version |
 138 | resourceName | string | required if NO resourceUUID available | Name of the resource, ideally from SDC catalog. But if not available, use well-known name. |
 139 | resourceType | string | optional | Use values defined by SDC: VF, VFC, VL, CP. |
 140 | resourceUUID | string - UUID | required IF available, else populate resourceName | Unique ID for the resource as assigned via SDC.
 141 | resourceVersion | string | optional | string version of the resource via SDC catalog
 142
 143
 144 ### service Object
 145
 146 This object was derived via SDC Catalog API and SDC Data Dictionary (POC) in an attempt to use common naming conventions.
 147
 148 | Field Name      | Type          | Required   | Description  |
 149 | ---------------:| -------------:| ----------:| ------------:|
 150 | serviceInvariantUUID | string - UUID | optional | via SDC catalog, the unique ID for the service version |
 151 | serviceName | string | required if NO serviceUUID available | Name of the service, ideally from SDC catalog. But if not available, use well-known name. |
 152 | serviceUUID | string - UUID | required IF available, else populate serviceName | Unique ID fort he service as assigned via SDC
 153 | serviceVersion | string | optional | string version of the service via SDC catalog
 154
 155
 156 ### pnf Object
 157
 158 This object is used for a physical network function. Expect this object to change in the future when ONAP Policy fully integrates with A&AI.
 159
 160 | Field Name      | Type          | Required   | Description  |
 161 | -------------   |:-------------:| -----------| ------------:|
 162 | PNFName         | string        | required   | Name of the PNF. Should be supplied via A&AI. If not available use a well-known name. |
 163 | PNFType         | string        | optional   | Type of PNF if available. |
 164
 165
 166 ## policies array
 167
 168 The policies section is an array of [Policy objects](#policy-object).
 169
 170 ### Policy Object
 171
 172 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"). An operation is simply defined as performing a recipe (or operation) on an actor.
 173
 174 | Field Name      | Type          | Required   | Description  |
 175 | -------------   |:-------------:| -----------| ------------:|
 176 | id              | string        | required   | Unique ID for the policy.
 177 | name            | string        | required   | Policy name |
 178 | description     | string        | optional   | Policy description |
 179 | actor           | string        | required   | Name of the actor for this operation: Example: APPC |
 180 | recipe          | string        | required   | Name of recipe to be performed. Example "Restart" |
 181 | target          | [target](#target-object) object        | required   | Entity being targeted. Example: VM |
 182 | timeout         | int           | required   | Timeout for the actor to perform the recipe. |
 183 | retry           | int           | optional   | Optional number of retries for ONAP Policy to invoke the recipe on the actor. |
 184 | 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.
 185 | 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. |
 186 | 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. |
 187 | 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. |
 188 | 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. |
 189 | 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. |
 190
 191 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.
 192
 193 #### target Object
 194
 195 This object is used for defining a target entity of a recipe.
 196
 197 | Field Name      | Type          | Required   | Description  |
 198 | -------------   |:-------------:| -----------| ------------:|
 199 | type            | enums of VM, PNF and VNC | required   | Type of the target. |
 200 | resourceID      | string        | optional   | Resource ID of the target. Should be supplied via SDC Catalog. |
 201
 202
 203 ## Examples of YAML Control Loops v2.0.0
 204
 205 [vService](src/test/resources/v2.0.0/policy_vService.yaml)
 206 [ONAP-vFirewall](src/test/resources/v2.0.0/policy_ONAP_demo_vFirewall.yaml)
 207 [ONAP-vDNS](src/test/resources/v2.0.0/policy_ONAP_demo_vDNS.yaml)
 208
 209 ### vService
 210 ```
 211 controlLoop:
 212   version: 2.0.0
 213   controlLoopName: ControlLoop-vService-cbed919f-2212-4ef7-8051-fe6308da1bda
 214   services:
 215     - serviceName: service1
 216   resources:
 217     - resourceName: resource1
 218       resourceType: VFC
 219     - resourceName: resource2
 220       resourceType: VFC
 221     - resourceName: resource3
 222       resourceType: VFC
 223     - resourceName: resource4
 224       resourceType: VFC
 225     - resourceName: resource5
 226       resourceType: VFC
 227   trigger_policy: unique-policy-id-1-restart
 228   timeout: 1200
 229   abatement: false
 230
 231 policies:
 232   - id: unique-policy-id-1-restart
 233     name: Restart Policy
 234     description:
 235     actor: APPC
 236     recipe: Restart
 237     target:
 238       type: VM
 239     retry: 2
 240     timeout: 300
 241     success: final_success
 242     failure: unique-policy-id-2-rebuild
 243     failure_timeout: unique-policy-id-2-rebuild
 244     failure_retries: unique-policy-id-2-rebuild
 245     failure_exception: final_failure_exception
 246     failure_guard: unique-policy-id-2-rebuild
 247
 248   - id: unique-policy-id-2-rebuild
 249     name: Rebuild Policy
 250     description:
 251     actor: APPC
 252     recipe: Rebuild
 253     target:
 254       type: VM
 255     retry: 0
 256     timeout: 600
 257     success: final_success
 258     failure: unique-policy-id-3-migrate
 259     failure_timeout: unique-policy-id-3-migrate
 260     failure_retries: unique-policy-id-3-migrate
 261     failure_exception: final_failure_exception
 262     failure_guard: unique-policy-id-3-migrate
 263
 264   - id: unique-policy-id-3-migrate
 265     name: Migrate Policy
 266     description:
 267     actor: APPC
 268     recipe: Migrate
 269     target:
 270       type: VM
 271     retry: 0
 272     timeout: 600
 273     success: final_success
 274     failure: final_failure
 275     failure_timeout: final_failure_timeout
 276     failure_retries: final_failure_retries
 277     failure_exception: final_failure_exception
 278     failure_guard: final_failure_guard
 279 ```
 280
 281
 282
 283 ### ONAP vFirewall
 284 ```
 285 controlLoop:
 286   version: 2.0.0
 287   controlLoopName: ControlLoop-vFirewall-d0a1dfc6-94f5-4fd4-a5b5-4630b438850a
 288   services:
 289     - serviceInvariantUUID: 5cfe6f4a-41bc-4247-8674-ebd4b98e35cc
 290       serviceUUID: 0f40bba5-986e-4b3c-803f-ddd1b7b25f24
 291       serviceName: 57e66ea7-0ed6-45c7-970f
 292   trigger_policy: unique-policy-id-1-modifyConfig
 293   timeout: 1200
 294
 295 policies:
 296   - id: unique-policy-id-1-modifyConfig
 297     name: Change the Load Balancer
 298     description:
 299     actor: APPC
 300     recipe: ModifyConfig
 301     target:
 302       resourceID: Eace933104d443b496b8.nodes.heat.vpg
 303     payload:
 304       generic-vnf.vnf-id: {generic-vnf.vnf-id}
 305       ref$: pgstreams.json
 306     retry: 0
 307     timeout: 300
 308     success: final_success
 309     failure: final_failure
 310     failure_timeout: final_failure_timeout
 311     failure_retries: final_failure_retries
 312     failure_exception: final_failure_exception
 313     failure_guard: final_failure_guard
 314 ```
 315
 316 ### ONAP vDNS
 317 ```
 318 controlLoop:
 319   version: 2.0.0
 320   controlLoopName: ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3
 321   services:
 322     - serviceName: d4738992-6497-4dca-9db9
 323       serviceInvariantUUID: dc112d6e-7e73-4777-9c6f-1a7fb5fd1b6f
 324       serviceUUID: 2eea06c6-e1d3-4c3a-b9c4-478c506eeedf
 325   trigger_policy: unique-policy-id-1-scale-up
 326   timeout: 1200
 327
 328 policies:
 329   - id: unique-policy-id-1-scale-up
 330     name: Create a new VF Module
 331     description:
 332     actor: SO
 333     recipe: VF Module Create
 334     target:
 335       resourceID: 59a2ee3fB58045feB5a1.nodes.heat.vdns
 336     retry: 0
 337     timeout: 1200
 338     success: final_success
 339     failure: final_failure
 340     failure_timeout: final_failure_timeout
 341     failure_retries: final_failure_retries
 342     failure_exception: final_failure_exception
 343     failure_guard: final_failure_guard
 344 ```
 345
 346
 347 # Control Loop Final Results Explained
 348
 349 A Control Loop Policy has the following set of final results, as defined in [FinalResult.java](src/main/java/org/onap/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.
 350