summaryrefslogtreecommitdiffstats
path: root/docs/design/design.rst
blob: cceba0fc5a28dd7e587ab34d8575ee7a745dfd09 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
.. This work is licensed under a
.. Creative Commons Attribution 4.0 International License.
.. http://creativecommons.org/licenses/by/4.0

.. _design-label:

Policy Design and Development
#############################

.. contents::
    :depth: 3

This document describes the design principles that should be used to write, deploy, and run policies of various types
using the Policy Framework. It explains the APIs that are available for Policy Framework users. It provides copious
examples to illustrate policy design and API usage.

1 Introduction
==============

The figure below shows the Artifacts (Blue) in the ONAP Policy Framework, the Activities (Yellow) that manipulate them,
and important components (Salmon) that interact with them. The Policy Framework is fully TOSCA compliant, and uses
TOSCA to model policies. Please see the :ref:`TOSCA Policy Primer <tosca-label>` page for an introduction to TOSCA
policy concepts.

.. image:: images/APIsInPolicyFramework.svg

TOSCA defines the concept of a *PolicyType*, the definition of a type of policy that can be applied to a service. It
also defines the concept of a *Policy*, an instance of a *PolicyType*. In the Policy Framework, we handle and manage
these TOSCA definitions and tie them to real implementations of policies that can run on PDPs.

The diagram above outlines how this is achieved. Each TOSCA *PolicyType* must have a corresponding *PolicyTypeImpl* in
the Policy Framework. The TOSCA *PolicyType* definition can be used to create a TOSCA *Policy* definition, either
directly by the Policy Framework, by CLAMP, or by some other system. Once the *Policy* artifact exists, it can be used
together with the *PolicyTypeImpl* artifact to create a *PolicyImpl* artifact. A *PolicyImpl* artifact is an executable
policy implementation that can run on a PDP.

The TOSCA *PolicyType* artifact defines the external characteristics of the policy; defining its properties, the types
of entities it acts on, and its triggers.  A *PolicyTypeImpl* artifact is an XACML, Drools, or APEX implementation of
that policy definition. *PolicyType* and *PolicyTypeImpl* artifacts may be preloaded, may be loaded manually, or may be
created using the Lifecycle API. Alternatively, *PolicyType* definitions may be loaded over the Lifecycle API for
preloaded *PolicyTypeImpl* artifacts. A TOSCA *PolicyType* artifact can be used by clients (such as CLAMP or CLI tools)
to create, parse, serialize, and/or deserialize an actual Policy.

The TOSCA *Policy* artifact is used internally by the Policy Framework, or is input by CLAMP or other systems. This
artifact specifies the values of the properties for the policy and specifies the specific entities the policy acts on.
Policy Design uses the TOSCA *Policy* artifact and the *PolicyTypeImpl* artifact to create an executable *PolicyImpl*
artifact. 

2 ONAP Policy Types
===================

Policy Type Design manages TOSCA *PolicyType* artifacts and their *PolicyTypeImpl* implementations.

A TOSCA *PolicyType* may ultimately be defined by the modeling team but for now are defined by the Policy Framework
project. Various editors and GUIs are available for creating *PolicyTypeImpl* implementations. However, systematic
integration of *PolicyTypeImpl* implementation is outside the scope of the ONAP Dublin release.

The *PolicyType* definitions and implementations listed below are preloaded and are always available for use in the
Policy Framework.

====================================== ===============================================================================
**Policy Type**                        **Description**
====================================== ===============================================================================
onap.policies.Monitoring               Overarching model that supports Policy driven DCAE microservice components used
                                       in a Control Loops
onap.policies.controlloop.Operational  Used to support actor/action operational policies for control loops
onap.policies.controlloop.Guard        Control Loop guard policies for policing control loops
onap.policies.controlloop.Coordination Control Loop Coordination policies to assist in coordinating multiple control
                                       loops at runtime
====================================== ===============================================================================

2.1 Policy Type: onap.policies.Monitoring
-----------------------------------------

This is a base Policy Type that supports Policy driven DCAE microservice components used in a Control Loops. The
implementation of this Policy Type is developed using the XACML PDP to support question/answer Policy Decisions during
runtime for the DCAE Policy Handler.

