2d6850cc343ee14d13f1730223cfc7e6070023f2
[policy/engine.git] / docs / platform / oofhpa.rst
1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
2 .. http://creativecommons.org/licenses/by/4.0
3
4 **************
5 Policy OOF HPA 
6 **************
7
8 .. contents::
9     :depth: 2
10
11 Background
12 ^^^^^^^^^^
13
14 The OOF(ONAP Optimization Framework) retrieves applicable constraints and objective functions as policies from the policy platform. These policies are retrieved at runtime, thus allowing an operator to change policies as and when needed. These policies are specified using policy models that are on-boarded during the OOF application deployment-time in the policy platform. The OOF-related policy models are typically derived from the constraints and objective functions of an OOF-application. Currently, for R2, these models will be pushed into the policy platform manually using the OOF policy uploaded module. 
15 Below is an example using HPA (Hardware Platform Awareness). 
16
17 Updating Policy Models
18 ^^^^^^^^^^^^^^^^^^^^^^
19
20 The following HPA TOSCA policy models need to be uploaded as a dictionary during the deployment-time of an optimization application. Currently, the model uploading process is manual since the policy system does not offer an interface to upload models programmatical. Once the models are uploaded, policy templates are created in the policy portal/GUI using which optimization policies can be created. Alternatively, the policy system offers CRUD REST APIs using which the policies can be managed by the application.
21
22 .. code-block:: bash
23    :caption: HPA Policy
24    :linenos:
25
26     tosca_definitions_version: tosca_simple_yaml_1_0_0
27     node_types:
28         policy.nodes.hpaPolicy:
29             derived_from: policy.nodes.Root
30             properties:
31                 policyScope:
32                     type: list
33                     description: scope where the policy is applicable
34                     required: true
35                     matchable: true
36                     entry_schema:
37                         type: string
38                 policyType:
39                     type: list
40                     description: type of a policy
41                     required: true
42                     matchable: true
43                     entry_schema:
44                         type: string
45                         consraints:
46                         -   valid_values:
47                             - hpaPolicy
48                 resource:
49                     type: string
50                     required: true
51                 identity:
52                     type: string
53                     required: true
54                 flavorFeatures:
55                     type: list
56                     required: true
57                     entry_schema:
58                     -   type: policy.data.flavorFeatures_properties
59     data_types:
60         policy.data.flavorFeatures_properties:
61             derived_from: tosca.nodes.Root
62             properties:
63                 flavorLabel:
64                     type: string
65                     required: true
66                 flavorProperties:
67                     type: list
68                     required: true
69                     entry_schema:
70                     -   type: policy.data.flavorProperties_properties
71         policy.data.flavorProperties_properties:
72             derived_from: tosca.nodes.Root
73             properties:
74                 hpa-feature:
75                     type: string
76                     required: true
77                 mandatory:
78                     type: string
79                     required: true
80                 score:
81                     type: string
82                     required: true
83                 architecture:
84                     type: string
85                     required: true
86                 hpa-version:
87                     type: string
88                     required: true
89                 hpa-feature-attributes:
90                     type: list
91                     required: true
92                     entry_schema:
93                     -   type: policy.data.hpa-feature-attributes_properties
94         policy.data.hpa-feature-attributes_properties:
95             derived_from: tosca.nodes.Root
96             properties:
97                 hpa-attribute-key:
98                     type: string
99                     required: true
100                 hpa-attribute-value:
101                     type: string
102                     required: true
103                 operator:
104                     type: list
105                     required: true
106                     entry_schema:
107                         type: string
108                         constraints:
109                         -   valid_values:
110                             - <
111                             - <=
112                             - '>'
113                             - '>='
114                             - '='
115                             - '!='
116                             - any
117                             - all
118                             - subset
119                 unit:
120                     type: string
121                     required: true
122
123
124 The POLICY Dictionary tab is used to create and manage attributes in the dictionaries.
125
126     1. Access to the POLICY GUI via the ONAP Portal. Select Dictionary on the left side.
127     2. Select Policy Type Dictionary. you need choose the Optimization Policy. 
128     3. Select Dictionary. you need Select ONAP Optimization Models.
129     4. Click Import Dictionary's  button, upload the HPA Policy file.
130
131 The image below shows an example of an uploaded policy.
132
133 .. image:: OofHpa_dictionary.png
134
135 Creating HPA Policies
136 ^^^^^^^^^^^^^^^^^^^^^
137
138 There are two options for creating policies: (1) through the GUI and (2) through the restful API.
139
140 GUI Method
141 ----------
142
143 From the POLICY GUI:
144
145 1. Select editor, right click a scope and choose create policy
146 2. Choose Config under Policy Type
147 3. Choose Optimization under Optimization
148 4. Enter  all required fields I for common Config Policy Type:
149
150  * Policy Name
151  * Onap Name - Name of the source of the requests
152  * Guard
153  * Risk Type
154  * Risk Level
155  * Priority
156  * Optimization Model: choose hpaPolicy
157  * Optimization Model Version: CSIT
158
159 5. Enter all required fields II about specified Optimization Config Policy Type:
160 6. Click validate, then save
161
162
163 Below is an example of a policy that uses the HPA feature: hpaPolicy_vGmuxInfra. 
164
165 .. image:: OofHpa_create1.png
166
167 .. image:: OofHpa_create2.png
168
169 API Method
170 ----------
171
172 To create the policy, use the PUT /createPolicy API.  
173 The request should be in the following form for the Optimization policy:
174
175 .. code-block:: json
176    :caption: HPA Policy Json file
177    :linenos:
178
179     {
180         "service": "hpaPolicy",
181         "policyName": "hpaPolicy_vGMuxInfra",
182         "description": "HPA policy for vGMuxInfra",
183         "templateVersion": "0.0.1",
184         "version": "1.0",
185         "priority": "3",
186         "riskType": "SampleRiskType",
187         "riskLevel": "2",
188         "guard": "False",
189         "Optimization Model" : "hpaPolicy",
190         "Optimization Model Version": "CSIT",
191         "content": {
192           "resources": "vGMuxInfra",
193           "identity": "hpaPolicy_vGMuxInfra",
194           "policyScope": ["vCPE", "US", "INTERNATIONAL", "ip", "vGMuxInfra"],
195           "policyType": "hpaPolicy",
196           "flavorFeatures": [
197             {
198               "flavorLabel": "flavor_label_vm_01",
199               "flavorProperties":[
200                 {
201                   "hpa-feature" : "cpuTopology",
202                   "mandatory" : "True",
203                   "architecture": "generic",
204                   "score": 3,
205                   "hpa-feature-attributes": [
206                     {"hpa-attribute-key":"numCpuSockets", "hpa-attribute-value": "2","operator": ">=", "unit": ""}
207                   ]
208                 }
209               ]
210             }
211             ]
212         }
213     }
214
215
216 Push Policy
217 ^^^^^^^^^^^
218
219 Use the Push tab to push the policy and make it active on the pdp-x.
220
221         1. From the web, select Push tab
222         2. Select the polices
223         3. Select the PDP
224         4. Click the Push Polices button
225
226 A message will be displayed indicatng a successful push. 
227
228 .. image:: OofHpa_push.png
229
230
231 Semantics of  Policy attributes
232 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
233
234 .. code-block:: bash
235    :caption: HPA Feature Attributes Semantics
236
237     "hpa-feature-attributes": [
238         {
239           "hpa-attribute-key": "{attribute name}",
240           "hpa-attribute-value": "{attribute value}",
241           "operator": "{comparison operator}",
242           "unit": "{the unit of an attribute}"
243         }
244     ]
245
246
247     # An Example
248
249     "hpa-feature-attributes": [
250       {"hpa-attribute-key":"numCpuSockets", "hpa-attribute-value": "2","operator": ">=", "unit": ""},
251       {"hpa-attribute-key":"numCpuSockets", "hpa-attribute-value": "4","operator": "<=", "unit": ""},
252       {"hpa-attribute-key":"numCpuCores", "hpa-attribute-value": "2", "operator":">=", "unit": ""},
253       {"hpa-attribute-key":"numCpuCores", "hpa-attribute-value": "4", "operator":"<=", "unit": ""},
254       {"hpa-attribute-key":"numCpuThreads", "hpa-attribute-value": "4", "operator":">=", "unit": ""},
255       {"hpa-attribute-key":"numCpuThreads", "hpa-attribute-value": "8", "operator":"<=", "unit": ""}
256     ]
257
258
259 .. seealso:: `Policy Specification and Retrieval for OOF <oofSpec.html>`_
260
261
262 End of Document
263
264 .. SSNote: Wiki page ref. https://wiki.onap.org/display/DW/Policy+OOF+HPA
265
266