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

   1 Copyright 2018 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 v1.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 v1.0.0:
  11
  12 * A single DCAE Closed Loop Event is the trigger for the overall Control Loop Policy
  13 * APPC is the only Actor that Policy will interact with. The operations available are: RESTART, REBUILD, MIGRATE.
  14 * An overall timeout for the Control Loop Policy must be provided
  15 * The Control Loop Policy can contain zero or more Operational Policies each chained together via outcomes of each policy.
  16 * If there are zero Operational Policies, i.e. no automated action is to be taken, then the policy is an Open Loop policy.
  17 * Operational Policies can have retries and timeout's given to control how they are processed.
  18
  19 This SDK helps build the YAML specification for ONAP Control Loop Policy v1.0.0.
  20
  21 # Create Builder Object
  22
  23 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.
  24
  25 ```java
  26                 ControlLoopPolicyBuilder builder = ControlLoopPolicyBuilder.Factory.buildControlLoop(
  27                                 UUID.randomUUID().toString(),
  28                                 2400,
  29                                 new Resource("sampleResource", ResourceType.VF),
  30                                 new Service("sampleService")
  31                                 );
  32 ```
  33
  34 # Define the Trigger Policy
  35
  36 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.
  37
  38 ```java
  39                 Policy triggerPolicy = builder.setTriggerPolicy(
  40                                 "Restart the VM",
  41                                 "Upon getting the trigger event, restart the VM",
  42                                 Actor.APPC,
  43                                 Target.VM,
  44                                 "Restart",
  45                                 2,
  46                                 300);
  47 ```
  48
  49 # Chain Operational Policies Together Using Operational Results
  50
  51 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
  52 setPolicyForPolicyResult() method.
  53
  54 ```java
  55                 Policy onRestartFailurePolicy = builder.setPolicyForPolicyResult(
  56                                 "Rebuild VM",
  57                                 "If the restart fails, rebuild it.",
  58                                 Actor.APPC,
  59                                 Target.VM,
  60                                 "Rebuild",
  61                                 1,
  62                                 600,
  63                                 triggerPolicy.id,
  64                                 PolicyResult.FAILURE,
  65                                 PolicyResult.FAILURE_RETRIES,
  66                                 PolicyResult.FAILURE_TIMEOUT);
  67 ```
  68
  69 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.
  70
  71 # Build the YAML Specification
  72
  73 When finished defining the Policies, build the specification and analyze the [Results.java](src/main/java/org/onap/policy/controlloop/policy/builder/Results.java)
  74
  75 ```java
  76                 Results results = builder.buildSpecification();
  77                 if (results.isValid()) {
  78                         System.out.println(results.getSpecification());
  79                 } else {
  80                         System.err.println("Builder failed");
  81                         for (Message message : results.getMessages()) {
  82                                 System.err.println(message.getMessage());
  83                         }
  84                 }
  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 ONAP 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 SDC Catalog API and SDC 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 SDC, the unique ID for the resource version |
 115 | resourceName | string | required if NO resourceUUID available | Name of the resource, ideally from SDC catalog. But if not available, use well-known name. |
 116 | resourceType | string | optional | Use values defined by SDC: VF, VFC, VL, CP. |
 117 | resourceUUID | string - UUID | required IF available, else populate resourceName | Unique ID for the resource as assigned via SDC.
 118 | resourceVersion | string | optional | string version of the resource via SDC catalog
 119
 120 SDC catalog is not fully available and resources have not been defined yet, use resourceName. Eg. vFW
 121
 122 ### service Object
 123
 124 This object was derived via SDC Catalog API and SDC 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 SDC catalog, the unique ID for the service version |
 129 | serviceName | string | required if NO serviceUUID available | Name of the service, ideally from SDC 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 SDC
 131 | serviceVersion | string | optional | string version of the service via SDC catalog
 132
 133 SDC catalog is not fully available and some services have not been defined yet, use serviceName. Eg. vLB.
 134
 135 ### pnf Object
 136
 137 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.
 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"). 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 ONAP 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 v1.0.0
 172
 173 [vService](src/test/resources/v1.0.0/policy_vService.yaml)
 174 [Open-Loop](src/test/resources/v1.0.0/policy_OpenLoop.yaml)
 175
 176
 177 ### vService
 178 ```
 179 controlLoop:
 180   version: 1.0.0
 181   controlLoopName: ControlLoop-vService-cbed919f-2212-4ef7-8051-fe6308da1bda
 182   services:
 183     - serviceName: service1
 184   resources:
 185     - resourceName: resource1
 186       resourceType: VF
 187     - resourceName: resource2
 188       resourceType: VF
 189     - resourceName: resource3
 190       resourceType: VF
 191     - resourceName: resource4
 192       resourceType: VF
 193     - resourceName: resource5
 194       resourceType: VF
 195   trigger_policy: unique-policy-id-1-restart
 196   timeout: 1200
 197
 198 policies:
 199   - id: unique-policy-id-1-restart
 200     name: Restart Policy
 201     description:
 202     actor: APPC
 203     recipe: Restart
 204     target: VM
 205     retry: 2
 206     timeout: 300
 207     success: final_success
 208     failure: unique-policy-id-2-rebuild
 209     failure_timeout: unique-policy-id-2-rebuild
 210     failure_retries: unique-policy-id-2-rebuild
 211     failure_exception: final_failure_exception
 212
 213   - id: unique-policy-id-2-rebuild
 214     name: Rebuild Policy
 215     description:
 216     actor: APPC
 217     recipe: Rebuild
 218     target: VM
 219     retry: 0
 220     timeout: 600
 221     success: final_success
 222     failure: unique-policy-id-3-migrate
 223     failure_timeout: unique-policy-id-3-migrate
 224     failure_retries: unique-policy-id-3-migrate
 225     failure_exception: final_failure_exception
 226
 227   - id: unique-policy-id-3-migrate
 228     name: Migrate Policy
 229     description:
 230     actor: APPC
 231     recipe: Migrate
 232     target: VM
 233     retry: 0
 234     timeout: 600
 235     success: final_success
 236     failure: final_failure
 237     failure_timeout: final_failure_timeout
 238     failure_retries: final_failure_retries
 239     failure_exception: final_failure_exception
 240
 241 ```
 242
 243 ### Open Loop
 244 ```
 245 controlLoop:
 246   version: 1.0.0
 247   controlLoopName: ControlLoop-Open-fac4ae3d-c3f5-4bab-8e54-0a8581ede132
 248   services:
 249     - serviceName: service1
 250   resources:
 251     - resourceType: VF
 252       resourceName: resource1
 253   trigger_policy: final_openloop
 254   timeout: 0
 255
 256 policies:
 257 ```
 258
 259
 260
 261 # Control Loop Final Results Explained
 262
 263 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.
 264