.. code-block:: yaml
  :caption: Base Policy Type definition for onap.policies.Monitoring
  :linenos:

  tosca_definitions_version: tosca_simple_yaml_1_0_0
  topology_template:
    policy_types:
      - onap.policies.Monitoring:
          derived_from: tosca.policies.Root
          version: 1.0.0
          description: a base policy type for all policies that govern monitoring provision

The *PolicyTypeImpl* implementation of the *onap.policies.Montoring* Policy Type is generic to support definition of
TOSCA *PolicyType* artifacts in the Policy Framework using the Policy Type Design API. Therefore many TOSCA *PolicyType*
artifacts will use the same *PolicyTypeImpl* implementation with different property types and towards different targets.
This allows dynamically generated DCAE microservice component Policy Types to be created at Design Time.

DCAE microservice components can generate their own TOSCA *PolicyType* using TOSCA-Lab Control Loop guard policies in
SDC (Stretch Goal) or can do so manually. See `How to generate artefacts for SDC catalog using Tosca Lab Tool
<https://wiki.onap.org/display/DW/How+to+generate+artefacts+for+SDC+catalog+using+Tosca+Lab+Tool>`__
for details on TOSCA-LAB in SDC. For Dublin, the DCAE team is defining the manual steps required to build policy models
`Onboarding steps for DCAE MS through SDC/Policy/CLAMP (Dublin)
<https://wiki.onap.org/pages/viewpage.action?pageId=60883710>`__.

.. note::
  For Dublin, microservice Policy Types will be preloaded into the SDC platform and be available as a Normative. The
  policy framework will preload support for those microservice Monitoring policy types.

.. code-block:: yaml
  :caption: Example PolicyType *onap.policies.monitoring.MyDCAEComponent* derived from *onap.policies.Monitoring*
  :linenos:

  tosca_definitions_version: tosca_simple_yaml_1_0_0
  policy_types:
    - onap.policies.Monitoring:
        derived_from: tosca.policies.Root
        version: 1.0.0
        description: a base policy type for all policies that govern monitoring provision
    - onap.policies.monitoring.MyDCAEComponent:
        derived_from: onap.policies.Monitoring
        version: 1.0.0
        properties:
          mydcaecomponent_policy:
          type: map
          description: The Policy Body I need
          entry_schema:
          type: onap.datatypes.monitoring.mydatatype

  data_types:
    - onap.datatypes.monitoring.MyDataType:
      derived_from: tosca.datatypes.Root
      properties:
        my_property_1:
        type: string
        description: A description of this property
        constraints:
          - valid_values:
            - value example 1
            - value example 2

For more examples of monitoring policy type definitions, please refer to the examples in the `ONAP policy-models gerrit
repository <https://github.com/onap/policy-models/tree/master/models-examples/src/main/resources/policytypes>`__.

2.2 Policy Type: onap.policies.controlloop.Operational
------------------------------------------------------

This policy type is used to support actor/action operational policies for control loops. There are two types of
implementations for this policy type

1. Drools implementations that supports runtime Control Loop actions taken on components such as SO/APPC/VFC/SDNC/SDNR
2. Implementations using APEX to support Control Loops.

.. note::
  For Dublin, this policy type will ONLY be used for the Policy Framework to distinguish the policy type as operational.

.. code-block:: yaml
  :caption: Base Policy Type definition for onap.policies.controlloop.Operational
  :linenos:

  tosca_definitions_version: tosca_simple_yaml_1_0_0
  policy_types:
    - onap.policies.controlloop.Operational:
        derived_from: tosca.policies.Root
        version: 1.0.0
        description: Operational Policy for Control Loops

Applications should use the following Content-Type when creating onap.policies.controlloop.Operational policies:
.. code-block::

  Content-Type: "application/yaml"

2.2.1 Operational Policy Type Schema for Drools
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For Dublin Drools will still support the Casablanca YAML definition of an Operational Policy for Control Loops.

Please use the the `YAML Operational Policy format
<https://github.com/onap/policy-models/blob/master/models-interactions/model-yaml/README-v2.0.0.md>`__.

2.2.2 Operational Policy Type Schema for APEX
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The operational Policy Type schema for APEX extends the base operational Policy Type schema. This Policy Type allows
parameters specific to the APEX PDP to be specified as a TOSCA policy. See `this sample APEX policy type definition
<https://github.com/onap/integration-csit/blob/master/tests/policy/apex-pdp/data/onap.policies.controlloop.operational.Apex.json>`__.

