summaryrefslogtreecommitdiffstats
path: root/docs/xacml/xacml-tutorial-enforcement.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/xacml/xacml-tutorial-enforcement.rst')
-rw-r--r--docs/xacml/xacml-tutorial-enforcement.rst161
1 files changed, 161 insertions, 0 deletions
diff --git a/docs/xacml/xacml-tutorial-enforcement.rst b/docs/xacml/xacml-tutorial-enforcement.rst
new file mode 100644
index 00000000..0e8efc0d
--- /dev/null
+++ b/docs/xacml/xacml-tutorial-enforcement.rst
@@ -0,0 +1,161 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+.. _xacmltutorial-enforcement-label:
+
+Policy XACML - Policy Enforcement Tutorial
+##########################################
+
+.. toctree::
+ :maxdepth: 3
+
+This tutorial shows how to build Policy Enforcement into your application. Please be sure to clone the
+policy repositories before going through the tutorial. See :ref:`policy-development-tools-label` for details.
+
+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>`_
+
+Policy Type being Enforced
+**************************
+
+For this tutorial, we will be enforcing a Policy Type that inherits from the **onap.policies.Monitoring** Policy Type. This Policy Type is
+used by DCAE analytics for configuration purposes. Any inherited Policy Type is automatically supported by the XACML PDP for Decisions.
+
+`See the latest example Policy Type <https://github.com/onap/policy-xacml-pdp/blob/master/tutorials/tutorial-enforcement/src/test/resources/MyAnalytic.yaml>`_
+
+.. code-block:: java
+ :caption: Example Policy Type
+
+ tosca_definitions_version: tosca_simple_yaml_1_1_0
+ policy_types:
+ onap.policies.Monitoring:
+ derived_from: tosca.policies.Root
+ version: 1.0.0
+ name: onap.policies.Monitoring
+ description: a base policy type for all policies that govern monitoring provisioning
+ onap.policies.monitoring.MyAnalytic:
+ derived_from: onap.policies.Monitoring
+ type_version: 1.0.0
+ version: 1.0.0
+ description: Example analytic
+ properties:
+ myProperty:
+ type: string
+ required: true
+
+Example Policy
+**************
+
+`See the latest example policy <https://github.com/onap/policy-xacml-pdp/blob/master/tutorials/tutorial-enforcement/src/test/resources/MyPolicies.yaml>`_
+
+.. code-block:: java
+ :caption: Example Policy
+
+ tosca_definitions_version: tosca_simple_yaml_1_1_0
+ topology_template:
+ policies:
+ -
+ policy1:
+ type: onap.policies.monitoring.MyAnalytic
+ type_version: 1.0.0
+ version: 1.0.0
+ name: policy1
+ metadata:
+ policy-id: policy1
+ policy-version: 1.0.0
+ properties:
+ myProperty: value1
+
+Example Decision Requests and Responses
+***************************************
+
+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.
+
+.. code-block:: json
+ :caption: Example Decision Request
+
+ {
+ "ONAPName": "myName",
+ "ONAPComponent": "myComponent",
+ "ONAPInstance": "myInstanceId",
+ "requestId": "1",
+ "action": "configure",
+ "resource": {
+ "policy-type": "onap.policies.monitoring.MyAnalytic"
+ }
+ }
+
+The **configure** action will return a payload containing your full policy:
+
+.. code-block: json
+ :caption: Example Decision Response
+ {
+ "policies": {
+ "policy1": {
+ "type": "onap.policies.monitoring.MyAnalytic",
+ "type_version": "1.0.0",
+ "properties": {
+ "myProperty": "value1"
+ },
+ "name": "policy1",
+ "version": "1.0.0",
+ "metadata": {
+ "policy-id": "policy1",
+ "policy-version": "1.0.0"
+ }
+ }
+ }
+ }
+
+Making Decision Call in your Application
+****************************************
+
+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:
+
+.. code-block: bash
+ :caption: Example Decision API REST Call using curl
+
+ curl -k -u https://xacml-pdp:6969/policy/pdpx/v1/decision
+
+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.
+
+.. code-block: java
+ :caption: Policy Common REST Code Dependency
+
+ <dependency>
+ <groupId>org.onap.policy.common</groupId>
+ <artifactId>policy-endpoints</artifactId>
+ <version>${policy.common.version}</version>
+ </dependency>
+
+Also, if your application wants to use common code to serialize/deserialize Decision Requests and Responses, then you can include the following dependency:
+
+.. code-block: java
+ :caption: Policy Decision Request and Response Classes
+
+ <dependency>
+ <groupId>org.onap.policy.models</groupId>
+ <artifactId>policy-models-decisions</artifactId>
+ <version>${policy.models.version}</version>
+ </dependency>
+
+Responding to Policy Update Notifications
+*****************************************
+
+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.
+
+.. code-block: bash
+ :caption: Example Dmaap REST Call using curl
+
+ curl -k -u https://dmaap:3904/events/POLICY-NOTIFICATION/group/id?timeout=5000
+
+If your application does not have Dmaap client code, you can use some available code in policy/common to receive Dmaap events.
+
+To parse the JSON send over the topic, your application can use the following dependency:
+
+.. code-block: java
+ :caption: Policy PAP Update Notification Classes
+
+ <dependency>
+ <groupId>org.onap.policy.models</groupId>
+ <artifactId>policy-models-pap</artifactId>
+ <version>${policy.models.version}</version>
+ </dependency>