models-interactions/model-yaml/README-v2.0.0.md

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