2.3 Policy Type: onap.policies.controlloop.Guard
------------------------------------------------

This policy type is the the type definition for Control Loop guard policies for frequency limiting, blacklisting and
min/max guards to help protect runtime Control Loop Actions from doing harm to the network. This policy type is
developed using the XACML PDP to support question/answer Policy Decisions during runtime for the Drools and APEX
onap.controlloop.Operational policy type implementations.

.. code-block:: yaml
  :caption: Base Policy Type definition for onap.policies.controlloop.Guard
  :linenos:

  tosca_definitions_version: tosca_simple_yaml_1_0_0
  policy_types:
    - onap.policies.controlloop.Guard:
        derived_from: tosca.policies.Root
        version: 1.0.0
        description: Guard Policy for Control Loops Operational Policies

As with the *onap.policies.Monitoring* policy type, the *PolicyTypeImpl* implementation of the
*onap.policies.controlloop.Guard* Policy Type is generic to support definition of TOSCA *PolicyType* artifacts in the
Policy Framework using the Policy Type Design API.

.. note::
  For Dublin, only the following derived Policy Type definitions below are preloaded in the Policy Framework. However,
  the creation of policies will still support the payload from Casablanca.

Guard policy type definitions for *FrequencyLimiter*, *BlackList*, and  *MinMax* are available in the `ONAP
policy-models gerrit repository
<https://github.com/onap/policy-models/tree/master/models-examples/src/main/resources/policytypes>`__.

3 PDP Deployment and Registration with PAP
==========================================

The unit of execution and scaling in the Policy Framework is a *PolicyImpl* entity. A *PolicyImpl* entity runs on a PDP.
As is explained above, a *PolicyImpl* entity is a *PolicyTypeImpl* implementation parameterized with a TOSCA *Policy*.

.. image:: images/PolicyImplPDPSubGroup.svg

In order to achieve horizontal scalability, we group the PDPs running instances of a given *PolicyImpl* entity logically
together into a *PDPSubGroup*. The number of PDPs in a *PDPSubGroup* can then be scaled up and down using Kubernetes. In
other words, all PDPs in a subgroup run the same *PolicyImpl*, that is the same policy template implementation (in
XACML, Drools, or APEX) with the same parameters.

The figure above shows the layout of *PDPGroup* and *PDPSubGroup* entities. The figure shows examples of PDP groups for
Control Loop and Monitoring policies on the right.

The health of PDPs is monitored by the PAP in order to alert operations teams managing policy. The PAP manages the life
cycle of policies running on PDPs.

The table below shows the deployment methods in which *PolicyImpl* entities can be deployed to PDP Subgroups.

========== =========================================== ============================== ==================================
**Method** **Description**                             **Advantages**                 **Disadvantages**
========== =========================================== ============================== ==================================
Cold       The *PolicyImpl* (*PolicyTypeImpl* and      No run time configuration      Very restrictive, no run time
           TOSCA *Policy*) are predeployed on the PDP. required and run time          configuration of PDPs is possible.
           PDP is fully configured and ready to        administration is simple.
           execute when started.

           PDPs register with the PAP when they
           start, providing the *PolicyImpl* they
           have been predeployed with.

Warm       The *PolicyTypeImpl* entity is predeployed  The configuration, parameters, Administration and management is
           on the PDP. A TOSCA *Policy* may be loaded  and PDP group of PDPs may be   required. The configuration and
           at startup. The PDP may be configured or    changed at run time by loading life cycle of the TOSCA policies
           reconfigured with a new or updated TOSCA    or updating a TOSCA *Policy*   can change at run time and must be
           *Policy* at run time.                       into the PDP.                  administered and managed.

           PDPs register with the PAP when they start, Support TOSCA *Policy* entity
           providing the *PolicyImpl* they have been   life cycle managgement is
           predeployed with if any. The PAP may update supported, allowing features
           the TOSCA *Policy* on a PDP at any time     such as *PolicyImpl* Safe Mode
           after registration.                         and *PolicyImpl* retirement.

