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

   1 ECOMP Control Loop Guard
   2
   3 A control loop guard is a YAML specification for creating policy guard for ControlLoop.
   4
   5 1707 ECOMP Control Loop Guard Features:
   6
   7 * The Control Loop Guard can specify the frequency limiter and the blacklist of target entities but not both in the same Guard.
   8 * Two parts are incorporated. One is the common guard header including guard version while the other part is a set of guard policies.
   9 * The Control Loop Guard should contain at least one guard policies.
  10 * Each guard policy is bound to a specific Actor and Recipe.
  11 * Each guard policy should have at least one limit constraints which define how the guard policy should be enforced.
  12 * Supported Actors are APPC, MSO, SDNO, SDNR and AOTS.
  13
  14 This SDK helps build the YAML specification for 1707 ECOMP Control Loop Guard.
  15
  16 # Create Builder Object
  17
  18 To begin with, the ControlLoopGuardBuilder.Factory class has static methods that one should use to begin building a Control Loop Guard. It will return a [ControlLoopGuardBuilder object](src/main/java/com/att/ecomp/policy/controlloop/policy/guard/builder/ControlLoopGuardBuilder.java) that can then be used to continue to build and define the Control Loop Guard.
  19
  20 ```java
  21                 ControlLoopGuardBuilder builder = ControlLoopGuardBuilder.Factory.buildControlLoopGuard(new Guard());
  22 ```
  23
  24 # Add Guard Policy
  25
  26 After a guard builder has been created, the next step would be to add a guard policy to the newly created Control Loop Guard via the builder. To add a guard policy, use the addGuardPolicy() method.
  27
  28 ```java
  29                 GuardPolicy policy = new GuardPolicy(
  30                                                                 "unique_guard_vUSP_1",
  31                                                                 "APPC 5 Restart",
  32                                                                 "We only allow 5 restarts over 15 minute window during the day time hours (i.e. avoid midnight to 5am)",
  33                                                                 "APPC",
  34                                                                 "Restart");
  35                 builder = builder.addGuardPolicy(policy);
  36 ```
  37
  38 # Add Limit Constraint to a Guard Policy
  39
  40 The limit constraint defines the details of how to enforce the guard policy. Each limit constraint can contain two types of constraints - frequency limiter and black list. At least one type of constraints should be specified, otherwise the limit constraint will be counted as invalid. To add a limit constraint to an existing guard policy, use the addLimitConstraint() method.
  41
  42 ```java
  43                 Map<String, String> time_in_range = new HashMap<String, String>();
  44                 time_in_range.put("arg2", "PT5H");
  45                 time_in_range.put("arg3", "PT24H");
  46                 List<String> blacklist = new LinkedList<String>();
  47                 blacklist.add("vm_name_1");
  48                 blacklist.add("vm_name_2");
  49                 Constraint cons = new Constraint(5, "PT15M", time_in_range, blacklist);
  50                 builder = builder.addLimitConstraint(policy.id, cons);
  51 ```
  52
  53
  54 # Build the YAML Specification
  55
  56 When finished defining the Guard Policies, build the specification and analyze the [Results.java](src/main/java/com/att/ecomp/policy/controlloop/policy/builder/Results.java)
  57
  58 ```java
  59                 Results results = builder.buildSpecification();
  60                 if (results.isValid()) {
  61                         System.out.println(results.getSpecification());
  62                 } else {
  63                         System.err.println("Builder failed");
  64                         for (Message message : results.getMessages()) {
  65                                 System.err.println(message.getMessage());
  66                         }
  67                 }
  68 ```
  69
  70 # Sample Code
  71
  72 Sample code is available in this project: https://codecloud.web.att.com/projects/ST_POLICY/repos/com.att.ecomp.policy.controlloop.sample/browse
  73
  74
  75
  76 # Use the YAML Specification to Generate the XACML Guard Policies
  77
  78 Now that you have a valid YAML specification, call the method in [PolicyGuardYamlToXacml.java](guard/src/main/java/com/att/ecomp/policy/guard/PolicyGuardYamlToXacml.java) to generate the XACML Guard Policies.
  79
  80 # YAML Specification
  81
  82 The YAML specification has 2 sections to it: [guard](#guard-object) and [guards](#guards-array). The [guard section](#guard-object) section is simply a header defining the version of this guard. The [guards section](#guards-array) is simply an array of [GuardPolicy objects](#guardpolicy-object).
  83
  84 ## guard Object
  85
  86 | Field Name      | Type          | Required   | Description  |
  87 | -------------   |:-------------:| -----------| ------------:|
  88 | version         | string        | required   | Value for this release if 2.0.0 |
  89
  90
  91 ## guards array
  92
  93 The guards section is an array of [GuardPolicy objects](#guardpolicy-object).
  94
  95 ### GuardPolicy Object
  96
  97 | Field Name      | Type          | Required   | Description  |
  98 | -------------   |:-------------:| -----------| ------------:|
  99 | id              | string        | required   | Unique ID for the policy. |
 100 | name            | string        | required   | Policy name |
 101 | description     | string        | optional   | Policy description |
 102 | actor           | string        | required   | Name of the actor for this operation: Example: APPC |
 103 | recipe          | string        | required   | Name of recipe to be performed. Example "Restart" |
 104 | limit_constraints  | array of [constraint](#constraint-object) object | required | Constraints used to enforce the guard policy |
 105
 106 The guard policy is bound to a specific recipe performed by the actor. When the Control Loop tries to perform the recipe operation by the actor, this guard policy should be evaluated against all the specified constraints. If any of the constraints will be violated, the operation should be abandoned.
 107
 108 #### constraint Object
 109
 110 | Field Name      | Type          | Required   | Description  |
 111 | -------------   |:-------------:| -----------| ------------:|
 112 | num             | integer       | required if blacklist is not specified  | The limited number of the same operations |
 113 | duration        | string        | required if blacklist is not specified  | Time window for counting the same operations |
 114 | time_in_range   | map<string, string> | optional   | Valid time spans for enforcing the guard policy |
 115 | blacklist       | array of string     | required if num and duration are not specified | A list of the entity names that should not be touched by the Control Loop |
 116
 117 The first three attributes define the frequency limiter which means that only a limited number of the same operations can be allowed within each valid time window. The last attribute defines a blacklist of the target entities on which the Control Loop should not perform the operation.
 118
 119 The "duration" parameter should have one of the following values: [5min, 10min, 30min, 1h, 12h, 1d, 5d, 1w, 1mon].
 120
 121
 122 ## Examples of YAML Control Loop Guards for 1707
 123
 124 [1707-vUSP-Guard](src/test/resources/v2.0.0-guard/policy_guard_vUSP_1707_appc.yaml)
 125 [1707-eNodeB-Ericsson-Frequency-Limiter-Guard](template.enodeb/src/test/resources/policy_guard_eNodeB_1707_sdnr_reset.yaml)
 126 [1707-eNodeB-Ericsson-Blacklist-Guard](template.enodeb/src/test/resources/policy_guard_vUSP_1707_sdnr_reset_blacklist.yaml)
 127 [OpenECOMP-vDNS-Guard](src/test/resources/v2.0.0-guard/policy_guard_OpenECOMP_demo_vDNS.yaml)
 128
 129
 130 ### 1707 vUSP Guard
 131 ```
 132 guard:
 133   version: 2.0.0
 134
 135 guards:
 136   - id: unique_guard_vUSP_1
 137     name: APPC 5 Restart
 138     description:
 139       We only allow 5 restarts over 15 minute window during the day time hours (i.e. avoid midnight to 5am)
 140     actor: APPC
 141     recipe: Restart
 142     limit_constraints:
 143       - num: 5
 144         duration: PT15M
 145         time_in_range:
 146           arg2: PT5H
 147           arg3: PT24H
 148 ```
 149
 150 ### 1707 eNodeB Ericsson Frequency Limiter Guard
 151 ```
 152 guard:
 153   version: 2.0.0
 154
 155 guards:
 156   - id: unique_guard_eNodeB_Ericsson
 157     name: SDNR 1 Reset
 158     description: |
 159       We only allow 1 reset over 24 hour window
 160     actor: SDNR
 161     recipe: Reset
 162     limit_constraints:
 163       - num: 100
 164         duration: 1d
 165         time_in_range:
 166           arg2: 00:00:00-05:00
 167           arg3: 23:59:59-05:00
 168 ```
 169
 170 ### 1707 eNodeB Ericsson Blacklist Guard
 171 ```
 172 guard:
 173   version: 2.0.0
 174
 175 guards:
 176   - id: unique_guard_eNodeB_Ericsson_Blacklist
 177     name: SDNR Reset Blacklist
 178     description: |
 179       We deny restart of the blacklisted targets (avoid midnight to 5am)
 180     actor: APPC
 181     recipe: Reset
 182     limit_constraints:
 183       - blacklist:
 184           - HNVJAL22_DMH1_U_L
 185           - MNYKAQ35_DMH1_U_L
 186         time_in_range:
 187           arg2: 00:00:00-05:00
 188           arg3: 23:59:59-05:00
 189 ```
 190
 191 ### OpenECOMP vDNS Guard
 192 ```
 193 guard:
 194   version: 2.0.0
 195
 196 guards:
 197   - id: unique_guard_ONAP_vDNS_1
 198     name: MSO Spinup
 199     description: We only spin up 1 instance over a 10 minute window
 200     actor: MSO
 201     recipe: VF Module Create
 202     limit_constraints:
 203       - num: 1
 204         duration: PT10M
 205 ```
 206