docs/xacml/xacml-tutorial-enforcement.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2
   3 .. _xacmltutorial-enforcement-label:
   4
   5 Policy XACML - Policy Enforcement Tutorial
   6 ##########################################
   7
   8 .. toctree::
   9    :maxdepth: 3
  10
  11 This tutorial shows how to build Policy Enforcement into your application. Please be sure to clone the
  12 policy repositories before going through the tutorial. See :ref:`policy-development-tools-label` for details.
  13
  14 This tutorial can be found in the XACML PDP repository. `See the tutorial <https://github.com/onap/policy-xacml-pdp/tree/master/tutorials/tutorial-enforcement>`_
  15
  16 Policy Type being Enforced
  17 **************************
  18
  19 For this tutorial, we will be enforcing a Policy Type that inherits from the **onap.policies.Monitoring** Policy Type. This Policy Type is
  20 used by DCAE analytics for configuration purposes. Any inherited Policy Type is automatically supported by the XACML PDP for Decisions.
  21
  22 `See the latest example Policy Type <https://github.com/onap/policy-xacml-pdp/blob/master/tutorials/tutorial-enforcement/src/test/resources/MyAnalytic.yaml>`_
  23
  24 .. code-block:: java
  25   :caption: Example Policy Type
  26
  27     tosca_definitions_version: tosca_simple_yaml_1_1_0
  28     policy_types:
  29        onap.policies.Monitoring:
  30           derived_from: tosca.policies.Root
  31           version: 1.0.0
  32           name: onap.policies.Monitoring
  33           description: a base policy type for all policies that govern monitoring provisioning
  34        onap.policies.monitoring.MyAnalytic:
  35           derived_from: onap.policies.Monitoring
  36           type_version: 1.0.0
  37           version: 1.0.0
  38           description: Example analytic
  39           properties:
  40              myProperty:
  41                 type: string
  42                 required: true
  43
  44 Example Policy
  45 **************
  46
  47 `See the latest example policy <https://github.com/onap/policy-xacml-pdp/blob/master/tutorials/tutorial-enforcement/src/test/resources/MyPolicies.yaml>`_
  48
  49 .. code-block:: java
  50   :caption: Example Policy
  51
  52     tosca_definitions_version: tosca_simple_yaml_1_1_0
  53     topology_template:
  54        policies:
  55          -
  56            policy1:
  57                type: onap.policies.monitoring.MyAnalytic
  58                type_version: 1.0.0
  59                version: 1.0.0
  60                name: policy1
  61                metadata:
  62                  policy-id: policy1
  63                  policy-version: 1.0.0
  64                properties:
  65                  myProperty: value1
  66
  67 Example Decision Requests and Responses
  68 ***************************************
  69
  70 For **onap.policies.Montoring** Policy Types, the action used will be **configure**. For **configure** actions, you can specify a resource by **policy-id** or **policy-type**. We recommend using **policy-type**, as a policy-id may not necessarily be deployed. In addition, your application should request all the available policies for your policy-type that your application should be enforcing.
  71
  72 .. code-block:: json
  73   :caption: Example Decision Request
  74
  75     {
  76       "ONAPName": "myName",
  77       "ONAPComponent": "myComponent",
  78       "ONAPInstance": "myInstanceId",
  79       "requestId": "1",
  80       "action": "configure",
  81       "resource": {
  82           "policy-type": "onap.policies.monitoring.MyAnalytic"
  83       }
  84     }
  85
  86 The **configure** action will return a payload containing your full policy:
  87
  88 .. code-block: json
  89   :caption: Example Decision Response
  90     {
  91         "policies": {
  92             "policy1": {
  93                 "type": "onap.policies.monitoring.MyAnalytic",
  94                 "type_version": "1.0.0",
  95                 "properties": {
  96                     "myProperty": "value1"
  97                 },
  98                 "name": "policy1",
  99                 "version": "1.0.0",
 100                 "metadata": {
 101                     "policy-id": "policy1",
 102                     "policy-version": "1.0.0"
 103                 }
 104             }
 105         }
 106     }
 107
 108 Making Decision Call in your Application
 109 ****************************************
 110
 111 Your application should be able to do a RESTful API call to the XACML PDP Decision API endpoint. If you have code that does this already, then utilize that to do something similar to the following curl command:
 112
 113 .. code-block: bash
 114   :caption: Example Decision API REST Call using curl
 115
 116     curl -k -u https://xacml-pdp:6969/policy/pdpx/v1/decision
 117
 118 If your application does not have REST http client code, you can use some common code available in the policy/common repository for doing HTTP calls.
 119
 120 .. code-block: java
 121   :caption: Policy Common REST Code Dependency
 122
 123         <dependency>
 124             <groupId>org.onap.policy.common</groupId>
 125             <artifactId>policy-endpoints</artifactId>
 126             <version>${policy.common.version}</version>
 127         </dependency>
 128
 129 Also, if your application wants to use common code to serialize/deserialize Decision Requests and Responses, then you can include the following dependency:
 130
 131 .. code-block: java
 132   :caption: Policy Decision Request and Response Classes
 133
 134         <dependency>
 135             <groupId>org.onap.policy.models</groupId>
 136             <artifactId>policy-models-decisions</artifactId>
 137             <version>${policy.models.version}</version>
 138         </dependency>
 139
 140 Responding to Policy Update Notifications
 141 *****************************************
 142
 143 Your application should also be able to respond to Policy Update Notifications that are published on the Dmaap topic POLICY-NOTIFICATION. This is because if a user pushes an updated Policy, your application should be able to dynamically start enforcing that policy without restart.
 144
 145 .. code-block: bash
 146   :caption: Example Dmaap REST Call using curl
 147
 148   curl -k -u https://dmaap:3904/events/POLICY-NOTIFICATION/group/id?timeout=5000
 149
 150 If your application does not have Dmaap client code, you can use some available code in policy/common to receive Dmaap events.
 151
 152 To parse the JSON send over the topic, your application can use the following dependency:
 153
 154 .. code-block: java
 155   :caption: Policy PAP Update Notification Classes
 156
 157         <dependency>
 158             <groupId>org.onap.policy.models</groupId>
 159             <artifactId>policy-models-pap</artifactId>
 160             <version>${policy.models.version}</version>
 161         </dependency>