:maxdepth: 2
platform/index
- release-notes/index
+.. release-notes/index
--- /dev/null
+
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+**********************************
+Feature: Active/Standby Management
+**********************************
+
+.. contents::
+ :depth: 3
+
+Summary
+^^^^^^^
+When the Feature Session Persistence is enabled, there can only be one active/providing service Drools PDP due to the behavior of Drools persistence. The Active/Standby Management Feature controls the selection of the Drools PDP that is providing service. It utilizes its own database and the State Management Feature database in the election algorithm. All Drools PDP nodes periodically run the election algorithm and, since they all use the same data, all nodes come to the same conclusion with the "elected" node assuming an active/providingservice state. Thus, the algorithm is distributed and has no single point of failure - assuming the database is configured for high availability.
+
+When the algorithm selects a Drools PDP to be active/providing service the controllers and topic endpoints are unlocked and allowed to process transactions. When a Drools PDP transitions to a hotstandby or coldstandby state, the controllers and topic endpoints are locked, preventing the Drools PDP from handling transactions.
+
+
+Usage
+^^^^^
+
+Enabling and Disabling Feature State Management
+-----------------------------------------------
+
+The Active/Standby Management Feature is enabled from the command line when logged in as policy after configuring the feature properties file (see Description Details section). From the command line:
+
+- > features status - Lists the status of features
+- > features enable active-standby-management - Enables the Active-Standby Management Feature
+- > features disable active-standby-management - Disables the Active-Standby Management Feature
+
+The Drools PDP must be stopped prior to enabling/disabling features and then restarted after the features have been enabled/disabled.
+
+ .. code-block:: bash
+ :caption: Enabling Active/Standby Management Feature
+
+ policy@hyperion-4:/opt/app/policy$ policy stop
+ [drools-pdp-controllers]
+ L []: Stopping Policy Management... Policy Management (pid=354) is stopping... Policy Management has stopped.
+ policy@hyperion-4:/opt/app/policy$ features enable active-standby-management
+ name version status
+ ---- ------- ------
+ controlloop-utils 1.1.0-SNAPSHOT disabled
+ healthcheck 1.1.0-SNAPSHOT disabled
+ test-transaction 1.1.0-SNAPSHOT disabled
+ eelf 1.1.0-SNAPSHOT disabled
+ state-management 1.1.0-SNAPSHOT disabled
+ active-standby-management 1.1.0-SNAPSHOT enabled
+ session-persistence 1.1.0-SNAPSHOT disabled
+
+
+Description Details
+^^^^^^^^^^^^^^^^^^^
+
+Election Algorithm
+------------------
+
+The election algorithm selects the active/providingservice Drools PDP. The algorithm on each node reads the *standbystatus* from the *StateManagementEntity* table for all other nodes to determine if they are providingservice or in a hotstandby state and able to assume an active status. It uses the *DroolsPdpEntity* table to verify that other node election algorithms are currently functioning and when the other nodes were last designated as the active Drools PDP.
+
+In general terms, the election algorithm periodically gathers the standbystatus and designation status for all the Drools PDPs. If the node which is currently designated as providingservice is "current" in updating its status, no action is required. If the designated node is either not current or has a standbystatus other than providingservice, it is time to choose another designated *DroolsPDP*. The algorithm will build a list of all DroolsPDPs that are current and have a *standbystatus* of *hotstandby*. It will then give preference to DroolsPDPs within the same site, choosing the DroolsPDP with the lowest lexicographic value to the droolsPdpId (resourceName). If the chosen DroolsPDP is itself, it will promote its standbystatus from hotstandby to providingservice. If the chosen DroolsPDP is other than itself, it will do nothing.
+
+When the DroolsPDP promotes its *standbystatus* from hotstandby to providing service, a state change notification will occur and the Standby State Change Handler will take appropriate action.
+
+
+Standby State Change Handler
+----------------------------
+
+The Standby State Change Handler (*PMStandbyStateChangeHandler* class) extends the IntegrityMonitor StateChangeNotifier class which implements the Observer class. When the DroolsPDP is constructed, an instance of the handler is constructed and registered with StateManagement. Whenever StateManagement implements a state transition, it calls the *handleStateChange()* method of the handler. If the StandbyStatus transitions to hot or cold standby, the handler makes a call into the lower level management layer to lock the application controllers and topic endpoints, preventing it from handling transactions. If the StandbyStatus transitions to providingservice, the handler makes a call into the lower level management layer to unlock the application controllers and topic endpoints, allowing it to handle transactions.
+
+
+Database
+--------
+
+The Active/Standby Feature creates a database named activestandbymanagement with a single table, **droolspdpentity**. The election handler uses that table to determine which DroolsPDP was/is designated as the active DroolsPDP and which DroolsPDP election handlers are healthy enough to periodically update their status.
+
+The **droolspdpentity** table has the following columns:
+ - **pdpId** - The unique indentifier for the DroolsPDP. It is the same as the resourceName
+ - **designated** - Has a value of 1 if the DroolsPDP is designated as active/providingservice. It has a value of 0 otherwise
+ - **priority** - Indicates the priority level of the DroolsPDP for the election handler. In general, this is ignore and all have the same priority.
+ - **updatedDate** - This is the timestamp for the most recent update of the record.
+ - **designatedDate** - This is the timestamp that indicates when the designated column was most recently set to a value of 1
+ - **site** - This is the name of the site
+
+Properties
+----------
+
+The properties are found in the feature-active-standby-management.properties file. In general, the properties are adequately described in the properties file. Parameters which must be replaced prior to usage are indicated thus: ${{parameter to be replaced}}
+
+ .. code-block:: bash
+ :caption: feature-active-standby-mangement.properties
+
+ # DB properties
+ javax.persistence.jdbc.driver=org.mariadb.jdbc.Driver
+ javax.persistence.jdbc.url=jdbc:mariadb://${{SQL_HOST}}:3306/activestandbymanagement
+ javax.persistence.jdbc.user=${{SQL_USER}}
+ javax.persistence.jdbc.password=${{SQL_PASSWORD}}
+
+ # Must be unique across the system
+ resource.name=pdp1
+ # Name of the site in which this node is hosted
+ site_name=site1
+
+ # Needed by DroolsPdpsElectionHandler
+ pdp.checkInterval=1500 # The interval in ms between updates of the updatedDate
+ pdp.updateInterval=1000 # The interval in ms between executions of the election handler
+ #pdp.timeout=3000
+ # Need long timeout, because testTransaction is only run every 10 seconds.
+ pdp.timeout=15000
+ #how long do we wait for the pdp table to populate on initial startup
+ pdp.initialWait=20000
+
+
+End of Document
+
+.. SSNote: Wiki page ref. https://wiki.onap.org/pages/viewpage.action?pageId=16005790
+
+
--- /dev/null
+
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+*************************
+Feature: State Management
+*************************
+
+.. contents::
+ :depth: 3
+
+Summary
+^^^^^^^
+The State Management Feature provides:
+
+ - Node-level health monitoring
+ - Monitoring the health of dependency nodes - nodes on which a particular node is dependent
+ - Ability to lock/unlock a node and suspend or resume all application processing
+ - Ability to suspend application processing on a node that is disabled or in a standby state
+ - Interworking/Coordination of state values
+ - Support for ITU X.731 states and state transitions for:
+ - Administrative State
+ - Operational State
+ - Availability Status
+ - Standby Status
+
+Usage
+^^^^^
+
+Enabling and Disabling Feature State Management
+-----------------------------------------------
+
+The State Management Feature is enabled from the command line when logged in as policy after configuring the feature properties file (see Description Details section). From the command line:
+
+- > features status - Lists the status of features
+- > features enable state-management - Enables the State Management Feature
+- > features disable state-management - Disables the State Management Feature
+
+The Drools PDP must be stopped prior to enabling/disabling features and then restarted after the features have been enabled/disabled.
+
+ .. code-block:: bash
+ :caption: Enabling State Management Feature
+
+ policy@hyperion-4:/opt/app/policy$ policy stop
+ [drools-pdp-controllers]
+ L []: Stopping Policy Management... Policy Management (pid=354) is stopping... Policy Management has stopped.
+ policy@hyperion-4:/opt/app/policy$ features enable state-management
+ name version status
+ ---- ------- ------
+ controlloop-utils 1.1.0-SNAPSHOT disabled
+ healthcheck 1.1.0-SNAPSHOT disabled
+ test-transaction 1.1.0-SNAPSHOT disabled
+ eelf 1.1.0-SNAPSHOT disabled
+ state-management 1.1.0-SNAPSHOT enabled
+ active-standby-management 1.1.0-SNAPSHOT disabled
+ session-persistence 1.1.0-SNAPSHOT disabled
+
+Description Details
+^^^^^^^^^^^^^^^^^^^
+
+State Model
+-----------
+
+The state model follows the ITU X.731 standard for state management. The supported state values are:
+ **Administrative State:**
+ - Locked - All application transaction processing is prohibited
+ - Unlocked - Application transaction processing is allowed
+
+ **Administrative State Transitions:**
+ - The transition from Unlocked to Locked state is triggered with a Lock operation
+ - The transition from the Locked to Unlocked state is triggered with an Unlock operation
+
+ **Operational State:**
+ - Enabled - The node is healthy and able to process application transactions
+ - Disabled - The node is not healthy and not able to process application transactions
+
+ **Operational State Transitions:**
+ - The transition from Enabled to Disabled is triggered with a disableFailed or disableDependency operation
+ - The transition from Disabled to Enabled is triggered with an enableNotFailed and enableNoDependency operation
+
+ **Availability Status:**
+ - Null - The Operational State is Enabled
+ - Failed - The Operational State is Disabled because the node is no longer healthy
+ - Dependency - The Operational State is Disabled because all members of a dependency group are disabled
+ - Dependency.Failed - The Operational State is Disabled because the node is no longer healthy and all members of a dependency group are disabled
+
+ **Availability Status Transitions:**
+ - The transition from Null to Failed is triggered with a disableFailed operation
+ - The transtion from Null to Dependency is triggered with a disableDependency operation
+ - The transition from Failed to Dependency.Failed is triggered with a disableDependency operation
+ - The transition from Dependency to Dependency.Failed is triggered with a disableFailed operation
+ - The transition from Dependency.Failed to Failed is triggered with an enableNoDependency operation
+ - The transition from Dependency.Failed to Dependency is triggered with an enableNotFailed operation
+ - The transition from Failed to Null is triggered with an enableNotFailed operation
+ - The transition from Dependency to Null is triggered with an enableNoDependency operation
+
+ **Standby Status:**
+ - Null - The node does not support active-standby behavior
+ - ProvidingService - The node is actively providing application transaction service
+ - HotStandby - The node is capable of providing application transaction service, but is currently waiting to be promoted
+ - ColdStandby - The node is not capable of providing application service because of a failure
+
+ **Standby Status Transitions:**
+ - The transition from Null to HotStandby is triggered by a demote operation when the Operational State is Enabled
+ - The transition for Null to ColdStandby is triggered is a demote operation when the Operational State is Disabled
+ - The transition from ColdStandby to HotStandby is triggered by a transition of the Operational State from Disabled to Enabled
+ - The transition from HotStandby to ColdStandby is triggered by a transition of the Operational State from Enabled to Disabled
+ - The transition from ProvidingService to ColdStandby is triggered by a transition of the Operational State from Enabled to Disabled
+ - The transition from HotStandby to ProvidingService is triggered by a Promote operation
+ - The transition from ProvidingService to HotStandby is triggered by a Demote operation
+
+Database
+--------
+
+The State Management feature creates a StateManagement database having three tables:
+
+ **StateManagementEntity** - This table has the following columns:
+ - **id** - Automatically created unique identifier
+ - **resourceName** - The unique identifier for a node
+ - **adminState** - The Administrative State
+ - **opState** - The Operational State
+ - **availStatus** - The Availability Status
+ - **standbyStatus** - The Standby Status
+ - **created_Date** - The timestamp the resource entry was created
+ - **modifiedDate** - The timestamp the resource entry was last modified
+
+ **ForwardProgressEntity** - This table has the following columns:
+ - **forwardProgressId** - Automatically created unique identifier
+ - **resourceName** - The unique identifier for a node
+ - **fpc_count** - A forward progress counter which is periodically incremented if the node is healthy
+ - **created_date** - The timestamp the resource entry was created
+ - **last_updated** - The timestamp the resource entry was last updated
+
+ **ResourceRegistrationEntity** - This table has the following columns:
+ - **ResourceRegistrationId** - Automatically created unique identifier
+ - **resourceName** - The unique identifier for a node
+ - **resourceUrl** - The JMX URL used to check the health of a node
+ - **site** - The name of the site in which the resource resides
+ - **nodeType** - The type of the node (i.e, pdp_xacml, pdp_drools, pap, pap_admin, logparser, brms_gateway, astra_gateway, elk_server, pypdp)
+ - **created_date** - The timestamp the resource entry was created
+ - **last_updated** - The timestamp the resource entry was last updated
+
+Node Health Monitoring
+----------------------
+
+**Application Monitoring**
+
+ Application monitoring can be implemented using the *startTransaction()* and *endTransaction()* methods. Whenever a transaction is started, the *startTransaction()* method is called. If the node is locked, disabled or in a hot/cold standby state, the method will throw an exception. Otherwise, it resets the timer which triggers the default *testTransaction()* method.
+
+ When a transaction completes, calling *endTransaction()* increments the forward process counter in the *ForwardProgressEntity* DB table. As long as this counter is updating, the integrity monitor will assume the node is healthy/sane.
+
+ If the *startTransaction()* method is not called within a provisioned period of time, a timer will expire which calls the *testTransaction()* method. The default implementation of this method simply increments the forward progress counter. The *testTransaction()* method may be overwritten to perform a more meaningful test of system sanity, if desired.
+
+ If the forward progress counter stops incrementing, the integrity monitoring routine will assume the node application has lost sanity and it will trigger a *statechange* (disableFailed) to cause the operational state to become disabled and the availability status attribute to become failed. Once the forward progress counter again begins incrementing, the operational state will return to enabled.
+
+**Dependency Monitoring**
+
+ When a Drools PDP (or other node using the *IntegrityMonitor* policy/common module) is dependent upon other nodes to perform its function, those other nodes can be defined as dependencies in the properties file. In order for the dependency algorithm to function, the other nodes must also be running the *IntegrityMonitor*. Periodically the Drools PDP will check the state of dependencies. If all of a node type have failed, the Drools PDP will declare that it can no longer function and change the operational state to disabled and the availability status to dependency.
+
+ In addition to other policy node types, there is a *subsystemTest()* method that is periodically called by the *IntegrityMonitor*. In Drools PDP, *subsystemTest* has been overwritten to execute an audit of the Database and of the Maven Repository. If the audit is unable to verify the function of either the DB or the Maven Repository, he Drools PDP will declare that it can no longer function and change the operational state to disabled and the availability status to dependency.
+
+ When a failed dependency returns to normal operation, the *IntegrityMontor* will change the operational state to enabled and availability status to null.
+
+**External Health Monitoring Interface**
+
+ The Drools PDP has a http test interface which, when called, will return 200 if all seems well and 500 otherwise. The test interface URL is defined in the properties file.
+
+
+Site Manager
+------------
+
+The Site Manager is not deployed with the Drools PDP, but it is available in the policy/common repository in the site-manager directory.
+The Site Manager provides a lock/unlock interface for nodes and a way to display node information and status.
+
+The following is from the README file included with the Site Manager.
+
+ .. code-block:: bash
+ :caption: Site Manager README extract
+
+ Before using 'siteManager', the file 'siteManager.properties' needs to be
+ edited to configure the parameters used to access the database:
+
+ javax.persistence.jdbc.driver - typically 'org.mariadb.jdbc.Driver'
+
+ javax.persistence.jdbc.url - URL referring to the database,
+ which typically has the form: 'jdbc:mariadb://<host>:<port>/<db>'
+ ('<db>' is probably 'xacml' in this case)
+
+ javax.persistence.jdbc.user - the user id for accessing the database
+
+ javax.persistence.jdbc.password - password for accessing the database
+
+ Once the properties file has been updated, the 'siteManager' script can be
+ invoked as follows:
+
+ siteManager show [ -s <site> | -r <resourceName> ] :
+ display node information (Site, NodeType, ResourceName, AdminState,
+ OpState, AvailStatus, StandbyStatus)
+
+ siteManager setAdminState { -s <site> | -r <resourceName> } <new-state> :
+ update admin state on selected nodes
+
+ siteManager lock { -s <site> | -r <resourceName> } :
+ lock selected nodes
+
+ siteManager unlock { -s <site> | -r <resourceName> } :
+ unlock selected nodes
+
+Note that the 'siteManager' script assumes that the script,
+'site-manager-${project.version}.jar' file and 'siteManager.properties' file
+are all in the same directory. If the files are separated, the 'siteManager'
+script will need to be modified so it can locate the jar and properties files.
+
+
+Properties
+----------
+
+The feature-state-mangement.properties file controls the function of the State Management Feature. In general, the properties have adequate descriptions in the file. Parameters which must be replaced prior to usage are indicated thus: ${{parameter to be replaced}}.
+
+ .. code-block:: bash
+ :caption: feature-state-mangement.properties
+
+ # DB properties
+ javax.persistence.jdbc.driver=org.mariadb.jdbc.Driver
+ javax.persistence.jdbc.url=jdbc:mariadb://${{SQL_HOST}}:3306/statemanagement
+ javax.persistence.jdbc.user=${{SQL_USER}}
+ javax.persistence.jdbc.password=${{SQL_PASSWORD}}
+
+ # DroolsPDPIntegrityMonitor Properties
+ # Test interface host and port defaults may be overwritten here
+ http.server.services.TEST.host=0.0.0.0
+ http.server.services.TEST.port=9981
+ #These properties will default to the following if no other values are provided:
+ # http.server.services.TEST.restClasses=org.onap.policy.drools.statemanagement.IntegrityMonitorRestManager
+ # http.server.services.TEST.managed=false
+ # http.server.services.TEST.swagger=true
+
+ #IntegrityMonitor Properties
+
+ # Must be unique across the system
+ resource.name=pdp1
+ # Name of the site in which this node is hosted
+ site_name=site1
+ # Forward Progress Monitor update interval seconds
+ fp_monitor_interval=30
+ # Failed counter threshold before failover
+ failed_counter_threshold=3
+ # Interval between test transactions when no traffic seconds
+ test_trans_interval=10
+ # Interval between writes of the FPC to the DB seconds
+ write_fpc_interval=5
+ # Node type Note: Make sure you don't leave any trailing spaces, or you'll get an 'invalid node type' error!
+ node_type=pdp_drools
+ # Dependency groups are groups of resources upon which a node operational state is dependent upon.
+ # Each group is a comma-separated list of resource names and groups are separated by a semicolon. For example:
+ # dependency_groups=site_1.astra_1,site_1.astra_2;site_1.brms_1,site_1.brms_2;site_1.logparser_1;site_1.pypdp_1
+ dependency_groups=
+ # When set to true, dependent health checks are performed by using JMX to invoke test() on the dependent.
+ # The default false is to use state checks for health.
+ test_via_jmx=true
+ # This is the max number of seconds beyond which a non incrementing FPC is considered a failure
+ max_fpc_update_interval=120
+ # Run the state audit every 60 seconds (60000 ms). The state audit finds stale DB entries in the
+ # forwardprogressentity table and marks the node as disabled/failed in the statemanagemententity
+ # table. NOTE! It will only run on nodes that have a standbystatus = providingservice.
+ # A value of <= 0 will turn off the state audit.
+ state_audit_interval_ms=60000
+ # The refresh state audit is run every (default) 10 minutes (600000 ms) to clean up any state corruption in the
+ # DB statemanagemententity table. It only refreshes the DB state entry for the local node. That is, it does not
+ # refresh the state of any other nodes. A value <= 0 will turn the audit off. Any other value will override
+ # the default of 600000 ms.
+ refresh_state_audit_interval_ms=600000
+
+
+ # Repository audit properties
+ # Assume it's the releaseRepository that needs to be audited,
+ # because that's the one BRMGW will publish to.
+ repository.audit.id=${{releaseRepositoryID}}
+ repository.audit.url=${{releaseRepositoryUrl}}
+ repository.audit.username=${{repositoryUsername}}
+ repository.audit.password=${{repositoryPassword}}
+ repository2.audit.id=${{releaseRepository2ID}}
+ repository2.audit.url=${{releaseRepository2Url}}
+ repository2.audit.username=${{repositoryUsername2}}
+ repository2.audit.password=${{repositoryPassword2}}
+
+ # Repository Audit Properties
+ # Flag to control the execution of the subsystemTest for the Nexus Maven repository
+ repository.audit.is.active=false
+ repository.audit.ignore.errors=true
+ repository.audit.interval_sec=86400
+ repository.audit.failure.threshold=3
+
+ # DB Audit Properties
+ # Flag to control the execution of the subsystemTest for the Database
+ db.audit.is.active=false
+
+
+End of Document
+
+.. SSNote: Wiki page ref. https://wiki.onap.org/display/DW/Feature+State+Management
+
+
offeredapis.rst
installation.rst
policygui.rst
- guardpolicy.rst
+ swarch_pap.rst
+ swarch_pdpx.rst
deployPDPPAP.rst
+ guardpolicy.rst
guardpdp.rst
- tutorial_vDNS.rst
- tutorial_VOLTE.rst
+ feature_eelf.rst
feature_testtransaction.rst
feature_healthcheck.rst
- feature_eelf.rst
+ feature_statemgmt.rst
+ feature_activestdbymgmt.rst
+ tutorial_vDNS.rst
+ tutorial_VOLTE.rst
+ tutorial_vFW.rst
+ tutorial_vCPE.rst
--- /dev/null
+
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+*************************
+PAP Software Architecture
+*************************
+
+.. contents::
+ :depth: 3
+
+Overview
+^^^^^^^^
+PAP (Policy Administration Point) is the component of POLICY that is used to administer both Drools and XACML related policies. The core underlying technology used is XACML and the component itself belongs to the XACML architecture family. This component, as the name suggests, manages the configurations for PDP's and is responsible for the Create, Update and Delete operations of policies.
+
+Context
+^^^^^^^
+The purpose of PAP is to:
+
+- Manage groups. create, delete or edit a group. By default "*default*" is created at startup.
+- Manage PDP's. PDP's are assigned to single group at any given point of time. They can be changed or even removed. By default, at the time of startup PDP's are registered to the default group.
+- Manage Policies. Create, update and remove policies which are stored in the database.
+- Assign Policies to Group. Policies can be added or removed from group(s).
+- Group changes updates all PDP's present in the group.
+- Manage PIP (Policy Information Point) configuration to groups.
+- Provide RESTful API interface for PDP's to communicate with PAP to register and be able to update their properties.
+- Provide RESTful API interface for PDP/ POLICY-SDK-APP (policy GUI) to call the PAP and utilize its services. Clients would either use the GUI or PDP API to communicate with PAP.
+
+PAP Application Software
+^^^^^^^^^^^^^^^^^^^^^^^^
+- PAP application software can run as a standalone application. But, to utilize its full features it needs at-least one running PDP instance connected to the PAP. The urls can be defined in the properties file of PDP component.
+- This application can run as single container, or can support multiple instances of PAP's running. Each instance runs the same software. The differences are defined in the properties file used by the PAP software.
+- The software is maintained using this project.
+ ONAP-PAP-REST → https://git.onap.org/policy/engine/tree/ONAP-PAP-REST
+- Tomcat 8 is used as the web server to host PAP.
+- A PDP update thread is used to update all PDP's upon any change to the group.
+- MariaDB is used as the database behind to store the policies.
+- File system and Properties file are used to cache and store the group information data.
+- Elastic search database is used to store the policy data for index and search.
+
+Core components
+^^^^^^^^^^^^^^^
+- XACMLPapServlet is the core servlet module handling the RESTful calls from PDP and Policy GUI. Apart from the servlet, PAP co hosts spring rest controller to host special API calls to serve Policy GUI.
+- Each policy type is comprised as a different component type and are all under components package. In order to add any new extension to the Policy, it can be done by extending Policy.
+- Spring controllers are present under the controller package which have the controller logic for different dictionaries as well as policy creation controller.
+- Threads are used to update PDP's about any new updates in the group. There are also other threads which are used to monitor the status of PDP's.
+
+Configuration
+^^^^^^^^^^^^^
+- All configurations related to the PAP are presesnt in xacml.pap.properties file. This can be changed if required in the docker setup or policy installation setup.
+- pip.properties file is used as the PIP properties file. At the time of writing this document the PIP configuration can be changed via this file and applies for all groups.
+
+.. seealso:: The XACML PAP implementation mainly references the AT&T XACML https://github.com/att/XACML project.
+
+
+End of Document
+
+.. SSNote: Wiki page ref. https://wiki.onap.org/display/DW/PAP+Software+Architecture
+
+
--- /dev/null
+
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+***************************
+PDP-X Software Architecture
+***************************
+
+.. contents::
+ :depth: 3
+
+Overview
+^^^^^^^^
+The PDP (Policy Decision Point) is the main decision engine of POLICY. The decisions taken are based on the policy set which has been assigned by PAP. **PDP** is a part of **XACML** family and, hence, referred to as **PDP-X**. The PDP-X receives XACML requests and returns XACML responses which are either Permit, Deny or Indeterminate. The software contains wrapper code to wrap the internal XACML structures with a request and response structure that is commonly used in ONAP.
+
+PDP Application container
+^^^^^^^^^^^^^^^^^^^^^^^^^
+- PDP Application containers run as standalone containers which when requested for decision give appropriate responses.
+- If configured with PAP it would be able to modify the PDP's policy set. In absence of PAP the PDP would utilize its existing set of policies to take decisions.
+- In order to scale up and handle multiple requests, Multiple PDP's can be started and used to serve the requests.
+
+Core Software
+^^^^^^^^^^^^^
+- The core software of PDP-X is the divided into two projects:
+ - ONAP-PDP (core PDP decision components)
+ - ONAP-PDP-REST (Rest wrapper around PDP to support communications with PAP and take in requests from clients)
+
+- ONAP-PDP-REST is the project which has the wrapper code and hosts the Policy APIs, which also acts as a proxy for Policy administration related APIs.
+- ONAP-PDP-REST project comprises of:
+ - Servlet code implementation which handles the requests from PAP's and legacy XACML requests from clients.
+ - Spring REST controller implementation handles the Policy API's that are widely used within ONAP. Swagger documentation is tied with the API code which are available with the PDP container when executed.
+ - Notification server which sends notification to the connected clients via Websocket, DMaaP or UEB. Policy Internal components use Websocket as the notification medium.
+ - Runs a thread to communicate with PAP about any updates in policy configurations.
+
+- ONAP-PDP project is an extension of XACML implementation of PDP which contains the core XACML function and definition which are used in the policy decision process.
+- Tomcat 8 is used as the web server to host PDP-X.
+- File system and properties file are used to store policy information so that PDP can recover in case of failure.
+- In memory cache is used by PDP to store policy information after startup in order to serve requests quickly.
+
+Package Overview
+^^^^^^^^^^^^^^^^
+- ONAP-PDP-REST package structure is discussed here:
+ - rest is the main package which contains servlet code.
+ - controller package consists of the spring rest controller which handles the API requests from clients.
+ - service package consists of the service layer code for different policy API services.
+ - notifications package consists of the notification service that is offered by PDP-X.
+ - config package consists of the spring and swagger configurations.
+
+- Extensions
+ - Any new addition to the service can be added to the service layer and appropriate API call can be added to the controller code.
+
+Configuration
+^^^^^^^^^^^^^
+- All configurations related to PDP are present in xacml.pdp.properties file. This can be changed if required in the docker setup or policy installation setup.
+
+
+.. seealso:: The PDP implementation references the XACML AT&T https://github.com/att/XACML project.
+
+
+End of Document
+
+.. SSNote: Wiki page ref. https://wiki.onap.org/display/DW/PDP-X+Software+Architecture
+
+
--- /dev/null
+
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+*********************************************************
+Tutorial: Testing the vCPE use case in a standalone PDP-D
+*********************************************************
+
+.. contents::
+ :depth: 3
+
+
+High Level Architecture
+^^^^^^^^^^^^^^^^^^^^^^^
+The vCPE flow begins with an onset message that is sent from DCAE notifying the PDP-D that an action needs to be taken on a VM/VNF. Once the PDP-D has inserted the onset into drools memory, rules begin to fire to start processing the onset for the vCPE policy that exists in drools memory. If the onset is not enriched with A&AI data, Policy will query A&AI for the VM/VNF data otherwise the PDP-D will get the A&AI data needed directly from the onset. A Guard query is then executed to determine if the action to be taken is allowed. If Guard returns a permit, the PDP-D will then send an APPC Restart recipe request to restart the VM/VNF specified in the request. If APPC is successful then the PDP-D will send a operation success notification on the POLICY-CL-MGT topic. The PDP-D waits for an abatement message to come from DCAE before ending the transaction. Once the abatement is received the PDP-D sends a final success notification and gracefully ends processing the event.
+
+Initial Setup
+^^^^^^^^^^^^^
+
+For this tutorial, a feature for simulating components involved in the flow outside of Policy will be turned on. Run "*features enable controlloop-utils*".
+
+ .. image:: Tut_vCPE_simulators_enabled.JPG
+
+Now start the PDP-D using the command "policy start"
+
+ .. image:: Tut_vCPE_policy_start.JPG
+
+Running the Flow
+^^^^^^^^^^^^^^^^
+
+The telemetry API is used to see what is in memory. There should only be 1 fact, the Params object which is created at initialization time and contains the vCPE policy that was created.
+
+ .. code-block:: bash
+
+ curl --silent --user @1b3rt:31nst31n -X GET http://localhost:9696/policy/pdp/engine/controllers/amsterdam/drools/facts/amsterdam | python -m json.tool
+
+
+ .. image:: Tut_vCPE_get_facts.JPG
+
+Using the telemetry API, a simulated onset can be injected by the user. For demo purposes, this is the simulated onset that will be used:
+
+ .. image:: Tut_vCPE_simulated_onset.JPG
+
+**NOTE:** The onset that gets injected has to have a closedLoopControlName that matches the pushed policy's closedLoopControlName.
+
+Inject the onset using the Telemetry API.
+
+ .. code-block:: bash
+
+ curl --silent --user @1b3rt:31nst31n --header "Content-Type: text/plain" --data @dcae.vcpe.onset.json -X PUT http://localhost:9696/policy/pdp/engine/topics/sources/ueb/unauthenticated.DCAE_EVENT_OUTPUT/events | python -m json.tool
+
+ .. image:: Tut_vCPE_insert_onset.JPG
+
+**NOTE:** The simulated onset is enriched with A&AI data. The PDP-D will not make an A&AI query since the data needed can be extracted from the onset.
+
+Now check the facts in memory, there should be 7 objects present. Two timers exist to put a time limit on the operation and on the overall control loop (in the case of retries or policy chaining). The event and it's associated manager and operation manager are also present in memory. A lock on the target entity is inserted to ensure no other events try to take action on the VM/VNF that is currently processing.
+
+
+ .. image:: Tut_vCPE_get_facts_2.JPG
+
+The network log will be used to monitor the activity coming in and out of the PDP-D. This log is located at *$POLICY_HOME/logs/network.log*. This will show the notifications that the PDP-D sends out at different stages of processing. The order of successful processing begins with an ACTIVE notification to show that the onset was acknowledged and the operation is beginning transit.
+
+ .. image:: Tut_vCPE_policy_active.JPG
+
+Once the event is in the ACTIVE state, the PDP-D consults Guard to determine if this operation should be allowed, a series of operation notifications are sent for starting the Guard query, obtaining a PERMIT or DENY, and beginning the operation.
+
+ .. image:: Tut_vCPE_guard_not_queried.JPG
+
+ .. image:: Tut_vCPE_guard_result.JPG
+
+ .. image:: Tut_vCPE_policy_operation.JPG
+
+Once the operation starts an APPC request is sent out.
+
+ .. image:: Tut_vCPE_appc_request.JPG
+
+A simulated APPC response will be injected to the APPC-LCM-WRITE topic, this is the example response used:
+
+ .. image:: Tut_vCPE_simulated_appc_response.JPG
+
+Inject the response using the Telemetry API.
+
+ .. code-block:: bash
+
+ curl --silent --user @1b3rt:31nst31n --header "Content-Type: text/plain" --data @appc.lcm.success.json -X PUT http://localhost:9696/policy/pdp/engine/topics/sources/ueb/APPC-LCM-WRITE/events | python -m json.tool
+
+ .. image:: Tut_vCPE_inject_appc_response.JPG
+
+The network log will show the PDP-D sent an operation success notification.
+
+ .. image:: Tut_vCPE_policy_operation_success.JPG
+
+For the vCPE use case, once an operation is successful, the PDP-D waits for DCAE to send an abatement message to end processing. The following abatement message will be used:
+
+ .. image:: Tut_vCPE_simulated_abatement.JPG
+
+Inject the abatement message using the Telemetry API.
+
+ .. code-block:: bash
+
+ curl --silent --user @1b3rt:31nst31n --header "Content-Type: text/plain" --data @dcae.vcpe.abatement.json -X PUT http://localhost:9696/policy/pdp/engine/topics/sources/ueb/unauthenticated.DCAE_EVENT_OUTPUT/events | python -m json.tool
+
+ .. image:: Tut_vCPE_insert_abatement.JPG
+
+Once the abatement is received, a final success notification is sent from the PDP-D.
+
+ .. image:: Tut_vCPE_policy_final_success.JPG
+
+After processing there should only be 1 fact left in memory.
+
+ .. image:: Tut_vCPE_final_memory.JPG
+
+
+End of Document
+
+
+.. SSNote: Wiki page ref. https://wiki.onap.org/display/DW/Tutorial%3A+Testing+the+vCPE+use+case+in+a+standalone+PDP-D
+
+
--- /dev/null
+
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+****************************************************
+Tutorial: Testing the vFW flow in a standalone PDP-D
+****************************************************
+
+.. contents::
+ :depth: 3
+
+
+High Level Architecture
+^^^^^^^^^^^^^^^^^^^^^^^
+The vFW flow begins with an onset message that is sent from DCAE notifying the PDP-D that an action needs to be taken on a VNF. Once the PDP-D has inserted the onset into drools memory, rules begin to fire to start processing the onset for the vFW policy that exists in drools memory. If the onset is not enriched with A&AI data, Policy will query A&AI for the VNF data otherwise the PDP-D will get the A&AI data needed directly from the onset. Then an A&AI named query is executed on the source VNF entity from the onset to find the target VNF entity that the PDP-D will take action on. Once the target entity is retrieved from A&AI, a Guard query is executed to determine if the action to be taken is allowed. If Guard returns a permit, the PDP-D will then send an APPC ModifyConfig recipe request to modify pg-streams as specified in the request payload. If APPC is successful then the PDP-D will send a final success notification on the POLICY-CL-MGT topic and gracefully end processing the event.
+
+Initial Setup
+^^^^^^^^^^^^^
+
+For this tutorial, a feature for simulating components involved in the flow outside of Policy will be turned on. Run "*features enable controlloop-utils*".
+
+ .. image:: Tut_vFW_simulators_enabled.JPG
+
+Now start the PDP-D using the command "policy start"
+
+ .. image:: Tut_vFW_policy_start.JPG
+
+Running the Flow
+^^^^^^^^^^^^^^^^
+
+The telemetry API is used to see what is in memory. There should only be 1 fact, the Params object which is created at initialization time and contains the vFW policy that was created.
+
+ .. code-block:: bash
+
+ curl --silent --user @1b3rt:31nst31n -X GET http://localhost:9696/policy/pdp/engine/controllers/amsterdam/drools/facts/amsterdam | python -m json.tool
+
+ .. image:: Tut_vFW_get_facts.JPG
+
+Using the telemetry API, a simulated onset can be injected by the user. For demo purposes, this is the simulated onset that will be used:
+
+ .. image:: Tut_vFW_simulated_onset.JPG
+
+**NOTE:** The onset that gets injected has to have a closedLoopControlName that matches the pushed policy's closedLoopControlName.
+
+Inject the onset using the Telemetry API.
+
+ .. code-block:: bash
+
+ curl --silent --user @1b3rt:31nst31n --header "Content-Type: text/plain" --data @dcae.vfw.onset.json -X PUT http://localhost:9696/policy/pdp/engine/topics/sources/ueb/unauthenticated.DCAE_EVENT_OUTPUT/events | python -m json.tool
+
+ .. image:: Tut_vFW_onset_injected.JPG
+
+Now check the facts in memory, there should be 7 objects present. Two timers exist to put a time limit on the operation and on the overall control loop (in the case of retries or policy chaining). The event and it's associated manager and operation manager are also present in memory. A lock on the target entity is inserted to ensure no other events try to take action on the VNF that is currently processing.
+
+ .. image:: Tut_vFW_get_facts_2.JPG
+
+The network log will be used to monitor the activity coming in and out of the PDP-D. This log is located at *$POLICY_HOME/logs/network.log*. This will show the notifications that the PDP-D sends out at different stages of processing. The order of successful processing begins with an ACTIVE notification to show that the onset was acknowledged and the operation is beginning transit.
+
+ .. image:: Tut_vFW_policy_active.JPG
+
+Next a query will be sent to A&AI to get information on the VNF specified from the onset. The picture below shows the query going OUT of the PDP-D and the response coming IN.
+
+**NOTE:** Policy does A&AI queries for VNF information when the onset is not enriched with A&AI data. In this example only the generic-vnf.vnf-name was provided so a query to A&AI is necessary to retrieve data that is needed in the APPC request.
+
+ .. image:: Tut_vFW_aai_get.JPG
+
+For the vFW use case, the source entity reported in the onset message may not be the target entity that the APPC operation takes action on. To determine the true target entity, an A&AI named query is performed. The request is shown in the network log.
+
+ .. image:: Tut_vFW_aai_named_query_request.JPG
+
+The response is also displayed in the network log.
+
+ .. image:: Tut_vFW_aai_named_query_response.JPG
+
+Once the target entity is found, the PDP-D consults Guard to determine if this operation should be allowed, a series of operation notifications are sent for starting the Guard query, obtaining a PERMIT or DENY, and beginning the operation.
+
+ .. image:: Tut_vFW_policy_guard_start.JPG
+
+ .. image:: Tut_vFW_policy_guard_result.JPG
+
+ .. image:: Tut_vFW_policy_operation_start.JPG
+
+Once the operation starts an APPC request is sent out.
+
+ .. image:: Tut_vFW_appc_request.JPG
+
+A simulated APPC response will be injected to the APPC-CL topic, this is the example response used:
+
+ .. image:: Tut_vFW_simulated_appc_response.JPG
+
+Inject the response using the Telemetry API.
+
+ .. code-block:: bash
+
+ curl --silent --user @1b3rt:31nst31n --header "Content-Type: text/plain" --data @appc.legacy.success.json -X PUT http://localhost:9696/policy/pdp/engine/topics/sources/ueb/APPC-CL/events | python -m json.tool
+
+ .. image:: Tut_vFW_insert_appc_response.JPG
+
+The network log will show the PDP-D sent an operation success notification.
+
+ .. image:: Tut_vFW_policy_operation_success.JPG
+
+Then a final success notification is sent.
+
+ .. image:: Tut_vFW_policy_final_success.JPG
+
+After processing there should only be 1 fact left in memory.
+
+ .. image:: Tut_vFW_final_memory.JPG
+
+
+
+
+End of Document
+
+
+
+
+.. SSNote: Wiki page ref. https://wiki.onap.org/display/DW/Tutorial%3A+Testing+the+vFW+flow+in+a+standalone+PDP-D
+
Code Review / policy / engine.git / commitdiff