Hot        The *PolicyImpl* (*PolicyTypeImpl* and      The policy logic, rules,       Administration and management is
           TOSCA *Policy*) are deployed at run time.   configuration, parameters, and more complex. The *PolicyImpl*
           The *PolicyImpl* (*PolicyTypeImpl* and      PDP group of PDPs may be       itself and its configuration and
           TOSCA *Policy*) may be loaded at startup.   changed at run time by loading life cycle as well as the life
           The PDP may be configured or reconfigured   or updating a TOSCA *Policy*   cycle of the TOSCA policies can
           with a new or updated *PolicyTypeImpl*      and *PolicyTypeImpl* into the  change at run time and must be
           and/or TOSCA *Policy* at run time.          PDP.                           administered and managed.

           PDPs register with the PAP when they        Lifecycle management of TOSCA
           start, providing the *PolicyImpl* they have *Policy* entities and
           been predeployed with if any. The PAP may   *PolicyTypeImpl* entites is
           update the TOSCA *Policy* and               supported, allowing features
           *PolicyTypeImpl* on a PDP at any time after such as *PolicyImpl* Safe Mode
           registration                                and *PolicyImpl* retirement.
========== =========================================== ============================== ==================================

4. Policy Framework Public APIs
===============================

The Policy Framework provides the public APIs outline in the subsections below. For a full description of the APIs, see
their individual documentation linked in each subsection.

4.1 Policy Type Design API for TOSCA Policy Types
-------------------------------------------------

The full documentation for this API is available on the :ref:`Policy Life Cycle API <api-label>` page.

The purpose of this API is to support CRUD of TOSCA *PolicyType* entities. This API is provided by the
*PolicyDevelopment* component of the Policy Framework, see the :ref:`The ONAP Policy Framework Architecture
<architecture-label>` page.

The API allows applications to create, update, delete, and query *PolicyType* entities so that they become available for
use in ONAP by applications such as CLAMP. Some Policy Type entities are preloaded in the Policy Framework. The TOSCA
fields below are valid on API calls:

============ ======= ======== ========== ===============================================================================
**Field**    **GET** **POST** **DELETE** **Comment**
============ ======= ======== ========== ===============================================================================
(name)       M       M        M          The definition of the reference to the Policy Type, GET allows ranges to be
                                         specified
version      O       M        C          GET allows ranges to be specified, must be specified if more than one version
                                         of the Policy Type exists
description  R       O        N/A        Desciption of the Policy Type
derived_from R       C        N/A        Must be specified when a Policy Type is derived from another Policy Type such
                                         as in the case of derived Monitoring Policy Types
metadata     R       O        N/A        Metadata for the Policy Type
properties   R       M        N/A        This field holds the specification of the specific Policy Type in ONAP
targets      R       O        N/A        A list of node types and/or group types to which the Policy Type can be applied
triggers     R       O        N/A        Specification of policy triggers, not currently supported in ONAP
============ ======= ======== ========== ===============================================================================

.. note::
  On this and subsequent tables, use the following legend:   M-Mandatory, O-Optional, R-Read-only, C-Conditional.
  Conditional means the field is mandatory when some other field is present.

.. note::
  Preloaded policy types may only be queried over this API, modification or deletion of preloaded policy type
  implementations is disabled.

.. note::
  Policy types that are in use (referenced by defined Policies) may not be deleted.

.. note::
  The group types of targets in TOSCA are groups of TOSCA nodes, not PDP groups; the *target* concept in TOSCA is
  equivalent to the Policy Enforcement Point (PEP) concept

4.2 Policy Design API
---------------------

The full documentation for this API is available on the :ref:`Policy Life Cycle API <api-label>` page.

The purpose of this API is to support CRUD of TOSCA *Policy* entities from TOSCA compliant *PolicyType* definitions.
TOSCA *Policy* entities become the parameters for *PolicyTypeImpl* entities, producing *PolicyImpl* entities that can
run on PDPs. This API is provided by the *PolicyDevelopment* component of the Policy Framework, see the :ref:`The ONAP
Policy Framework Architecture <architecture-label>` page.

This API allows applications (such as CLAMP and Integration) to create, update, delete, and query *Policy* entities. The
TOSCA fields below are valid on API calls:

=========== ======= ======== ========== ================================================================================
**Field**   **GET** **POST** **DELETE** **Comment**
=========== ======= ======== ========== ================================================================================
(name)      M       M        M          The definition of the reference to the Policy, GET allows ranges to be specified
type        O       M        O          The Policy Type of the policy, see section 3.1
description R       O        O
metadata    R       O        N/A
properties  R       M        N/A        This field holds the specification of the specific Policy in ONAP
targets     R       O        N/A        A list of nodes and/or groups to which the Policy can be applied
=========== ======= ======== ========== ================================================================================

