Merge "Added validation on matching required fields"
[policy/engine.git] / docs / platform / oofSpec.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 Specification and Retrieval for OOF
6 ******************************************
7
8 .. contents::
9     :depth: 2
10
11 Introduction
12 ^^^^^^^^^^^^
13
14 The OOF retrieves applicable constraints and objective functions as policies from the policy platform. 
15 These policies are retrieved at runtime, thus allowing an operator to change policies as and when needed. 
16 These policies are specified using policy models that are on-boarded during the OOF application deployment-time in the policy platform. 
17 The OOF-related policy models are typically derived from the constraints and objective functions of an OOF-application. 
18 Currently, for R2, these models will be pushed into the policy platform manually using the OOF policy uploader module.
19
20 Policy Platform
21 ^^^^^^^^^^^^^^^
22
23 The OOF currently relies on the following features of the policy platform: 
24
25 * **Policy specification:** Optimization constraints and objective functions can be specified in terms of policies by service providers and operators.
26 * **Policy prioritization:** Policies capturing constraints and objectives can be prioritized.
27 * **Policy searching and filtering:** OOF policies can be searched and filtered based on different criteria; by scope or by name patterns
28
29 OOF-HAS Service Design Policies
30 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
31
32 Service design policies are typically defined as a part of a service design model and evaluated/enforced prior to the service instantiation phase. For example, Hardware Platform Enablement (HPA) policies are defined in an SDC service model and evaluated/enforced during the homing optimization process in ONAP. 
33
34 The HPA requirements are captured in a VNF descriptor provided by a vendor. During the service-design phase, these requirements are extracted out from the VNF descriptor and captured in a service model. Some of the HPA requirements cannot be changed during the lifecycle of a service; while other optional requirements can be changed by a service designer or operator over time (e.g. the use of SR-IOV may be preferred by an operator if the SR-IOV capability is optionally provided by a vendor). Once a service model is designed and uploaded into the SDC repository, SDC notifies the policy service about the distribution of a new service model. The policy service then fetches the service model and extracts out the HPA requirements through model decomposition. Next, the policy service creates HPA policies for the homing service (OOF-HAS) by populating the HPA requirements in policy models provided by OOF, and stores the policies in a repository. When the homing service receives a homing request from SO, the homing service asks for the associated HPA policies from the policy platform. Finally, the homing service finds homing solutions based on the evaluation of the received HPA policies and returns the solutions to SO.
35
36 Note that all HPA requirements for a given VM can be put in one policy or across different policies. Also, each HPA capability can be enhanced to include mandatory and score attributes. Keeping this in mind, HPA capabilities are defined here. As indicated, policy can have multiple capabilities.
37
38
39 .. code-block:: bash
40    :caption: Template for the HPA policies
41    :linenos:
42
43     {
44         "service": "{the model name of a policy}",
45         "policyName": "{policy scope folder}.{policy name; must be unique}",
46         "description": "{description of a policy}",
47         "templateVersion": "{policy model version}",
48         "version": "{policy version}",
49         "priority": "{priority in 1-10; larger the number higher the priority is}",
50         "riskType": "{the type of risk}",
51         "riskLevel": "{the level of risk}",
52         "guard": "{True/False flag to indicate whether guard is applicable or not}",
53         "content": { 
54           "resource": "{resource name}",
55           "identity": "{policy identity}",
56           "policyScope": ["{a tag representing policy scope}"],
57           "policyType": "{policy type}",
58           "flavorFeatures": [
59             {
60               "flavorLabel": "{VM/VFC id}",
61               "flavorProperties":[
62                 {
63                   "hpa-feature" : "{HPA feature type}",
64                   "mandatory" : "{mandatoriness of the feature}",
65                   "score" : "{priority of this feature if the feature is not mandatory for VM}"
66                   "architecture": "{supported architecuture}",
67                   "hpa-version": "{version for hpa capability}",
68                   "hpa-feature-attributes": [
69                     {
70                       "hpa-attribute-key": "{attribute name}", 
71                       "hpa-attribute-value": "{attribute value}",
72                       "operator": "{comparison operator}", 
73                       "unit": "{the unit of an attribute}"}
74                   ]
75                 }
76               ] 
77             }
78           ]
79         }
80     }
81
82
83 .. code-block:: bash
84    :caption: HPA Policy Example
85    :linenos:
86     
87     # NOTE:
88     #
89     # The fields in this example policy are typically generated from a TOSCA service model specified by 
90     # VNF vendors or service designers. 
91     # This policy cannot be changed during the life-cycle of a service.
92     #
93     # CPUTHREADPOLICY = prefer, isolate, require
94     # CPUPOLICY = shared, dedicated
95     # PCIETYPEVALUE: SRIOV, PCI-PASSTHROUGH
96     # CPUINST = aes, avx, sha_ni, mpx, adcx, mpx, pclmulqdq, rdrand,sse, etc
97     # MEMORYPAGESIZE = 4KB (unit=KB), 2MB (unit=MB), 1GB(unit=GB), ANY, Other explicit Page size
98
99     {
100         "service": "hpaPolicy",
101         "policyName": "oofBeijing.hpaPolicy_vGMuxInfra",
102         "description": "HPA policy for vGMuxInfra",
103         "templateVersion": "0.0.1",
104         "version": "1.0",
105         "priority": "3",
106         "riskType": "test",
107         "riskLevel": "2",
108         "guard": "False",
109         "content": { 
110           "resources": "vGMuxInfra",
111           "identity": "hpaPolicy_vGMuxInfra",
112           "policyScope": ["vCPE", "US", "INTERNATIONAL", "ip", "vGMuxInfra"],
113           "policyType": "hpaPolicy",
114           "flavorFeatures": [
115             {
116               "flavorLabel": "flavor_label_vm_01",
117               "flavorProperties":[
118                 {
119                   "hpa-feature" : "cpuTopology",
120                   "mandatory" : "True",
121                   "architecture": "generic",
122                   "hpa-version": "v1",
123                   "hpa-feature-attributes": [
124                     {"hpa-attribute-key":"numCpuSockets", 
125                      "hpa-attribute-value":"2","operator": ">=", "unit":""},
126                     {"hpa-attribute-key":"numCpuSockets", 
127                      "hpa-attribute-value":"4","operator": "<=", "unit":""},
128                     {"hpa-attribute-key":"numCpuCores", 
129                      "hpa-attribute-value":"2", "operator":">=", "unit":""},
130                     {"hpa-attribute-key":"numCpuCores", 
131                      "hpa-attribute-value":"4", "operator":"<=", "unit":""},
132                     {"hpa-attribute-key":"numCpuThreads", 
133                      "hpa-attribute-value":"4", "operator":">=", "unit":""},
134                     {"hpa-attribute-key":"numCpuThreads", 
135                      "hpa-attribute-value":"8", "operator":"<=", "unit":""}
136                   ]
137                 },
138                 {
139                   "hpa-feature" : "basicCapabilities",
140                   "mandatory" : "True",
141                   "architecture": "generic",
142                   "hpa-version": "v1",
143                   "hpa-feature-attributes": [
144                     {"hpa-attribute-key":"numVirtualCpu", 
145                      "hpa-attribute-value":"6", "operator":"=", "unit":""},
146                     {"hpa-attribute-key":"virtualMemSize", 
147                      "hpa-attribute-value":"6", "operator":"=", "unit":"GB"}
148                   ]
149                 },
150                 {
151                   "hpa-feature" : "ovsDpdk",
152                   "mandatory" : "False",
153                   "score" : "3",
154                   "architecture": "generic",
155                   "hpa-version": "v1",
156                   "hpa-feature-attributes": [
157                      {"hpa-attribute-key":"dataProcessingAccelerationLibrary", 
158                       "hpa-attribute-value":"ovsDpdk_version", "operator": "=", "unit":""}
159                   ]
160                 },
161                 {
162                   "hpa-feature" : "cpuInstructionSetExtensions",
163                   "mandatory" : "True",
164                   "architecture": "INTEL-64",
165                   "hpa-version": "v1",
166                   "hpa-feature-attributes": [
167                     {"hpa-attribute-key":"instructionSetExtensions", 
168                      "hpa-attribute-value":["<CPUINST>", "<CPUINST>"] "operator": "ALL", "unit":""}
169                   ]
170                 }
171               ] 
172             },
173             {
174               "flavorLabel": "flavor_label_vm_02",
175               "flavorProperties":[
176                 {
177                   "hpa-feature" : "cpuPinningy",
178                   "mandatory" : "True",
179                   "architecture": "generic",
180                   "hpa-version": "v1",
181                   "hpa-feature-attributes": [
182                     {"hpa-attribute-key":"logicalCpuThreadPinningPolicy", 
183                      "hpa-attribute-value":"<CPUTHREADPOLICY>", "operator": "=", "unit":""},
184                     {"hpa-attribute-key":"logicalCpuPinningPolicy", 
185                      "hpa-attribute-value": "<CPUPOLICY>","operator": "=", "unit":""},
186                   ]
187                 },
188                 {
189                   "hpa-feature" : "basicCapabilities",
190                   "mandatory" : "True",
191                   "architecture": "generic",
192                   "hpa-version": "v1",
193                   "hpa-feature-attributes": [
194                     {"hpa-attribute-key": "numVirtualCpu", 
195                      "hpa-attribute-value": "6", "operator": "=", "unit": ""},
196                     {"hpa-attribute-key": "virtualMemSize", 
197                      "hpa-attribute-value":"6", "operator": "=", "unit": "GB"}
198                   ]
199                 },
200                 {
201                   "hpa-feature" : "localStorage",
202                   "mandatory" : "False",
203                   "score" : "5",
204                   "architecture": "generic",
205                   "hpa-version": "v1",
206                   "hpa-feature-attributes": [
207                     {"hpa-attribute-key": "diskSize", 
208                      "hpa-attribute-value": "2", "operator": "=", "unit": "GB"},   
209                     {"hpa-attribute-key": "ephemeralDiskSize", 
210                      "hpa-attribute-value": "2", "operator": "=", "unit": "GB"},
211                     {"hpa-attribute-key": "swapMemSize", 
212                      "hpa-attribute-value":"16", "operator": "=", "unit": "MB"},
213                   ]
214                 },
215                 {
216                   "hpa-feature" : "pcie",
217                   "mandatory" : "True",
218                   "architecture": "generic",
219                   "hpa-version": "v1",
220                   "hpa-feature-attributes": [
221                     {"hpa-attribute-key": "pciCount", 
222                      "hpa-attribute-value": "2", "operator": "=", "unit": ""},
223                     {"hpa-attribute-key": "pciVendorId", 
224                      "hpa-attribute-value":"8086", "operator": "=", "unit": ""},
225                     {"hpa-attribute-key": "pciDeviceId", 
226                      "hpa-attribute-value": "2", "operator": "=", "unit": ""} 
227                     {"hpa-attribute-key": "functionType", 
228                      "hpa-attribute-value": "<PCITYPEVALUE>","operator": "=", "unit": ""} 
229                   ]
230                 }
231               ] 
232             },
233             {
234               "flavorLabel": "flavor_label_vm_03",
235               "flavorProperties":[
236                 {
237                   "hpa-feature" : "numa",
238                   "mandatory" : "False",
239                   "score" : "5",
240                   "architecture": "generic",
241                   "hpa-version": "v1",
242                   "hpa-feature-attributes": [
243                     {"hpa-attribute-key": "numaNodes", 
244                      "hpa-attribute-value": "2", "operator": "=", "unit": ""},
245                     {"hpa-attribute-key": "numaCpu-0", 
246                      "hpa-attribute-value":"2", "operator": "=", "unit": ""},
247                     {"hpa-attribute-key": "numaMem-0", 
248                      "hpa-attribute-value": "2048", "operator": "=", "unit": "MB"}
249                     {"hpa-attribute-key": "numaCpu-1", 
250                      "hpa-attribute-value":"4", "operator": "=", "unit": ""},
251                     {"hpa-attribute-key": "numaMem-1", "value": "4096", "operator": "=", "unit": "MB"}
252                   ]
253                 },
254                 {
255                   "hpa-feature" : "basicCapabilities",
256                   "mandatory" : "True",
257                   "architecture": "generic",
258                   "hpa-version": "v1",
259                   "hpa-feature-attributes": [
260                     {"hpa-attribute-key": "numVirtualCpu", 
261                      "hpa-attribute-value": "6", "operator": "=", "unit": ""},
262                     {"hpa-attribute-key": "virtualMemSize", 
263                      "hpa-attribute-value":"6", "operator": "=", "unit": "GB"}
264                   ]
265                 },
266                 {
267                   "hpa-feature" : "hugePages",
268                   "mandatory" : "False",
269                   "score" : "7",
270                   "architecture": "generic",
271                   "hpa-version": "v1",
272                   "hpa-feature-attributes": [
273                      {"hpa-attribute-key": "memoryPageSize", 
274                       "hpa-attribute-value": "<MEMORYPAGESIZE>", "operator": "=", "unit": ""}
275                   ]
276                 }
277               ] 
278             }
279           ]
280         }
281     }
282     
283
284 .. code-block:: bash
285    :caption: Distance Policy Example
286    :linenos:
287         
288     # NOTE:
289     #
290     # The fields in this example policy are typically generated from a TOSCA service model specified by 
291     # VNF vendors or service designers. However, the policy can be updated over time by operators.
292
293     {
294       "service": "distancePolicy",
295       "policyName": "oofBeijing.distancePolicy_vGMuxInfra",
296       "description": "Distance Policy for vGMuxInfra",
297       "templateVersion": "0.0.1",
298       "version": "oofBeijing",
299       "priority": "3",
300       "riskType": "test",
301       "riskLevel": "2",
302       "guard": "False",
303       "content": {
304         "distanceProperties": {
305           "locationInfo": customer_location",
306           "distance": { "value": "500", "operator": "<", "unit": "km" }
307         },
308         "resources": ["vGMuxInfra", "vG"],
309         "applicableResources": "any",
310         "identity": "distance-vGMuxInfra",
311         "policyScope": ["vCPE", "US", "INTERNATIONAL", "ip", "vGMuxInfra"],
312         "policyType": "distancePolicy"
313       }
314     }
315     
316
317 .. code-block:: bash
318    :caption: HPA Basic Capabilities Policy Example
319    :linenos:
320             
321     # NOTE:
322     #
323     # The fields in this example policy are typically generated from a TOSCA service model specified by 
324     # VNF vendors or service designers. 
325     # This policy cannot be changed during the life-cycle of a service.
326
327     {
328         "hpa-feature" : "basicCapabilities",
329         "mandatory" : "False",
330         "score" : "5",
331         "architecture": "generic",
332         "hpa-version": "v1",
333         "hpa-feature-attributes": [
334            {"hpa-attribute-key": "numVirtualCpu", 
335                      "hpa-attribute-value": "6", "operator": "=", "unit": ""},
336            {"hpa-attribute-key": "virtualMemSize", 
337                      "hpa-attribute-value":"6", "operator": "=", "unit": "GB"}
338         ]
339     }
340     
341
342 .. code-block:: bash
343    :caption: HPA OVS DPDK Policy Example
344    :linenos:
345     
346     # NOTE:
347     #
348     # The fields in this example policy are typically generated from a TOSCA service model specified by 
349     # VNF vendors or service designers. 
350     # This policy cannot be changed during the life-cycle of a service.
351     #
352     # For this policy others architectures are also applicable.
353
354     {
355         "hpa-feature" : "ovsDpdk",
356         "mandatory" : "False",
357         "score" : "5",
358         "architecture": "INTEL-64",
359         "hpa-version": "v1",
360         "hpa-feature-attributes": [
361           {"hpa-attribute-key":"dataProcessingAccelerationLibrary", 
362            "hpa-attribute-value":"ovsDpdk_version", "operator": "=", "unit":""}
363          ]
364     }
365     
366
367 .. code-block:: bash
368    :caption: HPA CPU Pinning Policy Example
369    :linenos:
370         
371     # NOTE:
372     #
373     # The fields in this example policy are typically generated from a TOSCA service model specified by 
374     # VNF vendors or service designers. 
375     # This policy cannot be changed during the life-cycle of a service.
376
377     {
378        "hpa-feature" : "cpuPinning",
379        "mandatory" : "False",
380        "score" : "5",
381        "architecture": "generic",
382        "hpa-version": "v1",
383        "hpa-feature-attributes": [
384          {"hpa-attribute-key":"logicalCpuThreadPinningPolicy", 
385           "hpa-attribute-value":"<CPUTHREADPOLICY>", "operator": "=", "unit":""},
386          {"hpa-attribute-key":"logicalCpuPinningPolicy", 
387           "hpa-attribute-value": "<CPUPOLICY>","operator": "=", "unit":""},
388         ]
389     }
390     
391
392 .. code-block:: bash
393    :caption: HPA NUMA Policy Example
394    :linenos:
395             
396     # NOTE:
397     #
398     # The fields in this example policy are typically generated from a TOSCA service model specified by 
399     # VNF vendors or service designers. 
400     # This policy cannot be changed during the life-cycle of a service.
401
402     {
403         "hpa-feature" : "numa",
404         "mandatory" : "False",
405         "score" : "5",
406         "architecture": "generic",
407         "hpa-version": "v1",
408         "hpa-feature-attributes": [
409            {"hpa-attribute-key": "numaNodes", 
410             "hpa-attribute-value": "2", "operator": "=", "unit": ""},
411            {"hpa-attribute-key": "numaCpu-0", 
412             "hpa-attribute-value":"2", "operator": "=", "unit": ""},
413            {"hpa-attribute-key": "numaMem-0", 
414             "hpa-attribute-value": "2048", "operator": "=", "unit": "MB"},
415            {"hpa-attribute-key": "numaCpu-1", 
416             "hpa-attribute-value":"4", "operator": "=", "unit": ""},
417            {"hpa-attribute-key": "numaMem-1", 
418             "hpa-attribute-value": "4096", "operator": "=", "unit": "MB"}
419         ]
420     }
421     
422
423 .. code-block:: bash
424    :caption: HPA CPU Topology Policy Example
425    :linenos:
426     
427     # NOTE:
428     #
429     # The fields in this example policy are typically generated from a TOSCA service model specified by 
430     # VNF vendors or service designers. 
431     # This policy cannot be changed during the life-cycle of a service.
432
433     {
434        "hpa-feature" : "cpuTopology",
435        "mandatory" : "False",
436        "score" : "5",
437        "architecture": "generic",
438        "hpa-version": "v1",
439        "hpa-feature-attributes": [
440           {"hpa-attribute-key":"numCpuSockets", 
441            "hpa-attribute-value": "2","operator": ">=", "unit": ""},
442           {"hpa-attribute-key":"numCpuSockets", 
443            "hpa-attribute-value": "4","operator": "<=", "unit": ""},
444           {"hpa-attribute-key":"numCpuCores", 
445            "hpa-attribute-value": "2", "operator":">=", "unit": ""},
446           {"hpa-attribute-key":"numCpuCores", 
447            "hpa-attribute-value": "4", "operator":"<=", "unit": ""},
448           {"hpa-attribute-key":"numCpuThreads", 
449            "hpa-attribute-value": "4", "operator":">=", "unit": ""},
450           {"hpa-attribute-key":"numCpuThreads", 
451            "hpa-attribute-value": "8", "operator":"<=", "unit": ""}
452        ]
453     }
454     
455
456 .. code-block:: bash
457    :caption: Affinity Policy Example
458    :linenos:
459         
460     # NOTE:
461     #
462     # The fields in this example policy are typically generated from a TOSCA service model specified by 
463     # VNF vendors or service designers. This policy cannot be changed during the life-cycle of a service.
464
465     {
466         "service": "affinityPolicy",
467         "policyName": "oofBeijing.affinityPolicy_vcpe",
468         "description": "Affinity policy for vCPE",
469         "templateVersion": "1702.03",
470         "version": "oofBeijing",
471         "priority": "5",
472         "riskType": "test",
473         "riskLevel": "2",
474         "guard": "False",
475         "content": {
476             "identity": "affinity_vCPE",
477             "policyScope": ["vCPE", "US", "INTERNATIONAL", "ip", "vGMuxInfra"],
478             "affinityProperties": {
479                 "qualifier": "different",
480                 "category": "complex"
481             },
482             "policyType": "affinityPolicy",
483             "resources": ["vGMuxInfra", "vG"],
484             "applicableResources": "all"
485         }
486     }
487     
488
489 .. code-block:: bash
490    :caption: Capacity Policy Example
491    :linenos:
492             
493     # NOTE:
494     #
495     # The fields in this example policy are typically generated from a TOSCA service model specified by 
496     # VNF vendors or service designers. This policy cannot be changed during the life-cycle of a service.
497
498     {
499         "service": "capacityPolicy",
500         "policyName": "oofBeijing.capacityPolicy_vGMuxInfra",
501         "description": "Capacity policy for vGMuxInfra",
502         "templateVersion": "1702.03",
503         "version": "oofBeijing",
504         "priority": "5",
505         "riskType": "test",
506         "riskLevel": "2",
507         "guard": "False",
508         "content": {
509             "identity": "capacity_vGMuxInfra",
510             "policyScope": ["vCPE", "US", "INTERNATIONAL", "ip", "vGMuxInfra"],
511             "controller": "multicloud",
512             "capacityProperties": {
513                 "cpu": {"value": 2, "operator": ">"},
514                 "memory": {"value": 4, "operator": ">", "unit": "GB"}
515                 "storage": {"value": 80, "operator": ">", "unit": "GB"}
516             },
517             "policyType": "vim_fit",
518             "resources": ["vGMuxInfra"],
519             "applicableResources": "any"
520         }
521     }
522     
523
524 .. code-block:: bash
525    :caption: Min Guarantee Policy Example
526    :linenos:
527                 
528     # NOTE:
529     #
530     # The fields in this example policy are typically generated from a TOSCA service model specified by 
531     # VNF vendors or service designers.  This policy cannot be changed during the life-cycle of a service. 
532     # A min-guarantee policy can be specified using the HPA policy model.
533
534     {
535         "service": "minGuaranteePolicy",
536         "policyName": "oofBeijing.minGuaranee_vGMuxInfra",
537         "description": "Min guarantee policy for vGMuxInfra",
538         "templateVersion": "1702.03",
539         "version": "oofBeijing",
540         "priority": "5",
541         "riskType": "test",
542         "riskLevel": "2",
543         "guard": "False",
544         "content": {
545             "identity": "minGuarantee_vGMuxInfra",
546             "policyScope": ["vCPE", "US", "INTERNATIONAL", "ip", "vGMuxInfra"],
547             "minGuaranteeProperty": {
548                 "cpu": "true",
549                 "memory": "false",
550             },
551             "type": "minGuaranteePolicy",
552             "resources": ["vGMuxInfra"],
553             "applicableResources": "any"
554         }
555     }
556     
557
558 .. code-block:: bash
559    :caption: Optimization Policy Example
560    :linenos:
561                 
562     # NOTE:
563     #
564     # The fields in this example policy are typically generated from a TOSCA service model specified by 
565     # VNF vendors or service designers.  This policy cannot be changed during the life-cycle of a service. 
566                     
567     {
568         "service": "PlacementOptimizationPolicy",
569         "policyName": "oofBeijing.PlacementOptimizationPolicy_vGMuxInfra",
570         "description": "Placement Optimization Policy for vGMuxInfra",
571         "templateVersion": "1702.03",
572         "version": "oofBeijing",
573         "priority": "5",
574         "riskType": "test",
575         "riskLevel": "3",
576         "guard": "False",
577         "content": {
578             "objectiveParameter": {
579                 "parameterAttributes": [
580                     {
581                         "resources": ["vGMuxInfra"],
582                         "customerLocationInfo": "customer_loc",
583                         "parameter": "distance",
584                         "weight": "1",
585                         "operator": "product"=
586                     },
587                     {
588                         "resources": ["vG"],
589                         "customerLocationInfo": "customer_loc",
590                         "parameter": "distance",
591                         "weight": "1",
592                         "operator": "product"
593                     }
594                 ],
595                 "operator": "sum"
596             },
597             "identity": "optimization",
598             "policyScope": ["vCPE", "US", "INTERNATIONAL", "ip", "vGMuxInfra"],
599             "policyType": "placementOptimization",
600             "objective": "minimize"
601         }
602     }
603
604
605 .. code-block:: bash
606    :caption: HPA PCIe Policy Example
607    :linenos:
608     
609     # NOTE:
610     #
611     # PCIETYPEVALUE: SRIOV, PCI-PASSTHROUGH
612
613     {
614         "hpa-feature" : "pcie",
615         "mandatory" : "False",
616         "score" : "5",
617         "architecture": "generic",
618         "hpa-version": "v1",
619         "hpa-feature-attributes": [
620           {"hpa-attribute-key": "pciCount", "hpa-attribute-value": "2", "operator": "=", "unit": ""},
621           {"hpa-attribute-key": "pciVendorId", "hpa-attribute-value":"8086", "operator": "=", "unit": ""},
622           {"hpa-attribute-key": "pciDeviceId", "hpa-attribute-value": "2", "operator": "=", "unit": ""} 
623           {"hpa-attribute-key": "functionType", 
624            "hpa-attribute-value": "<PCIETYPEVALUE>","operator": "=", "unit": ""} 
625          ]
626     }
627     
628
629 .. code-block:: bash
630    :caption: HPA Local Storage Policy Example
631    :linenos:
632                 
633     # NOTE:
634     #
635     # The fields in this example policy are typically generated from a TOSCA service model specified by 
636     # VNF vendors or service designers.  
637     # This policy cannot be changed during the life-cycle of a service. 
638
639     {
640         "hpa-feature" : "localStorage",
641         "mandatory" : "False",
642         "score" : "5",
643         "architecture": "generic",
644         "hpa-version": "v1",
645         "hpa-feature-attributes": [
646            {"hpa-attribute-key": "diskSize", 
647             "hpa-attribute-value": "2", "operator": "=", "unit": "GB"},   
648            {"hpa-attribute-key": "ephemeralDiskSize", 
649             "hpa-attribute-value": "2", "operator": "=", "unit": "GB"},
650            {"hpa-attribute-key": "swapMemSize", 
651             "hpa-attribute-value":"16", "operator": "=", "unit": "MB"},
652          ]
653     }
654     
655
656 .. code-block:: bash
657    :caption: HPA CPU Instruction Set Extensions Policy Example
658    :linenos:
659                 
660     # NOTE:
661     #
662     # instructionSetExtensions attribute has a list of all instruction set extensions required. 
663     # CPUINST = aes, avx, sha_ni, mpx, adcx, mpx, pclmulqdq, rdrand, sse, etc
664                     
665     {
666         "hpa-feature" : "cpuInstructionSetExtensions",
667         "mandatory" : "False",
668         "score" : "5",
669         "architecture": "INTEL-64",
670         "hpa-version": "v1",
671         "hpa-feature-attributes": [
672           {"hpa-attribute-key":"instructionSetExtensions", 
673            "hpa-attribute-value":["<CPUINST>", "<CPUINST>"] "operator": "ALL", "unit":""}
674          ]
675     }
676     
677
678 .. code-block:: bash
679    :caption: HPA Huge Pages Policy Example
680    :linenos:
681                 
682     # NOTE:
683     #
684     # MEMORYPAGESIZE = 4KB (unit=KB), 2MB (unit=MB), 1GB(unit GB), ANY, Other explicit Page size
685                     
686     {
687         "hpa-feature" : "hugePages",
688         "mandatory" : "False",
689         "score" : "5",
690         "architecture": "generic",
691         "hpa-version": "v1",
692         "hpa-feature-attributes": [
693           {"hpa-attribute-key": "memoryPageSize", 
694            "hpa-attribute-value": "<MEMORYPAGESIZE>", "operator": "=", "unit": ""}
695         ]
696     }
697     
698
699 .. code-block:: bash
700    :caption: VNF Policy Example
701    :linenos:
702                 
703     # NOTE:
704     #
705     # VNF policy captures the location of inventories and customer information.
706                     
707     {
708         "service": "vnfPolicy",
709         "policyName": "oofBeijing.vnfPolicy_vGMuxInfra",
710         "description": "vnfPolicy",
711         "templateVersion": "1702.03",
712         "version": "oofBeijing",
713         "priority": "6",
714         "riskType": "test",
715         "riskLevel": "3",
716         "guard": "False",
717         "content": {
718             "identity": "vnf_vGMuxInfra",
719             "policyScope": ["vCPE", "INTERNATIONAL", "ip", "vGMuxInfra"],
720             "policyType": "vnf_policy",
721             "resources": ["vGMuxInfra"],
722             "applicableResources": "any",
723             "vnfProperties": [
724                 {
725                     "inventoryProvider": "aai",
726                     "serviceType": "",
727                     "inventoryType": "cloudRegionId",
728                     "customerId": ""
729                 },
730                 {
731                     "inventoryProvider": "multicloud",
732                     "serviceType": "HNGATEWAY",
733                     "inventoryType": "serviceInstanceId",
734                     "customerId": "21014aa2-526b-11e6-beb8-9e71128cae77"
735                 }
736             ]
737         }
738     }
739     
740
741 .. code-block:: bash
742    :caption: Subscriber Role Policy Example
743    :linenos:
744                 
745     # NOTE:
746     #
747     # Subscriber role policy to capture the role of a subscriber and related provisioning states.
748     
749     {
750      "service": "SubscriberPolicy",
751      "policyName": "oofBeijing.SubscriberPolicy_v1",
752      "description": "Subscriber Policy",
753      "templateVersion": "0.0.1",
754      "version": "oofBeijing",
755      "priority": "1",
756      "riskType": "test",
757      "riskLevel": "3",
758      "guard": "False",
759      "content": {
760             "identity": "subscriber",
761             "policyScope": ["vCPE", "subscriber_x", "subscriber_y"],
762             "properties": {
763                     "subscriberName": ["subscriber_x", "subscriber_y"],
764                     "subscriberRole": ["Test"],
765                     "provStatus": ["CAPPED"]
766             },
767             "policyType": "SubscriberPolicy"
768      }
769     }
770     
771
772 Modes for Fetching Policies
773 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
774
775 OOF can fetch optimzation policies using the getConfig API of the policy system. The policies can be searched and filtered in two different modes; by-name and by-scope from the policy system.
776
777 **By-name**: OOF can send an explicite policy name or a regular expression matching a set of policy names as a part of the getConfig API payload. In return, OOF expects to receive a specific policy or a set of policies with name matching to the regular expression.
778
779 **By-scope**: A scope is the domain to which a policy is applicable. Scope information can be captured as a set of attribute-value pairs, which can be sent as a part of the getConfig API payload. In response, the policy system is expected to return a set of policies with the matching attribute-value pairs. A policy can only be included in the response if all the matching attribute-value pairs exist.
780
781 OOF can requerst prioritization by enabling a prioritization flag in the getConfig API call to the policy system, and expects to receive a single policy with the highest priority policy among the set of policies meeting the search criteria.
782
783
784 TOSCA Policy Models
785 ^^^^^^^^^^^^^^^^^^^
786
787 The following TOSCA policy models need to be uploaded as a dictionary during the deployment-time of an optimization application. Currently, the model uploading porcess is manual since the policy system does not offer an interface to upload models programatically. 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.
788
789 * HPA Policy
790 * Affinity Policy
791 * Distance Policy
792 * Capacity Policy
793 * VNF Policy
794 * Optimization Policy
795 * Query Policy
796 * Subscriber Policy
797
798
799 End of Document
800
801 .. SSNote: Wiki page ref. https://wiki.onap.org/display/DW/Policy+Specification+and+Retrieval+for+OOF
802
803