docs/design/design.rst

   1 .. This work is licensed under a
   2 .. Creative Commons Attribution 4.0 International License.
   3 .. http://creativecommons.org/licenses/by/4.0
   4
   5 .. _design-label:
   6
   7 Policy Design and Development
   8 #############################
   9
  10 .. contents::
  11     :depth: 3
  12
  13 This document describes the design principles that should be used to write, deploy, and run policies of various types
  14 using the Policy Framework. It explains the APIs that are available for Policy Framework users. It provides copious
  15 examples to illustrate policy design and API usage.
  16
  17 1 Introduction
  18 ==============
  19
  20 The figure below shows the Artifacts (Blue) in the ONAP Policy Framework, the Activities (Yellow) that manipulate them,
  21 and important components (Salmon) that interact with them. The Policy Framework is fully TOSCA compliant, and uses
  22 TOSCA to model policies. Please see the :ref:`TOSCA Policy Primer <tosca-label>` page for an introduction to TOSCA
  23 policy concepts.
  24
  25 .. image:: images/APIsInPolicyFramework.svg
  26
  27 TOSCA defines the concept of a *PolicyType*, the definition of a type of policy that can be applied to a service. It
  28 also defines the concept of a *Policy*, an instance of a *PolicyType*. In the Policy Framework, we handle and manage
  29 these TOSCA definitions and tie them to real implementations of policies that can run on PDPs.
  30
  31 The diagram above outlines how this is achieved. Each TOSCA *PolicyType* must have a corresponding *PolicyTypeImpl* in
  32 the Policy Framework. The TOSCA *PolicyType* definition can be used to create a TOSCA *Policy* definition, either
  33 directly by the Policy Framework, by CLAMP, or by some other system. Once the *Policy* artifact exists, it can be used
  34 together with the *PolicyTypeImpl* artifact to create a *PolicyImpl* artifact. A *PolicyImpl* artifact is an executable
  35 policy implementation that can run on a PDP.
  36
  37 The TOSCA *PolicyType* artifact defines the external characteristics of the policy; defining its properties, the types
  38 of entities it acts on, and its triggers.  A *PolicyTypeImpl* artifact is an XACML, Drools, or APEX implementation of
  39 that policy definition. *PolicyType* and *PolicyTypeImpl* artifacts may be preloaded, may be loaded manually, or may be
  40 created using the Lifecycle API. Alternatively, *PolicyType* definitions may be loaded over the Lifecycle API for
  41 preloaded *PolicyTypeImpl* artifacts. A TOSCA *PolicyType* artifact can be used by clients (such as CLAMP or CLI tools)
  42 to create, parse, serialize, and/or deserialize an actual Policy.
  43
  44 The TOSCA *Policy* artifact is used internally by the Policy Framework, or is input by CLAMP or other systems. This
  45 artifact specifies the values of the properties for the policy and specifies the specific entities the policy acts on.
  46 Policy Design uses the TOSCA *Policy* artifact and the *PolicyTypeImpl* artifact to create an executable *PolicyImpl*
  47 artifact.
  48
  49 2 ONAP Policy Types
  50 ===================
  51
  52 Policy Type Design manages TOSCA *PolicyType* artifacts and their *PolicyTypeImpl* implementations.
  53
  54 A TOSCA *PolicyType* may ultimately be defined by the modeling team but for now are defined by the Policy Framework
  55 project. Various editors and GUIs are available for creating *PolicyTypeImpl* implementations. However, systematic
  56 integration of *PolicyTypeImpl* implementation is outside the scope of the ONAP Dublin release.
  57
  58 The *PolicyType* definitions and implementations listed below are preloaded and are always available for use in the
  59 Policy Framework.
  60
  61 ====================================== ===============================================================================
  62 **Policy Type**                        **Description**
  63 ====================================== ===============================================================================
  64 onap.policies.Monitoring               Overarching model that supports Policy driven DCAE microservice components used
  65                                        in a Control Loops
  66 onap.policies.controlloop.Operational  Used to support actor/action operational policies for control loops
  67 onap.policies.controlloop.Guard        Control Loop guard policies for policing control loops
  68 onap.policies.controlloop.Coordination Control Loop Coordination policies to assist in coordinating multiple control
  69                                        loops at runtime
  70 ====================================== ===============================================================================
  71
  72 2.1 Policy Type: onap.policies.Monitoring
  73 -----------------------------------------
  74
  75 This is a base Policy Type that supports Policy driven DCAE microservice components used in a Control Loops. The
  76 implementation of this Policy Type is developed using the XACML PDP to support question/answer Policy Decisions during
  77 runtime for the DCAE Policy Handler.
  78
  79 .. code-block:: yaml
  80   :caption: Base Policy Type definition for onap.policies.Monitoring
  81   :linenos:
  82
  83   tosca_definitions_version: tosca_simple_yaml_1_0_0
  84   topology_template:
  85     policy_types:
  86       - onap.policies.Monitoring:
  87           derived_from: tosca.policies.Root
  88           version: 1.0.0
  89           description: a base policy type for all policies that govern monitoring provision
  90
  91 The *PolicyTypeImpl* implementation of the *onap.policies.Montoring* Policy Type is generic to support definition of
  92 TOSCA *PolicyType* artifacts in the Policy Framework using the Policy Type Design API. Therefore many TOSCA *PolicyType*
  93 artifacts will use the same *PolicyTypeImpl* implementation with different property types and towards different targets.
  94 This allows dynamically generated DCAE microservice component Policy Types to be created at Design Time.
  95
  96 DCAE microservice components can generate their own TOSCA *PolicyType* using TOSCA-Lab Control Loop guard policies in
  97 SDC (Stretch Goal) or can do so manually. See `How to generate artefacts for SDC catalog using Tosca Lab Tool
  98 <https://wiki.onap.org/display/DW/How+to+generate+artefacts+for+SDC+catalog+using+Tosca+Lab+Tool>`__
  99 for details on TOSCA-LAB in SDC. For Dublin, the DCAE team is defining the manual steps required to build policy models
 100 `Onboarding steps for DCAE MS through SDC/Policy/CLAMP (Dublin)
 101 <https://wiki.onap.org/pages/viewpage.action?pageId=60883710>`__.
 102
 103 .. note::
 104   For Dublin, microservice Policy Types will be preloaded into the SDC platform and be available as a Normative. The
 105   policy framework will preload support for those microservice Monitoring policy types.
 106
 107 .. code-block:: yaml
 108   :caption: Example PolicyType *onap.policies.monitoring.MyDCAEComponent* derived from *onap.policies.Monitoring*
 109   :linenos:
 110
 111   tosca_definitions_version: tosca_simple_yaml_1_0_0
 112   policy_types:
 113     - onap.policies.Monitoring:
 114         derived_from: tosca.policies.Root
 115         version: 1.0.0
 116         description: a base policy type for all policies that govern monitoring provision
 117     - onap.policies.monitoring.MyDCAEComponent:
 118         derived_from: onap.policies.Monitoring
 119         version: 1.0.0
 120         properties:
 121           mydcaecomponent_policy:
 122           type: map
 123           description: The Policy Body I need
 124           entry_schema:
 125           type: onap.datatypes.monitoring.mydatatype
 126
 127   data_types:
 128     - onap.datatypes.monitoring.MyDataType:
 129       derived_from: tosca.datatypes.Root
 130       properties:
 131         my_property_1:
 132         type: string
 133         description: A description of this property
 134         constraints:
 135           - valid_values:
 136             - value example 1
 137             - value example 2
 138
 139 For more examples of monitoring policy type definitions, please refer to the examples in the `ONAP policy-models gerrit
 140 repository <https://github.com/onap/policy-models/tree/master/models-examples/src/main/resources/policytypes>`__.
 141
 142 2.2 Policy Type: onap.policies.controlloop.Operational
 143 ------------------------------------------------------
 144
 145 This policy type is used to support actor/action operational policies for control loops. There are two types of
 146 implementations for this policy type
 147
 148 1. Drools implementations that supports runtime Control Loop actions taken on components such as SO/APPC/VFC/SDNC/SDNR
 149 2. Implementations using APEX to support Control Loops.
 150
 151 .. note::
 152   For Dublin, this policy type will ONLY be used for the Policy Framework to distinguish the policy type as operational.
 153
 154 .. code-block:: yaml
 155   :caption: Base Policy Type definition for onap.policies.controlloop.Operational
 156   :linenos:
 157
 158   tosca_definitions_version: tosca_simple_yaml_1_0_0
 159   policy_types:
 160     - onap.policies.controlloop.Operational:
 161         derived_from: tosca.policies.Root
 162         version: 1.0.0
 163         description: Operational Policy for Control Loops
 164
 165 Applications should use the following Content-Type when creating onap.policies.controlloop.Operational policies:
 166 .. code-block::
 167
 168   Content-Type: "application/yaml"
 169
 170 2.2.1 Operational Policy Type Schema for Drools
 171 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 172
 173 For Dublin Drools will still support the Casablanca YAML definition of an Operational Policy for Control Loops.
 174
 175 Please use the the `YAML Operational Policy format
 176 <https://github.com/onap/policy-models/blob/master/models-interactions/model-yaml/README-v2.0.0.md>`__.
 177
 178 2.2.2 Operational Policy Type Schema for APEX
 179 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 180
 181 The operational Policy Type schema for APEX extends the base operational Policy Type schema. This Policy Type allows
 182 parameters specific to the APEX PDP to be specified as a TOSCA policy. See `this sample APEX policy type definition
 183 <https://github.com/onap/integration-csit/blob/master/tests/policy/apex-pdp/data/onap.policies.controlloop.operational.Apex.json>`__.
 184
 185 2.3 Policy Type: onap.policies.controlloop.Guard
 186 ------------------------------------------------
 187
 188 This policy type is the the type definition for Control Loop guard policies for frequency limiting, blacklisting and
 189 min/max guards to help protect runtime Control Loop Actions from doing harm to the network. This policy type is
 190 developed using the XACML PDP to support question/answer Policy Decisions during runtime for the Drools and APEX
 191 onap.controlloop.Operational policy type implementations.
 192
 193 .. code-block:: yaml
 194   :caption: Base Policy Type definition for onap.policies.controlloop.Guard
 195   :linenos:
 196
 197   tosca_definitions_version: tosca_simple_yaml_1_0_0
 198   policy_types:
 199     - onap.policies.controlloop.Guard:
 200         derived_from: tosca.policies.Root
 201         version: 1.0.0
 202         description: Guard Policy for Control Loops Operational Policies
 203
 204 As with the *onap.policies.Monitoring* policy type, the *PolicyTypeImpl* implementation of the
 205 *onap.policies.controlloop.Guard* Policy Type is generic to support definition of TOSCA *PolicyType* artifacts in the
 206 Policy Framework using the Policy Type Design API.
 207
 208 .. note::
 209   For Dublin, only the following derived Policy Type definitions below are preloaded in the Policy Framework. However,
 210   the creation of policies will still support the payload from Casablanca.
 211
 212 Guard policy type definitions for *FrequencyLimiter*, *BlackList*, and  *MinMax* are available in the `ONAP
 213 policy-models gerrit repository
 214 <https://github.com/onap/policy-models/tree/master/models-examples/src/main/resources/policytypes>`__.
 215
 216 3 PDP Deployment and Registration with PAP
 217 ==========================================
 218
 219 The unit of execution and scaling in the Policy Framework is a *PolicyImpl* entity. A *PolicyImpl* entity runs on a PDP.
 220 As is explained above, a *PolicyImpl* entity is a *PolicyTypeImpl* implementation parameterized with a TOSCA *Policy*.
 221
 222 .. image:: images/PolicyImplPDPSubGroup.svg
 223
 224 In order to achieve horizontal scalability, we group the PDPs running instances of a given *PolicyImpl* entity logically
 225 together into a *PDPSubGroup*. The number of PDPs in a *PDPSubGroup* can then be scaled up and down using Kubernetes. In
 226 other words, all PDPs in a subgroup run the same *PolicyImpl*, that is the same policy template implementation (in
 227 XACML, Drools, or APEX) with the same parameters.
 228
 229 The figure above shows the layout of *PDPGroup* and *PDPSubGroup* entities. The figure shows examples of PDP groups for
 230 Control Loop and Monitoring policies on the right.
 231
 232 The health of PDPs is monitored by the PAP in order to alert operations teams managing policy. The PAP manages the life
 233 cycle of policies running on PDPs.
 234
 235 The table below shows the deployment methods in which *PolicyImpl* entities can be deployed to PDP Subgroups.
 236
 237 ========== =========================================== ============================== ==================================
 238 **Method** **Description**                             **Advantages**                 **Disadvantages**
 239 ========== =========================================== ============================== ==================================
 240 Cold       The *PolicyImpl* (*PolicyTypeImpl* and      No run time configuration      Very restrictive, no run time
 241            TOSCA *Policy*) are predeployed on the PDP. required and run time          configuration of PDPs is possible.
 242            PDP is fully configured and ready to        administration is simple.
 243            execute when started.
 244
 245            PDPs register with the PAP when they
 246            start, providing the *PolicyImpl* they
 247            have been predeployed with.
 248
 249 Warm       The *PolicyTypeImpl* entity is predeployed  The configuration, parameters, Administration and management is
 250            on the PDP. A TOSCA *Policy* may be loaded  and PDP group of PDPs may be   required. The configuration and
 251            at startup. The PDP may be configured or    changed at run time by loading life cycle of the TOSCA policies
 252            reconfigured with a new or updated TOSCA    or updating a TOSCA *Policy*   can change at run time and must be
 253            *Policy* at run time.                       into the PDP.                  administered and managed.
 254
 255            PDPs register with the PAP when they start, Support TOSCA *Policy* entity
 256            providing the *PolicyImpl* they have been   life cycle managgement is
 257            predeployed with if any. The PAP may update supported, allowing features
 258            the TOSCA *Policy* on a PDP at any time     such as *PolicyImpl* Safe Mode
 259            after registration.                         and *PolicyImpl* retirement.
 260
 261 Hot        The *PolicyImpl* (*PolicyTypeImpl* and      The policy logic, rules,       Administration and management is
 262            TOSCA *Policy*) are deployed at run time.   configuration, parameters, and more complex. The *PolicyImpl*
 263            The *PolicyImpl* (*PolicyTypeImpl* and      PDP group of PDPs may be       itself and its configuration and
 264            TOSCA *Policy*) may be loaded at startup.   changed at run time by loading life cycle as well as the life
 265            The PDP may be configured or reconfigured   or updating a TOSCA *Policy*   cycle of the TOSCA policies can
 266            with a new or updated *PolicyTypeImpl*      and *PolicyTypeImpl* into the  change at run time and must be
 267            and/or TOSCA *Policy* at run time.          PDP.                           administered and managed.
 268
 269            PDPs register with the PAP when they        Lifecycle management of TOSCA
 270            start, providing the *PolicyImpl* they have *Policy* entities and
 271            been predeployed with if any. The PAP may   *PolicyTypeImpl* entites is
 272            update the TOSCA *Policy* and               supported, allowing features
 273            *PolicyTypeImpl* on a PDP at any time after such as *PolicyImpl* Safe Mode
 274            registration                                and *PolicyImpl* retirement.
 275 ========== =========================================== ============================== ==================================
 276
 277 4. Policy Framework Public APIs
 278 ===============================
 279
 280 The Policy Framework provides the public APIs outline in the subsections below. For a full description of the APIs, see
 281 their individual documentation linked in each subsection.
 282
 283 4.1 Policy Type Design API for TOSCA Policy Types
 284 -------------------------------------------------
 285
 286 The full documentation for this API is available on the :ref:`Policy Life Cycle API <api-label>` page.
 287
 288 The purpose of this API is to support CRUD of TOSCA *PolicyType* entities. This API is provided by the
 289 *PolicyDevelopment* component of the Policy Framework, see the :ref:`The ONAP Policy Framework Architecture
 290 <architecture-label>` page.
 291
 292 The API allows applications to create, update, delete, and query *PolicyType* entities so that they become available for
 293 use in ONAP by applications such as CLAMP. Some Policy Type entities are preloaded in the Policy Framework. The TOSCA
 294 fields below are valid on API calls:
 295
 296 ============ ======= ======== ========== ===============================================================================
 297 **Field**    **GET** **POST** **DELETE** **Comment**
 298 ============ ======= ======== ========== ===============================================================================
 299 (name)       M       M        M          The definition of the reference to the Policy Type, GET allows ranges to be
 300                                          specified
 301 version      O       M        C          GET allows ranges to be specified, must be specified if more than one version
 302                                          of the Policy Type exists
 303 description  R       O        N/A        Desciption of the Policy Type
 304 derived_from R       C        N/A        Must be specified when a Policy Type is derived from another Policy Type such
 305                                          as in the case of derived Monitoring Policy Types
 306 metadata     R       O        N/A        Metadata for the Policy Type
 307 properties   R       M        N/A        This field holds the specification of the specific Policy Type in ONAP
 308 targets      R       O        N/A        A list of node types and/or group types to which the Policy Type can be applied
 309 triggers     R       O        N/A        Specification of policy triggers, not currently supported in ONAP
 310 ============ ======= ======== ========== ===============================================================================
 311
 312 .. note::
 313   On this and subsequent tables, use the following legend:   M-Mandatory, O-Optional, R-Read-only, C-Conditional.
 314   Conditional means the field is mandatory when some other field is present.
 315
 316 .. note::
 317   Preloaded policy types may only be queried over this API, modification or deletion of preloaded policy type
 318   implementations is disabled.
 319
 320 .. note::
 321   Policy types that are in use (referenced by defined Policies) may not be deleted.
 322
 323 .. note::
 324   The group types of targets in TOSCA are groups of TOSCA nodes, not PDP groups; the *target* concept in TOSCA is
 325   equivalent to the Policy Enforcement Point (PEP) concept
 326
 327 4.2 Policy Design API
 328 ---------------------
 329
 330 The full documentation for this API is available on the :ref:`Policy Life Cycle API <api-label>` page.
 331
 332 The purpose of this API is to support CRUD of TOSCA *Policy* entities from TOSCA compliant *PolicyType* definitions.
 333 TOSCA *Policy* entities become the parameters for *PolicyTypeImpl* entities, producing *PolicyImpl* entities that can
 334 run on PDPs. This API is provided by the *PolicyDevelopment* component of the Policy Framework, see the :ref:`The ONAP
 335 Policy Framework Architecture <architecture-label>` page.
 336
 337 This API allows applications (such as CLAMP and Integration) to create, update, delete, and query *Policy* entities. The
 338 TOSCA fields below are valid on API calls:
 339
 340 =========== ======= ======== ========== ================================================================================
 341 **Field**   **GET** **POST** **DELETE** **Comment**
 342 =========== ======= ======== ========== ================================================================================
 343 (name)      M       M        M          The definition of the reference to the Policy, GET allows ranges to be specified
 344 type        O       M        O          The Policy Type of the policy, see section 3.1
 345 description R       O        O
 346 metadata    R       O        N/A
 347 properties  R       M        N/A        This field holds the specification of the specific Policy in ONAP
 348 targets     R       O        N/A        A list of nodes and/or groups to which the Policy can be applied
 349 =========== ======= ======== ========== ================================================================================
 350
 351 .. note::
 352   Policies that are deployed (used on deployed *PolicyImpl* entities) may not be deleted
 353
 354 .. note::
 355   This API is NOT used by DCAE for a decision on what policy the DCAE PolicyHandler should retrieve and enforce
 356
 357 .. note::
 358   The groups of targets in TOSCA are groups of TOSCA nodes, not PDP groups; the *target* concept in TOSCA is equivalent
 359   to the Policy Enforcement Point (PEP) concept
 360
 361 4.3 Policy Administration API
 362 -----------------------------
 363
 364 The full documentation for this API is available on the :ref:`Policy Administration Point (PAP) <pap-label>` page.
 365
 366 The purpose of this API is to support CRUD of PDP groups and subgroups and to support the deployment and life cycles of
 367 *PolicyImpl* entities (TOSCA *Policy* and *PolicyTypeImpl* entities) on PDP sub groups and PDPs. This API is provided by
 368 the *PolicyAdministration* component (PAP) of the Policy Framework, see the :ref:`The ONAP Policy Framework Architecture
 369 <architecture-label>` page.
 370
 371 PDP groups and subgroups may be prefedined in the system. Predefined groups and subgroups can be modified or deleted
 372 over this API. The policies running on predefined groups or subgroups as well as the desired instance counts and
 373 properties can also be modified.
 374
 375 A PDP may be preconfigured with its PDP group, PDP subgroup, and policies. The PDP sends this information to the PAP
 376 when it starts. If the PDP group, subgroup, or any policy is unknown to the PAP, the PAP locks the PDP in state PASSIVE.
 377
 378 The state of PDP groups is managed by the API. PDP groups can be in states PASSIVE, TEST, SAFE, or ACTIVE. For a full
 379 description of PDP group states, the :ref:`The ONAP Policy Framework Architecture <architecture-label>` page.
 380
 381 The API supports retrieval of statistics for PDP groups, PDP subgroups, and individual PDPs. It also allows a PDP group
 382 health check to be ordered on PDP groups and on individual PDPs.
 383
 384 The fields below are valid on API calls:
 385
 386 ============================ ======= ======== ========== ===============================================================
 387 **Field**                    **GET** **POST** **DELETE** **Comment**
 388 ============================ ======= ======== ========== ===============================================================
 389 name                         M       M        M          The name of the PDP group
 390 version                      O       M        C          The version of the PDP group
 391 state                        R       N/A      N/A        The administrative state of the PDP group: PASSIVE, SAFE, TEST,
 392                                                          or ACTIVE
 393 description                  R       O        N/A        The PDP group description
 394 properties                   R       O        N/A        Specific properties for a PDP group
 395 pdp_subgroups                R       M        N/A        A list of PDP subgroups for a PDP group
 396 ->pdp_type                   R       M        N/A        The PDP type of this PDP subgroup, currently xacml, drools, or
 397                                                          apex
 398 ->supported_policy_types     R       N/A      N/A        A list of the policy types supported by the PDPs in this PDP
 399                                                          subgroup.  A trailing “.*” can be used to specify multiple
 400                                                          policy types; for example, “onap.policies.monitoring.*”
 401                                                          would match any policy type beginning with
 402                                                          “onap.policies.monitoring.”
 403 ->policies                   R       M        N/A        The list of policies running on the PDPs in this PDP subgroup
 404 ->->(name)                   R       M        N/A        The name of a TOSCA policy running in this PDP subgroup
 405 ->->policy_type              R       N/A      N/A        The TOSCA policy type of the policy
 406 ->->policy_type_version      R       N/A      N/A        The version of the TOSCA policy type of the policy
 407 ->->policy_type_impl         R       C        N/A        The policy type implementation (XACML, Drools Rules, or APEX
 408                                                          Model) that implements the policy
 409 ->instance_count             R       N/A      N/A        The number of PDP instances running in a PDP subgroup
 410 ->min_instance_count         O       N/A      N/A        The minumum number of PDP instances to run in a PDP subgroup
 411 ->properties                 O       N/A      N/A        Deployment configuration or other properties for the PDP
 412                                                          subgroup
 413 ->deployment_info            R       N/A      N/A        Information on the deployment for a PDP subgroup
 414 ->instances                  R       N/A      N/A        A list of PDP instances running in a PDP subgroup
 415 ->->instance                 R       N/A      N/A        The instance ID of a PDP running in a Kuberenetes Pod
 416 ->->state                    R       N/A      N/A        The administrative state of the PDP: PASSIVE, SAFE, TEST, or
 417                                                          ACTIVE
 418 ->->healthy                  R       N/A      N/A        The result of the latest health check on the PDP:
 419                                                          HEALTHY/NOT_HEALTHY/TEST_IN_PROGRESS
 420 ->->message                  O       N/A      N/A        A status message for the PDP if any
 421 ->->deployment_instance_info R       N/A      N/A        Information on the node running the PDP
 422 ============================ ======= ======== ========== ===============================================================
 423
 424 Note: In the Dublin release, the *policy_type_impl* of all policy types in a PDP subgroup must be the same.
 425
 426 4.4 Policy Decision API - Getting Policy Decisions
 427 --------------------------------------------------
 428
 429 Policy decisions are required by ONAP components to support the policy-driven ONAP architecture. Policy Decisions are
 430 implemented using the XACML PDP. The calling application must provide attributes in order for the XACML PDP to return a
 431 correct decision.
 432
 433 Decision API queries are implemented with a POST operation with a JSON body that specifies the filter for the policies
 434 to be returned.
 435
 436 *https:{url}:{port}/decision/v1/ POST*
 437
 438 The table below describes the fields in the JSON payload for the decision API Call.
 439
 440 ============= ======= ======== ==========================================================================
 441 **Field**     **R/O** **Type** **Description**
 442 ============= ======= ======== ==========================================================================
 443 ONAPName      R       String   Name of the ONAP Project that is making the request.
 444 ONAPComponent O       String   Name of the ONAP Project component that is making the request.
 445 ONAPInstance  O       String   Optional instance identification for that ONAP component.
 446 action        R       String   The action that the ONAP component is performing on a resource.
 447                                "configure" → DCAE uS onap.Monitoring policy Decisions to configure uS
 448                                "naming"
 449                                "placement"
 450                                "guard"
 451 ============= ======= ======== ==========================================================================
 452
 453 These sub metadata structures are used to scope the resource the ONAP component is performing an action upon. At least
 454 one must be specified in order for Policy to return a decision. Multiple structures may be utilized to help define a
 455 precise scope for a decision.
 456
 457 4.4.1 Policy Decision API - DCAE configuration examples
 458 -------------------------------------------------------
 459
 460 These resource fields are examples on how DCAE implements its "configure" application to make Decision API calls.
 461
 462 ================= ======= ======== ==================================================================
 463 **Field**         **R/O** **Type** **Description**
 464 ================= ======= ======== ==================================================================
 465 policy-type-name  O       String   The policy type name. This may be a regular expression.
 466 policy-id         O       String   The policy id. This may be a regular expression or an exact value.
 467 ================= ======= ======== ==================================================================
 468
 469 This example below shows the JSON body of a query with a single policy ID.
 470
 471 .. code-block:: yaml
 472   :caption: Decision API Call - Single Policy ID query
 473   :linenos:
 474
 475   {
 476     "ONAPName": "DCAE",
 477     "ONAPComponent": "PolicyHandler",
 478     "ONAPInstance": "622431a4-9dea-4eae-b443-3b2164639c64",
 479     "action": "configure",
 480     "resource": {
 481       "policy-id": "onap.scaleout.tca"
 482     }
 483   }
 484
 485 .. code-block:: yaml
 486   :caption: Decision Response - Single Policy ID query
 487   :linenos:
 488
 489   {
 490     "policies": {
 491       "onap.scaleout.tca": {
 492         "type": "onap.policies.monitoring.cdap.tca.hi.lo.app",
 493         "version": "1.0.0",
 494         "metadata": {
 495           "policy-id": "onap.scaleout.tca",
 496           "policy-version": 1
 497         },
 498         "properties": {
 499           "tca_policy": {
 500             "domain": "measurementsForVfScaling",
 501             "metricsPerEventName": [{
 502               "eventName": "vLoadBalancer",
 503               "controlLoopSchemaType": "VNF",
 504               "policyScope": "type=configuration",
 505               "policyName": "onap.scaleout.tca",
 506               "policyVersion": "v0.0.1",
 507               "thresholds": [{
 508                   "closedLoopControlName": "ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3",
 509                   "closedLoopEventStatus": "ONSET",
 510                   "version": "1.0.2",
 511                   "fieldPath": "$.event.measurementsForVfScalingFields.vNicPerformanceArray[*]
 512                   .receivedBroadcastPacketsAccumulated",
 513                   "thresholdValue": 500,
 514                   "direction": "LESS_OR_EQUAL",
 515                   "severity": "MAJOR"
 516                 },
 517                 {
 518                   "closedLoopControlName": "ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3",
 519                   "closedLoopEventStatus": "ONSET",
 520                   "version": "1.0.2",
 521                   "fieldPath": "$.event.measurementsForVfScalingFields.vNicPerformanceArray[*]
 522                   .receivedBroadcastPacketsAccumulated",
 523                   "thresholdValue": 5000,
 524                   "direction": "GREATER_OR_EQUAL",
 525                   "severity": "CRITICAL"
 526               }]
 527             }]
 528           }
 529         }
 530       }
 531     }
 532   }
 533
 534 This example below shows the JSON body of a query with multiple policy IDs.
 535
 536 .. code-block:: yaml
 537   :caption: Decision API Call - Multiple Policy IDs query
 538   :linenos:
 539
 540   {
 541     "ONAPName": "DCAE",
 542     "ONAPComponent": "PolicyHandler",
 543     "ONAPInstance": "622431a4-9dea-4eae-b443-3b2164639c64",
 544     "action": "configure",
 545     "resource": {
 546       "policy-id": [
 547         "onap.scaleout.tca",
 548         "onap.restart.tca"
 549       ]
 550     }
 551   }
 552
 553 .. code-block:: yaml
 554   :caption: Decision Response - Multiple Policy IDs query
 555   :linenos:
 556
 557   {
 558     "policies": {
 559       "onap.scaleout.tca": {
 560         "type": "onap.policies.monitoring.cdap.tca.hi.lo.app",
 561         "version": "1.0.0",
 562         "metadata": {
 563           "policy-id": "onap.scaleout.tca"
 564         },
 565         "properties": {
 566           "tca_policy": {
 567             "domain": "measurementsForVfScaling",
 568             "metricsPerEventName": [
 569               {
 570                 "eventName": "vLoadBalancer",
 571                 "controlLoopSchemaType": "VNF",
 572                 "policyScope": "type=configuration",
 573                 "policyName": "onap.scaleout.tca",
 574                 "policyVersion": "v0.0.1",
 575                 "thresholds": [
 576                   {
 577                     "closedLoopControlName": "ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3",
 578                     "closedLoopEventStatus": "ONSET",
 579                     "version": "1.0.2",
 580                     "fieldPath": "$.event.measurementsForVfScalingFields.vNicPerformanceArray[*]
 581                     .receivedBroadcastPacketsAccumulated",
 582                     "thresholdValue": 500,
 583                     "direction": "LESS_OR_EQUAL",
 584                     "severity": "MAJOR"
 585                   },
 586                   {
 587                     "closedLoopControlName": "ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3",
 588                     "closedLoopEventStatus": "ONSET",
 589                     "version": "1.0.2",
 590                     "fieldPath": "$.event.measurementsForVfScalingFields.vNicPerformanceArray[*]
 591                     .receivedBroadcastPacketsAccumulated",
 592                     "thresholdValue": 5000,
 593                     "direction": "GREATER_OR_EQUAL",
 594                     "severity": "CRITICAL"
 595                   }
 596                 ]
 597               }
 598             ]
 599           }
 600         }
 601       },
 602       "onap.restart.tca": {
 603         "type": "onap.policies.monitoring.cdap.tca.hi.lo.app",
 604         "version": "1.0.0",
 605         "metadata": {
 606           "policy-id": "onap.restart.tca",
 607           "policy-version": 1
 608         },
 609         "properties": {
 610           "tca_policy": {
 611             "domain": "measurementsForVfScaling",
 612             "metricsPerEventName": [
 613               {
 614                 "eventName": "Measurement_vGMUX",
 615                 "controlLoopSchemaType": "VNF",
 616                 "policyScope": "DCAE",
 617                 "policyName": "DCAE.Config_tca-hi-lo",
 618                 "policyVersion": "v0.0.1",
 619                 "thresholds": [
 620                   {
 621                     "closedLoopControlName": "ControlLoop-vCPE-48f0c2c3-a172-4192-9ae3-052274181b6e",
 622                     "version": "1.0.2",
 623                     "fieldPath": "$.event.measurementsForVfScalingFields.additionalMeasurements[*]
 624                     .arrayOfFields[0].value",
 625                     "thresholdValue": 0,
 626                     "direction": "EQUAL",
 627                     "severity": "MAJOR",
 628                     "closedLoopEventStatus": "ABATED"
 629                   },
 630                   {
 631                     "closedLoopControlName": "ControlLoop-vCPE-48f0c2c3-a172-4192-9ae3-052274181b6e",
 632                     "version": "1.0.2",
 633                     "fieldPath": "$.event.measurementsForVfScalingFields.additionalMeasurements[*]
 634                     .arrayOfFields[0].value",
 635                     "thresholdValue": 0,
 636                     "direction": "GREATER",
 637                     "severity": "CRITICAL",
 638                     "closedLoopEventStatus": "ONSET"
 639                   }
 640                 ]
 641               }
 642             ]
 643           }
 644         }
 645       }
 646     }
 647   }
 648
 649 This example below shows the JSON body of a query to return all the deployed policies for a specific policy type.
 650
 651 .. code-block:: yaml
 652   :caption: Decision API Call - Policies for Policy Type query
 653   :linenos:
 654
 655   {
 656     "ONAPName": "DCAE",
 657     "ONAPComponent": "PolicyHandler",
 658     "ONAPInstance": "622431a4-9dea-4eae-b443-3b2164639c64",
 659     "action": "configure",
 660     "resource": {
 661       "policy-type": "onap.policies.monitoring.cdap.tca.hi.lo.app"
 662     }
 663   }
 664
 665 .. code-block:: yaml
 666   :caption: Decision Response - Policies for Policy Type query
 667   :linenos:
 668
 669   {
 670     "policies": {
 671       "onap.scaleout.tca": {
 672         "type": "onap.policies.monitoring.cdap.tca.hi.lo.app",
 673         "version": "1.0.0",
 674         "metadata": {
 675           "policy-id": "onap.scaleout.tca",
 676           "policy-version": 1,
 677         },
 678         "properties": {
 679           "tca_policy": {
 680             "domain": "measurementsForVfScaling",
 681             "metricsPerEventName": [
 682               {
 683                 "eventName": "vLoadBalancer",
 684                 "controlLoopSchemaType": "VNF",
 685                 "policyScope": "type=configuration",
 686                 "policyName": "onap.scaleout.tca",
 687                 "policyVersion": "v0.0.1",
 688                 "thresholds": [
 689                   {
 690                     "closedLoopControlName": "ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3",
 691                     "closedLoopEventStatus": "ONSET",
 692                     "version": "1.0.2",
 693                     "fieldPath": "$.event.measurementsForVfScalingFields.vNicPerformanceArray[*]
 694                     .receivedBroadcastPacketsAccumulated",
 695                     "thresholdValue": 500,
 696                     "direction": "LESS_OR_EQUAL",
 697                     "severity": "MAJOR"
 698                   },
 699                   {
 700                     "closedLoopControlName": "ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3",
 701                     "closedLoopEventStatus": "ONSET",
 702                     "version": "1.0.2",
 703                     "fieldPath": "$.event.measurementsForVfScalingFields.vNicPerformanceArray[*]
 704                     .receivedBroadcastPacketsAccumulated",
 705                     "thresholdValue": 5000,
 706                     "direction": "GREATER_OR_EQUAL",
 707                     "severity": "CRITICAL"
 708                   }
 709                 ]
 710               }
 711             ]
 712           }
 713         }
 714       },
 715       "onap.restart.tca": {
 716         "type": "onap.policies.monitoring.cdap.tca.hi.lo.app",
 717         "version": "1.0.0",
 718         "metadata": {
 719           "policy-id": "onap.restart.tca",
 720           "policy-version": 1
 721         },
 722         "properties": {
 723           "tca_policy": {
 724             "domain": "measurementsForVfScaling",
 725             "metricsPerEventName": [
 726               {
 727                 "eventName": "Measurement_vGMUX",
 728                 "controlLoopSchemaType": "VNF",
 729                 "policyScope": "DCAE",
 730                 "policyName": "DCAE.Config_tca-hi-lo",
 731                 "policyVersion": "v0.0.1",
 732                 "thresholds": [
 733                   {
 734                     "closedLoopControlName": "ControlLoop-vCPE-48f0c2c3-a172-4192-9ae3-052274181b6e",
 735                     "version": "1.0.2",
 736                     "fieldPath": "$.event.measurementsForVfScalingFields.additionalMeasurements[*].arrayOfFields[0]
 737                     .value",
 738                     "thresholdValue": 0,
 739                     "direction": "EQUAL",
 740                     "severity": "MAJOR",
 741                     "closedLoopEventStatus": "ABATED"
 742                   },
 743                   {
 744                     "closedLoopControlName": "ControlLoop-vCPE-48f0c2c3-a172-4192-9ae3-052274181b6e",
 745                     "version": "1.0.2",
 746                     "fieldPath": "$.event.measurementsForVfScalingFields.additionalMeasurements[*].arrayOfFields[0]
 747                     .value",
 748                     "thresholdValue": 0,
 749                     "direction": "GREATER",
 750                     "severity": "CRITICAL",
 751                     "closedLoopEventStatus": "ONSET"
 752                   }
 753                 ]
 754               }
 755             ]
 756           }
 757         }
 758       },
 759       "onap.vfirewall.tca": {
 760         "type": "onap.policy.monitoring.cdap.tca.hi.lo.app",
 761         "version": "1.0.0",
 762         "metadata": {
 763           "policy-id": "onap.vfirewall.tca",
 764           "policy-version": 1
 765         },
 766         "properties": {
 767           "tca_policy": {
 768             "domain": "measurementsForVfScaling",
 769             "metricsPerEventName": [
 770               {
 771                 "eventName": "vLoadBalancer",
 772                 "controlLoopSchemaType": "VNF",
 773                 "policyScope": "resource=vLoadBalancer;type=configuration",
 774                 "policyName": "onap.vfirewall.tca",
 775                 "policyVersion": "v0.0.1",
 776                 "thresholds": [
 777                   {
 778                     "closedLoopControlName": "ControlLoop-vFirewall-d0a1dfc6-94f5-4fd4-a5b5-4630b438850a",
 779                     "closedLoopEventStatus": "ONSET",
 780                     "version": "1.0.2",
 781                     "fieldPath": "$.event.measurementsForVfScalingFields.vNicPerformanceArray[*]
 782                     .receivedBroadcastPacketsAccumulated",
 783                     "thresholdValue": 500,
 784                     "direction": "LESS_OR_EQUAL",
 785                     "severity": "MAJOR"
 786                   },
 787                   {
 788                     "closedLoopControlName": "ControlLoop-vFirewall-d0a1dfc6-94f5-4fd4-a5b5-4630b438850a",
 789                     "closedLoopEventStatus": "ONSET",
 790                     "version": "1.0.2",
 791                     "fieldPath": "$.event.measurementsForVfScalingFields.vNicPerformanceArray[*]
 792                     .receivedBroadcastPacketsAccumulated",
 793                     "thresholdValue": 5000,
 794                     "direction": "GREATER_OR_EQUAL",
 795                     "severity": "CRITICAL"
 796                   }
 797                 ]
 798               }
 799             ]
 800           }
 801         }
 802       }
 803     }
 804   }
 805
 806 4.4.2 Policy Decision API - Guard Decision API examples
 807 -------------------------------------------------------
 808
 809 These resource fields are examples on how Drools-PDP implements its "guard" application to make Decision API calls. This
 810 structure is a transition from the legacy guard API calls. So each of these resources are contained under a "guard" object
 811 in the "resource" object of the JSON structure.
 812
 813 ================= ======= ======== ==================================================================
 814 **Field**         **R/O** **Type** **Description**
 815 ================= ======= ======== ==================================================================
 816 actor             O       String   The actor (eg APPC, SO) that is performing a recipe
 817 recipe            O       String   The recipe (eg Restart, Reboot) that the actor going to execute
 818 clname            O       String   The unique ID for the Control Loop
 819 target            O       String   The target VNF the actor is executing the recipe on
 820 vfCount           O       String   Specific to SO "VF Module Create" - the current count of VNFs
 821
 822 ================= ======= ======== ==================================================================
 823
 824 This example below shows the JSON body of a guard Decision API call.
 825
 826 .. code-block:: json
 827   :caption: Decision API Call - Guard
 828   :linenos:
 829
 830   {
 831     "ONAPName": "Policy",
 832     "ONAPComponent": "drools-pdp",
 833     "ONAPInstance": "usecase-template",
 834     "requestId": "unique-request-id-1",
 835     "action": "guard",
 836     "resource": {
 837         "guard": {
 838             "actor": "SO",
 839             "recipe": "VF Module Create",
 840             "clname": "ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3",
 841             "target": "vLoadBalancer-00",
 842             "vfCount": "1"
 843         }
 844     }
 845   }
 846
 847 .. code-block:: json
 848   :caption: Decision Response - Guard
 849   :linenos:
 850
 851   {"status":"Permit"}
 852
 853 4.4.3 Policy Decision API - Optimize Decision API examples
 854 ----------------------------------------------------------
 855
 856 These resource fields are examples on how OOF project will make Decision API calls. NOTE: The OOF project
 857 has not yet upgraded to the API. This work is scheduled for Frankfurt.
 858
 859 ================= ======= ============== ==================================================================
 860 **Field**         **R/O** **Type**       **Description**
 861 ================= ======= ============== ==================================================================
 862 scope             O       List of String   Optional scope for the policy.
 863 services          O       List of String   One or more services the policy applies to.
 864 resources         O       List of String   The unique ID for the Control Loop
 865 geography         O       List of String   The target VNF the actor is executing the recipe on
 866
 867 ================= ======= ============== ==================================================================
 868
 869 This example below shows the JSON body of an Optimize Decision API call.
 870
 871 .. code-block:: json
 872   :caption: Decision API Call - Optimize vCPE service in US
 873   :linenos:
 874
 875   {
 876     "ONAPName": "OOF",
 877     "ONAPComponent": "OOF-component",
 878     "ONAPInstance": "OOF-component-instance",
 879     "action": "optimize",
 880     "resource": {
 881         "scope": [],
 882         "services": ["vCPE"],
 883         "resources": [],
 884         "geography": ["US"]
 885     }
 886   }
 887
 888 .. code-block:: json
 889   :caption: Decision Response -
 890   :linenos:
 891
 892   {
 893     "policies:"  {
 894         ### Omitted for brevity
 895     }
 896   }
 897
 898 End of Document