.. note::
  Policies that are deployed (used on deployed *PolicyImpl* entities) may not be deleted

.. note::
  This API is NOT used by DCAE for a decision on what policy the DCAE PolicyHandler should retrieve and enforce

.. note::
  The groups of targets in TOSCA are groups of TOSCA nodes, not PDP groups; the *target* concept in TOSCA is equivalent
  to the Policy Enforcement Point (PEP) concept

4.3 Policy Administration API
-----------------------------

The full documentation for this API is available on the :ref:`Policy Administration Point (PAP) <pap-label>` page.

The purpose of this API is to support CRUD of PDP groups and subgroups and to support the deployment and life cycles of
*PolicyImpl* entities (TOSCA *Policy* and *PolicyTypeImpl* entities) on PDP sub groups and PDPs. This API is provided by
the *PolicyAdministration* component (PAP) of the Policy Framework, see the :ref:`The ONAP Policy Framework Architecture
<architecture-label>` page.

PDP groups and subgroups may be prefedined in the system. Predefined groups and subgroups can be modified or deleted
over this API. The policies running on predefined groups or subgroups as well as the desired instance counts and
properties can also be modified.

A PDP may be preconfigured with its PDP group, PDP subgroup, and policies. The PDP sends this information to the PAP
when it starts. If the PDP group, subgroup, or any policy is unknown to the PAP, the PAP locks the PDP in state PASSIVE.

The state of PDP groups is managed by the API. PDP groups can be in states PASSIVE, TEST, SAFE, or ACTIVE. For a full
description of PDP group states, the :ref:`The ONAP Policy Framework Architecture <architecture-label>` page.

The API supports retrieval of statistics for PDP groups, PDP subgroups, and individual PDPs. It also allows a PDP group
health check to be ordered on PDP groups and on individual PDPs.

The fields below are valid on API calls:

============================ ======= ======== ========== ===============================================================
**Field**                    **GET** **POST** **DELETE** **Comment**
============================ ======= ======== ========== ===============================================================
name                         M       M        M          The name of the PDP group
version                      O       M        C          The version of the PDP group
state                        R       N/A      N/A        The administrative state of the PDP group: PASSIVE, SAFE, TEST,
                                                         or ACTIVE
description                  R       O        N/A        The PDP group description
properties                   R       O        N/A        Specific properties for a PDP group
pdp_subgroups                R       M        N/A        A list of PDP subgroups for a PDP group
->pdp_type                   R       M        N/A        The PDP type of this PDP subgroup, currently xacml, drools, or
                                                         apex
->supported_policy_types     R       N/A      N/A        A list of the policy types supported by the PDPs in this PDP
                                                         subgroup
->policies                   R       M        N/A        The list of policies running on the PDPs in this PDP subgroup
->->(name)                   R       M        N/A        The name of a TOSCA policy running in this PDP subgroup
->->policy_type              R       N/A      N/A        The TOSCA policy type of the policy
->->policy_type_version      R       N/A      N/A        The version of the TOSCA policy type of the policy
->->policy_type_impl         R       C        N/A        The policy type implementation (XACML, Drools Rules, or APEX
                                                         Model) that implements the policy
->instance_count             R       N/A      N/A        The number of PDP instances running in a PDP subgroup
->min_instance_count         O       N/A      N/A        The minumum number of PDP instances to run in a PDP subgroup
->properties                 O       N/A      N/A        Deployment configuration or other properties for the PDP
                                                         subgroup
->deployment_info            R       N/A      N/A        Information on the deployment for a PDP subgroup
->instances                  R       N/A      N/A        A list of PDP instances running in a PDP subgroup
->->instance                 R       N/A      N/A        The instance ID of a PDP running in a Kuberenetes Pod
->->state                    R       N/A      N/A        The administrative state of the PDP: PASSIVE, SAFE, TEST, or
                                                         ACTIVE
->->healthy                  R       N/A      N/A        The result of the latest health check on the PDP:
                                                         HEALTHY/NOT_HEALTHY/TEST_IN_PROGRESS
->->message                  O       N/A      N/A        A status message for the PDP if any
->->deployment_instance_info R       N/A      N/A        Information on the node running the PDP
============================ ======= ======== ========== ===============================================================

Note: In the Dublin release, the *policy_type_impl* of all policy types in a PDP subgroup must be the same.

4.4 Policy Decision API - Getting Policy Decisions
--------------------------------------------------

Policy decisions are required by ONAP components to support the policy-driven ONAP architecture. Policy Decisions are
implemented using the XACML PDP. The calling application must provide attributes in order for the XACML PDP to return a
correct decision.

Decision API queries are implemented with a POST operation with a JSON body that specifies the filter for the policies
to be returned.

*https:{url}:{port}/decision/v1/ POST*

The table below describes the fields in the JSON payload for the decision API Call.

============= ======= ======== ==========================================================================
**Field**     **R/O** **Type** **Description**
============= ======= ======== ==========================================================================
ONAPName      R       String   Name of the ONAP Project that is making the request.
ONAPComponent O       String   Name of the ONAP Project component that is making the request.
ONAPInstance  O       String   Optional instance identification for that ONAP component.
action        R       String   The action that the ONAP component is performing on a resource.
                               "configure" → DCAE uS onap.Monitoring policy Decisions to configure uS
                               "naming"
                               "placement"
                               "guard"
============= ======= ======== ==========================================================================

These sub metadata structures are used to scope the resource the ONAP component is performing an action upon. At least
one must be specified in order for Policy to return a decision. Multiple structures may be utilized to help define a
precise scope for a decision.

================= ======= ======== ==================================================================
**Field**         **R/O** **Type** **Description**
================= ======= ======== ==================================================================
policy-type-name  O       String   The policy type name. This may be a regular expression.
policy-id         O       String   The policy id. This may be a regular expression or an exact value.
================= ======= ======== ==================================================================

This example below shows the JSON body of a query with a single policy ID.

.. code-block:: yaml
  :caption: Decision API Call - Single Policy ID query
  :linenos:

  {
    "ONAPName": "DCAE",
    "ONAPComponent": "PolicyHandler",
    "ONAPInstance": "622431a4-9dea-4eae-b443-3b2164639c64",
    "action": "configure",
    "resource": {
      "policy-id": "onap.scaleout.tca"
    }
  }

.. code-block:: yaml
  :caption: Decision Response - Single Policy ID query
  :linenos:

  {
    "policies": {
      "onap.scaleout.tca": {
        "type": "onap.policies.monitoring.cdap.tca.hi.lo.app",
        "version": "1.0.0",
        "metadata": {
          "policy-id": "onap.scaleout.tca",
          "policy-version": 1
        },
        "properties": {
          "tca_policy": {
            "domain": "measurementsForVfScaling",
            "metricsPerEventName": [{
              "eventName": "vLoadBalancer",
              "controlLoopSchemaType": "VNF",
              "policyScope": "type=configuration",
              "policyName": "onap.scaleout.tca",
              "policyVersion": "v0.0.1",
              "thresholds": [{
                  "closedLoopControlName": "ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3",
                  "closedLoopEventStatus": "ONSET",
                  "version": "1.0.2",
                  "fieldPath": "$.event.measurementsForVfScalingFields.vNicPerformanceArray[*]
                  .receivedBroadcastPacketsAccumulated",
                  "thresholdValue": 500,
                  "direction": "LESS_OR_EQUAL",
                  "severity": "MAJOR"
                },
                {
                  "closedLoopControlName": "ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3",
                  "closedLoopEventStatus": "ONSET",
                  "version": "1.0.2",
                  "fieldPath": "$.event.measurementsForVfScalingFields.vNicPerformanceArray[*]
                  .receivedBroadcastPacketsAccumulated",
                  "thresholdValue": 5000,
                  "direction": "GREATER_OR_EQUAL",
                  "severity": "CRITICAL"
              }]
            }]
          }
        }
      }
    }
  }

This example below shows the JSON body of a query with multiple policy IDs.

.. code-block:: yaml
  :caption: Decision API Call - Multiple Policy IDs query
  :linenos:

  {
    "ONAPName": "DCAE",
    "ONAPComponent": "PolicyHandler",
    "ONAPInstance": "622431a4-9dea-4eae-b443-3b2164639c64",
    "action": "configure",
    "resource": {
      "policy-id": [
        "onap.scaleout.tca",
        "onap.restart.tca"
      ]
    }
  }

.. code-block:: yaml
  :caption: Decision Response - Multiple Policy IDs query
  :linenos:

  {
    "policies": {
      "onap.scaleout.tca": {
        "type": "onap.policies.monitoring.cdap.tca.hi.lo.app",
        "version": "1.0.0",
        "metadata": {
          "policy-id": "onap.scaleout.tca"
        },
        "properties": {
          "tca_policy": {
            "domain": "measurementsForVfScaling",
            "metricsPerEventName": [
              {
                "eventName": "vLoadBalancer",
                "controlLoopSchemaType": "VNF",
                "policyScope": "type=configuration",
                "policyName": "onap.scaleout.tca",
                "policyVersion": "v0.0.1",
                "thresholds": [
                  {
                    "closedLoopControlName": "ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3",
                    "closedLoopEventStatus": "ONSET",
                    "version": "1.0.2",
                    "fieldPath": "$.event.measurementsForVfScalingFields.vNicPerformanceArray[*]
                    .receivedBroadcastPacketsAccumulated",
                    "thresholdValue": 500,
                    "direction": "LESS_OR_EQUAL",
                    "severity": "MAJOR"
                  },
                  {
                    "closedLoopControlName": "ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3",
                    "closedLoopEventStatus": "ONSET",
                    "version": "1.0.2",
                    "fieldPath": "$.event.measurementsForVfScalingFields.vNicPerformanceArray[*]
                    .receivedBroadcastPacketsAccumulated",
                    "thresholdValue": 5000,
                    "direction": "GREATER_OR_EQUAL",
                    "severity": "CRITICAL"
                  }
                ]
              }
            ]
          }
        }
      },
      "onap.restart.tca": {
        "type": "onap.policies.monitoring.cdap.tca.hi.lo.app",
        "version": "1.0.0",
        "metadata": {
          "policy-id": "onap.restart.tca",
          "policy-version": 1
        },
        "properties": {
          "tca_policy": {
            "domain": "measurementsForVfScaling",
            "metricsPerEventName": [
              {
                "eventName": "Measurement_vGMUX",
                "controlLoopSchemaType": "VNF",
                "policyScope": "DCAE",
                "policyName": "DCAE.Config_tca-hi-lo",
                "policyVersion": "v0.0.1",
                "thresholds": [
                  {
                    "closedLoopControlName": "ControlLoop-vCPE-48f0c2c3-a172-4192-9ae3-052274181b6e",
                    "version": "1.0.2",
                    "fieldPath": "$.event.measurementsForVfScalingFields.additionalMeasurements[*]
                    .arrayOfFields[0].value",
                    "thresholdValue": 0,
                    "direction": "EQUAL",
                    "severity": "MAJOR",
                    "closedLoopEventStatus": "ABATED"
                  },
                  {
                    "closedLoopControlName": "ControlLoop-vCPE-48f0c2c3-a172-4192-9ae3-052274181b6e",
                    "version": "1.0.2",
                    "fieldPath": "$.event.measurementsForVfScalingFields.additionalMeasurements[*]
                    .arrayOfFields[0].value",
                    "thresholdValue": 0,
                    "direction": "GREATER",
                    "severity": "CRITICAL",
                    "closedLoopEventStatus": "ONSET"
                  }
                ]
              }
            ]
          }
        }
      }
    }
  }

This example below shows the JSON body of a query to return all the deployed policies for a specific policy type.

.. code-block:: yaml
  :caption: Decision API Call - Policies for Policy Type query
  :linenos:

  {
    "ONAPName": "DCAE",
    "ONAPComponent": "PolicyHandler",
    "ONAPInstance": "622431a4-9dea-4eae-b443-3b2164639c64",
    "action": "configure",
    "resource": {
      "policy-type": "onap.policies.monitoring.cdap.tca.hi.lo.app"
    }
  }

.. code-block:: yaml
  :caption: Decision Response - Policies for Policy Type query
  :linenos:

  {
    "policies": {
      "onap.scaleout.tca": {
        "type": "onap.policies.monitoring.cdap.tca.hi.lo.app",
        "version": "1.0.0",
        "metadata": {
          "policy-id": "onap.scaleout.tca",
          "policy-version": 1,
        },
        "properties": {
          "tca_policy": {
            "domain": "measurementsForVfScaling",
            "metricsPerEventName": [
              {
                "eventName": "vLoadBalancer",
                "controlLoopSchemaType": "VNF",
                "policyScope": "type=configuration",
                "policyName": "onap.scaleout.tca",
                "policyVersion": "v0.0.1",
                "thresholds": [
                  {
                    "closedLoopControlName": "ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3",
                    "closedLoopEventStatus": "ONSET",
                    "version": "1.0.2",
                    "fieldPath": "$.event.measurementsForVfScalingFields.vNicPerformanceArray[*]
                    .receivedBroadcastPacketsAccumulated",
                    "thresholdValue": 500,
                    "direction": "LESS_OR_EQUAL",
                    "severity": "MAJOR"
                  },
                  {
                    "closedLoopControlName": "ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3",
                    "closedLoopEventStatus": "ONSET",
                    "version": "1.0.2",
                    "fieldPath": "$.event.measurementsForVfScalingFields.vNicPerformanceArray[*]
                    .receivedBroadcastPacketsAccumulated",
                    "thresholdValue": 5000,
                    "direction": "GREATER_OR_EQUAL",
                    "severity": "CRITICAL"
                  }
                ]
              }
            ]
          }
        }
      },
      "onap.restart.tca": {
        "type": "onap.policies.monitoring.cdap.tca.hi.lo.app",
        "version": "1.0.0",
        "metadata": {
          "policy-id": "onap.restart.tca",
          "policy-version": 1
        },
        "properties": {
          "tca_policy": {
            "domain": "measurementsForVfScaling",
            "metricsPerEventName": [
              {
                "eventName": "Measurement_vGMUX",
                "controlLoopSchemaType": "VNF",
                "policyScope": "DCAE",
                "policyName": "DCAE.Config_tca-hi-lo",
                "policyVersion": "v0.0.1",
                "thresholds": [
                  {
                    "closedLoopControlName": "ControlLoop-vCPE-48f0c2c3-a172-4192-9ae3-052274181b6e",
                    "version": "1.0.2",
                    "fieldPath": "$.event.measurementsForVfScalingFields.additionalMeasurements[*].arrayOfFields[0]
                    .value",
                    "thresholdValue": 0,
                    "direction": "EQUAL",
                    "severity": "MAJOR",
                    "closedLoopEventStatus": "ABATED"
                  },
                  {
                    "closedLoopControlName": "ControlLoop-vCPE-48f0c2c3-a172-4192-9ae3-052274181b6e",
                    "version": "1.0.2",
                    "fieldPath": "$.event.measurementsForVfScalingFields.additionalMeasurements[*].arrayOfFields[0]
                    .value",
                    "thresholdValue": 0,
                    "direction": "GREATER",
                    "severity": "CRITICAL",
                    "closedLoopEventStatus": "ONSET"
                  }
                ]
              }
            ]
          }
        }
      },
      "onap.vfirewall.tca": {
        "type": "onap.policy.monitoring.cdap.tca.hi.lo.app",
        "version": "1.0.0",
        "metadata": {
          "policy-id": "onap.vfirewall.tca",
          "policy-version": 1
        },
        "properties": {
          "tca_policy": {
            "domain": "measurementsForVfScaling",
            "metricsPerEventName": [
              {
                "eventName": "vLoadBalancer",
                "controlLoopSchemaType": "VNF",
                "policyScope": "resource=vLoadBalancer;type=configuration",
                "policyName": "onap.vfirewall.tca",
                "policyVersion": "v0.0.1",
                "thresholds": [
                  {
                    "closedLoopControlName": "ControlLoop-vFirewall-d0a1dfc6-94f5-4fd4-a5b5-4630b438850a",
                    "closedLoopEventStatus": "ONSET",
                    "version": "1.0.2",
                    "fieldPath": "$.event.measurementsForVfScalingFields.vNicPerformanceArray[*]
                    .receivedBroadcastPacketsAccumulated",
                    "thresholdValue": 500,
                    "direction": "LESS_OR_EQUAL",
                    "severity": "MAJOR"
                  },
                  {
                    "closedLoopControlName": "ControlLoop-vFirewall-d0a1dfc6-94f5-4fd4-a5b5-4630b438850a",
                    "closedLoopEventStatus": "ONSET",
                    "version": "1.0.2",
                    "fieldPath": "$.event.measurementsForVfScalingFields.vNicPerformanceArray[*]
                    .receivedBroadcastPacketsAccumulated",
                    "thresholdValue": 5000,
                    "direction": "GREATER_OR_EQUAL",
                    "severity": "CRITICAL"
                  }
                ]
              }
            ]
          }
        }
      }
    }
  }

End of Document