aboutsummaryrefslogtreecommitdiffstats
path: root/docs/drools/pdpdEngine.rst
diff options
context:
space:
mode:
authorjhh <jorge.hernandez-herrero@att.com>2020-06-12 17:01:24 -0500
committerjhh <jorge.hernandez-herrero@att.com>2020-06-15 11:56:21 -0500
commit108dd8ff62cbdfbbe1ba3589afe43582105ea275 (patch)
tree6007bd025b40e1aca92c3cfe1b0672f7645c917d /docs/drools/pdpdEngine.rst
parent11de40286f2a91edc9755f6ea9e621006452527b (diff)
drools documentation redo
Issue-ID: POLICY-2622 Signed-off-by: jhh <jorge.hernandez-herrero@att.com> Change-Id: I568c041f972c76b595964ee3de731c1cde304d8f Signed-off-by: jhh <jorge.hernandez-herrero@att.com>
Diffstat (limited to 'docs/drools/pdpdEngine.rst')
-rw-r--r--docs/drools/pdpdEngine.rst1405
1 files changed, 1405 insertions, 0 deletions
diff --git a/docs/drools/pdpdEngine.rst b/docs/drools/pdpdEngine.rst
new file mode 100644
index 00000000..3456cc6d
--- /dev/null
+++ b/docs/drools/pdpdEngine.rst
@@ -0,0 +1,1405 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+.. _pdpd-engine-label:
+
+PDP-D Engine
+############
+
+.. contents::
+ :depth: 2
+
+Overview
+========
+
+The PDP-D Core Engine provides an infrastructure and services for `drools <https://www.drools.org/>`__ based applications
+in the context of Policies and ONAP.
+
+A PDP-D supports applications by means of *controllers*. A *controller* is a named
+grouping of resources. These typically include references to communication endpoints,
+maven artifact coordinates, and *coders* for message mapping.
+
+*Controllers* use *communication endpoints* to interact
+with remote networked entities typically using messaging (dmaap or ueb),
+or http.
+
+PDP-D Engine capabilities can be extended via *features*. Integration with other
+Policy Framework components (API, PAP, and PDP-X) is through one of them (*feature-lifecycle*).
+
+The PDP-D Engine infrastructure provides mechanisms for data migration, diagnostics, and application management.
+
+Software
+========
+
+Source Code repositories
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The PDP-D software is mainly located in the `policy/drools repository <https://git.onap.org/policy/drools-pdp>`__ with the *communication endpoints* software residing in the `policy/common repository <https://git.onap.org/policy/common>`__ and Tosca policy models in the `policy/models repository <https://git.onap.org/policy/models>`__.
+
+Docker Image
+~~~~~~~~~~~~
+
+Check the *drools-pdp* `released versions <https://wiki.onap.org/display/DW/Policy+Framework+Project%3A+Component+Versions>`__ page for the latest versions.
+At the time of this writing *1.6.3* is the latest version.
+
+.. code-block:: bash
+
+ docker pull onap/policy-drools:1.6.3
+
+A container instantiated from this image will run under the non-priviledged *policy* account.
+
+The PDP-D root directory is located at the */opt/app/policy* directory (or *$POLICY_HOME*), with the
+exception of the *$HOME/.m2* which contains the local maven repository.
+The PDP-D configuration resides in the following directories:
+
+- **/opt/app/policy/config**: (*$POLICY_HOME/config* or *$POLICY_CONFIG*) contains *engine*, *controllers*, and *endpoint* configuration.
+- **/home/policy/.m2**: (*$HOME/.m2*) maven repository configuration.
+- **/opt/app/policy/etc/**: (*$POLICY_HOME/etc*) miscellaneous configuration such as certificate stores.
+
+The following command can be used to explore the directory layout.
+
+.. code-block:: bash
+
+ docker run --rm -it nexus3.onap.org:10001/onap/policy-drools:1.6.3 -- bash
+
+Communication Endpoints
+=======================
+
+PDP-D supports the following networked infrastructures. This is also referred to as
+*communication infrastructures* in the source code.
+
+- DMaaP
+- UEB
+- NOOP
+- Http Servers
+- Http Clients
+
+The source code is located at
+`the policy-endpoints module <https://git.onap.org/policy/common/tree/policy-endpoints>`__
+in the *policy/commons* repository.
+
+These network resources are *named* and typically have a *global* scope, therefore typically visible to
+the PDP-D engine (for administration purposes), application *controllers*,
+and *features*.
+
+DMaaP, UEB, and NOOP are message-based communication infrastructures, hence the terminology of
+source and sinks, to denote their directionality into or out of the *controller*, respectively.
+
+An endpoint can either be *managed* or *unmanaged*. The default for an endpoint is to be *managed*,
+meaning that they are globally accessible by name, and managed by the PDP-D engine.
+*Unmanaged* topics are used when neither global visibility, or centralized PDP-D management is desired.
+The software that uses *unmanaged* topics is responsible for their lifecycle management.
+
+DMaaP Endpoints
+~~~~~~~~~~~~~~~
+
+These are messaging enpoints that use DMaaP as the communication infrastructure.
+
+Typically, a *managed* endpoint configuration is stored in the *<topic-name>-topic.properties* files.
+
+For example, the
+`DCAE_TOPIC-topic.properties <https://git.onap.org/policy/drools-applications/tree/controlloop/common/feature-controlloop-management/src/main/feature/config/DCAE_TOPIC-topic.properties>`__ is defined as
+
+.. code-block:: bash
+
+ dmaap.source.topics=DCAE_TOPIC
+
+ dmaap.source.topics.DCAE_TOPIC.effectiveTopic=${env:DCAE_TOPIC}
+ dmaap.source.topics.DCAE_TOPIC.servers=${env:DMAAP_SERVERS}
+ dmaap.source.topics.DCAE_TOPIC.consumerGroup=${env:DCAE_CONSUMER_GROUP}
+ dmaap.source.topics.DCAE_TOPIC.https=true
+
+In this example, the generic name of the *source* endpoint
+is *DCAE_TOPIC*. This is known as the *canonical* name.
+The actual *topic* used in communication exchanges in a physical lab is contained
+in the *$DCAE_TOPIC* environment variable. This environment variable is usually
+set up by *devops* on a per installation basis to meet the needs of each
+lab spec.
+
+In the previous example, *DCAE_TOPIC* is a source-only topic.
+
+Sink topics are similarly specified but indicating that are sink endpoints
+from the perspective of the *controller*. For example, the *APPC-CL* topic
+is configured as
+
+.. code-block:: bash
+
+ dmaap.source.topics=APPC-CL
+ dmaap.sink.topics=APPC-CL
+
+ dmaap.source.topics.APPC-CL.servers=${env:DMAAP_SERVERS}
+ dmaap.source.topics.APPC-CL.https=true
+
+ dmaap.sink.topics.APPC-CL.servers=${env:DMAAP_SERVERS}
+ dmaap.sink.topics.APPC-CL.https=true
+
+Although not shown in these examples, additional configuration options are available such as *user name*,
+*password*, *security keys*, *consumer group* and *consumer instance*.
+
+UEB Endpoints
+~~~~~~~~~~~~~
+
+Similary, UEB endpoints are messaging endpoints, similar to the DMaaP ones.
+
+For example, the
+`DCAE_TOPIC-topic.properties <https://git.onap.org/policy/drools-applications/tree/controlloop/common/feature-controlloop-management/src/main/feature/config/DCAE_TOPIC-topic.properties>`__ can be converted to an *UEB* one, by replacing the
+*dmaap* prefix with *ueb*. For example:
+
+.. code-block:: bash
+
+ ueb.source.topics=DCAE_TOPIC
+
+ ueb.source.topics.DCAE_TOPIC.effectiveTopic=${env:DCAE_TOPIC}
+ ueb.source.topics.DCAE_TOPIC.servers=${env:DMAAP_SERVERS}
+ ueb.source.topics.DCAE_TOPIC.consumerGroup=${env:DCAE_CONSUMER_GROUP}
+ ueb.source.topics.DCAE_TOPIC.https=true
+
+NOOP Endpoints
+~~~~~~~~~~~~~~
+
+NOOP (no-operation) endpoints are messaging endpoints that don't have any network attachments.
+They are used for testing convenience.
+To convert the
+`DCAE_TOPIC-topic.properties <https://git.onap.org/policy/drools-applications/tree/controlloop/common/feature-controlloop-management/src/main/feature/config/DCAE_TOPIC-topic.properties>`__ to a *NOOP* endpoint, simply replace the *dmaap* prefix with *noop*:
+
+.. code-block:: bash
+
+ noop.source.topics=DCAE_TOPIC
+ noop.source.topics.DCAE_TOPIC.effectiveTopic=${env:DCAE_TOPIC}
+
+HTTP Clients
+~~~~~~~~~~~~
+
+HTTP Clients are typically stored in files following the naming convention: *<name>-http-client.properties* convention.
+One such example is
+the `AAI HTTP Client <https://git.onap.org/policy/drools-applications/tree/controlloop/common/feature-controlloop-management/src/main/feature/config/AAI-http-client.properties>`__:
+
+.. code-block:: bash
+
+ http.client.services=AAI
+
+ http.client.services.AAI.managed=true
+ http.client.services.AAI.https=true
+ http.client.services.AAI.host=${envd:AAI_HOST}
+ http.client.services.AAI.port=${envd:AAI_PORT}
+ http.client.services.AAI.userName=${envd:AAI_USERNAME}
+ http.client.services.AAI.password=${envd:AAI_PASSWORD}
+ http.client.services.AAI.contextUriPath=${envd:AAI_CONTEXT_URI}
+
+HTTP Servers
+~~~~~~~~~~~~
+
+HTTP Servers are stored in files that follow a similar naming convention *<name>-http-server.properties*.
+The following is an example of a server named *CONFIG*, getting most of its configuration from
+environment variables.
+
+.. code-block:: bash
+
+ http.server.services=CONFIG
+
+ http.server.services.CONFIG.host=${envd:TELEMETRY_HOST}
+ http.server.services.CONFIG.port=7777
+ http.server.services.CONFIG.userName=${envd:TELEMETRY_USER}
+ http.server.services.CONFIG.password=${envd:TELEMETRY_PASSWORD}
+ http.server.services.CONFIG.restPackages=org.onap.policy.drools.server.restful
+ http.server.services.CONFIG.managed=false
+ http.server.services.CONFIG.swagger=true
+ http.server.services.CONFIG.https=true
+ http.server.services.CONFIG.aaf=${envd:AAF:false}
+
+*Endpoints* configuration resides in the *$POLICY_HOME/config* (or *$POLICY_CONFIG*) directory in a container.
+
+Controllers
+===========
+
+*Controllers* are the means for the PDP-D to run *applications*. Controllers are
+defined in *<name>-controller.properties* files.
+
+For example, see the
+`frankfurt controller configuration <https://git.onap.org/policy/drools-applications/tree/controlloop/common/feature-controlloop-frankfurt/src/main/feature/config/frankfurt-controller.properties>`__.
+
+This configuration file has two sections: *a)* application maven coordinates, and *b)* endpoint references and coders.
+
+Maven Coordinates
+~~~~~~~~~~~~~~~~~
+
+The coordinates section (*rules*) points to the *controller-frankfurt* *kjar* artifact.
+It is the *brain* of the control loop application.
+
+.. code-block:: bash
+
+ controller.name=frankfurt
+
+ rules.groupId=${project.groupId}
+ rules.artifactId=controller-frankfurt
+ rules.version=${project.version}
+ .....
+
+This *kjar* contains the
+`frankfurt DRL <https://git.onap.org/policy/drools-applications/tree/controlloop/common/controller-frankfurt/src/main/resources/frankfurt.drl>`__ file (there may be more than one DRL file included).
+
+.. code-block:: bash
+
+ ...
+ rule "NEW.TOSCA.POLICY"
+ when
+ $policy : ToscaPolicy()
+ then
+
+ ...
+
+ ControlLoopParams params = ControlLoopUtils.toControlLoopParams($policy);
+ if (params != null) {
+ insert(params);
+ }
+ end
+ ...
+
+The DRL in conjuction with the dependent java libraries in the kjar
+`pom <https://git.onap.org/policy/drools-applications/tree/controlloop/common/controller-frankfurt/pom.xml>`__
+realizes the application's function. For intance, it realizes the
+vFirewall, vCPE, and vDNS use cases in ONAP.
+
+.. code-block:: bash
+
+ ..
+ <dependency>
+ <groupId>org.onap.policy.models.policy-models-interactions.model-actors</groupId>
+ <artifactId>actor.appclcm</artifactId>
+ <version>${policy.models.version}</version>
+ <scope>provided</scope>
+ </dependency>
+ ...
+
+Endpoints References and Coders
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The *frankfurt-controller.properties* configuration also contains a mix of
+source (of incoming controller traffic) and sink (of outgoing controller traffic)
+configuration. This configuration also contains specific
+filtering and mapping rules for incoming and outgoing dmaap messages
+known as *coders*.
+
+.. code-block:: bash
+
+ ...
+ dmaap.source.topics=DCAE_TOPIC,APPC-CL,APPC-LCM-WRITE,SDNR-CL-RSP
+ dmaap.sink.topics=APPC-CL,APPC-LCM-READ,POLICY-CL-MGT,SDNR-CL,DCAE_CL_RSP
+
+
+ dmaap.source.topics.APPC-LCM-WRITE.events=org.onap.policy.appclcm.AppcLcmDmaapWrapper
+ dmaap.source.topics.APPC-LCM-WRITE.events.org.onap.policy.appclcm.AppcLcmDmaapWrapper.filter=[?($.type == 'response')]
+ dmaap.source.topics.APPC-LCM-WRITE.events.custom.gson=org.onap.policy.appclcm.util.Serialization,gson
+
+ dmaap.sink.topics.APPC-CL.events=org.onap.policy.appc.Request
+ dmaap.sink.topics.APPC-CL.events.custom.gson=org.onap.policy.appc.util.Serialization,gsonPretty
+ ...
+
+In this example, the *coders* specify that incoming messages over the DMaaP endpoint
+reference *APPC-LCM-WRITE*, that have a field called *type* under the root JSON object with
+value *response* are allowed into the *controller* application. In this case, the incoming
+message is converted into an object (fact) of type *org.onap.policy.appclcm.AppcLcmDmaapWrapper*.
+The *coder* has attached a custom implementation provided by the *application* with class
+*org.onap.policy.appclcm.util.Serialization*. Note that the *coder* filter is expressed in JSONPath notation.
+
+Note that not all the communication endpoint references need to be explicitly referenced within the
+*controller* configuration file. For example, *Http clients* do not.
+The reasons are historical, as the PDP-D was initially intended to only communicate
+through messaging-based protocols such as UEB or DMaaP in asynchronous unidirectional mode.
+The introduction of *Http* with synchronous bi-directional communication with remote endpoints made
+it more convenient for the application to manage each network exchange.
+
+*Controllers* configuration resides in the *$POLICY_HOME/config* (or *$POLICY_CONFIG*) directory in a container.
+
+Other Configuration Files
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There are other types of configuration files that *controllers* can use, for example *.environment* files
+that provides a means to share data across applications. The
+`controlloop.properties.environment <https://git.onap.org/policy/drools-applications/tree/controlloop/common/feature-controlloop-management/src/main/feature/config/controlloop.properties.environment>`__ is one such example.
+
+
+Tosca Policies
+==============
+
+PDP-D supports Tosca Policies through the *feature-lifecycle*. The *PDP-D* receives its policy set
+from the *PAP*. A policy conforms to its Policy Type specification.
+Policy Types and policy creation is done by the *API* component.
+Policy deployments are orchestrated by the *PAP*.
+
+All communication between *PAP* and PDP-D is over the DMaaP *POLICY-PDP-PAP* topic.
+
+Native Policy Types
+~~~~~~~~~~~~~~~~~~~
+
+The PDP-D Engine supports two (native) Tosca policy types by means of the *lifecycle*
+feature:
+
+- *onap.policies.native.drools.Controller*
+- *onap.policies.native.drools.Artifact*
+
+These types can be used to dynamically deploy or undeploy application *controllers*,
+assign policy types, and upgrade or downgrade their attached maven artifact versions.
+
+For instance, an
+`example native controller <https://git.onap.org/policy/drools-pdp/tree/feature-lifecycle/src/test/resources/tosca-policy-native-controller-example.json>`__ policy is shown below.
+
+.. code-block:: bash
+
+ {
+ "tosca_definitions_version": "tosca_simple_yaml_1_0_0",
+ "topology_template": {
+ "policies": [
+ {
+ "example.controller": {
+ "type": "onap.policies.native.drools.Controller",
+ "type_version": "1.0.0",
+ "version": "1.0.0",
+ "name": "example.controller",
+ "metadata": {
+ "policy-id": "example.controller"
+ },
+ "properties": {
+ "controllerName": "lifecycle",
+ "sourceTopics": [
+ {
+ "topicName": "DCAE_TOPIC",
+ "events": [
+ {
+ "eventClass": "java.util.HashMap",
+ "eventFilter": "[?($.closedLoopEventStatus == 'ONSET')]"
+ },
+ {
+ "eventClass": "java.util.HashMap",
+ "eventFilter": "[?($.closedLoopEventStatus == 'ABATED')]"
+ }
+ ]
+ }
+ ],
+ "sinkTopics": [
+ {
+ "topicName": "APPC-CL",
+ "events": [
+ {
+ "eventClass": "java.util.HashMap",
+ "eventFilter": "[?($.CommonHeader && $.Status)]"
+ }
+ ]
+ }
+ ],
+ "customConfig": {
+ "field1" : "value1"
+ }
+ }
+ }
+ }
+ ]
+ }
+ }
+
+The actual application coordinates are provided with a policy of type onap.policies.native.drools.Artifact,
+see the `example native artifact <https://git.onap.org/policy/drools-pdp/tree/feature-lifecycle/src/test/resources/tosca-policy-native-artifact-example.json>`__
+
+.. code-block:: bash
+
+ {
+ "tosca_definitions_version": "tosca_simple_yaml_1_0_0",
+ "topology_template": {
+ "policies": [
+ {
+ "example.artifact": {
+ "type": "onap.policies.native.drools.Artifact",
+ "type_version": "1.0.0",
+ "version": "1.0.0",
+ "name": "example.artifact",
+ "metadata": {
+ "policy-id": "example.artifact"
+ },
+ "properties": {
+ "rulesArtifact": {
+ "groupId": "org.onap.policy.drools.test",
+ "artifactId": "lifecycle",
+ "version": "1.0.0"
+ },
+ "controller": {
+ "name": "lifecycle"
+ }
+ }
+ }
+ }
+ ]
+ }
+ }
+
+Operational Policy Types
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The PDP-D also recognizes Tosca Operational Policies, although it needs an
+application *controller* that understands them to execute them. These are:
+
+- *onap.policies.controlloop.operational.common.Drools*
+- *onap.policies.controlloop.Operational*
+
+A minimum of one application *controller* that supports these capabilities
+must be installed in order to honor the *operational policy types*.
+One such controller is the *frankfurt* controller residing in the
+`policy/drools-applications <https://git.onap.org/policy/drools-applications>`__
+repository.
+
+Controller Policy Type Support
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Note that a *controller* may support other policy types. A controller may declare them
+explicitly in a native *onap.policies.native.drools.Controller* policy.
+
+.. code-block:: bash
+
+ "customConfig": {
+ "controller.policy.types" : "policy.type.A"
+ }
+
+The *controller* application could declare its supported policy types in the *kjar*.
+For example, the *frankfurt controller* packages this information in the
+`kmodule.xml <https://git.onap.org/policy/drools-applications/tree/controlloop/common/controller-frankfurt/src/main/resources/META-INF/kmodule.xml>`__. One advantage of this approach is that the PDP-D would only
+commit to execute policies against these policy types if a supporting controller is up and running.
+
+.. code-block:: bash
+
+ <kmodule xmlns="http://jboss.org/kie/6.0.0/kmodule">
+ <kbase name="onap.policies.controlloop.operational.common.Drools" default="false" equalsBehavior="equality"/>
+ <kbase name="onap.policies.controlloop.Operational" equalsBehavior="equality"
+ packages="org.onap.policy.controlloop" includes="onap.policies.controlloop.operational.common.Drools">
+ <ksession name="frankfurt"/>
+ </kbase>
+ </kmodule>
+
+Software Architecture
+======================
+
+PDP-D is divided into 2 layers:
+
+- core (`policy-core <https://git.onap.org/policy/drools-pdp/tree/policy-core>`__)
+- management (`policy-management <https://git.onap.org/policy/drools-pdp/tree/policy-management>`__)
+
+Core Layer
+~~~~~~~~~~
+
+The core layer directly interfaces with the *drools* libraries with 2 main abstractions:
+
+* `PolicyContainer <https://git.onap.org/policy/drools-pdp/tree/policy-core/src/main/java/org/onap/policy/drools/core/PolicyContainer.java>`__, and
+* `PolicySession <https://git.onap.org/policy/drools-pdp/tree/policy-core/src/main/java/org/onap/policy/drools/core/PolicySession.java>`__.
+
+Policy Container and Sessions
+"""""""""""""""""""""""""""""
+
+The *PolicyContainer* abstracts the drools *KieContainer*, while a *PolicySession* abstracts a drools *KieSession*.
+PDP-D uses stateful sessions in active mode (*fireUntilHalt*) (please visit the `drools <https://www.drools.org/>`__
+website for additional documentation).
+
+Management Layer
+~~~~~~~~~~~~~~~~
+
+The management layer manages the PDP-D and builds on top of the *core* capabilities.
+
+PolicyEngine
+""""""""""""
+
+The PDP-D `PolicyEngine <https://git.onap.org/policy/drools-pdp/tree/policy-management/src/main/java/org/onap/policy/drools/system/PolicyEngine.java>`__ is the top abstraction and abstracts away the PDP-D and all the
+resources it holds. The reader looking at the source code can start looking at this component
+in a top-down fashion. Note that the *PolicyEngine* abstraction should not be confused with the
+sofware in the *policy/engine* repository, there is no relationship whatsoever other than in the naming.
+
+The *PolicyEngine* represents the PDP-D, holds all PDP-D resources, and orchestrates activities among those.
+
+The *PolicyEngine* manages applications via the `PolicyController <https://git.onap.org/policy/drools-pdp/tree/policy-management/src/main/java/org/onap/policy/drools/system/PolicyController.java>`__ abstractions in the base code. The
+relationship between the *PolicyEngine* and *PolicyController* is one to many.
+
+The *PolicyEngine* holds other global resources such as a *thread pool*, *policies validator*, *telemetry* server,
+and *unmanaged* topics for administration purposes.
+
+The *PolicyEngine* has interception points that allow
+`*features* <https://git.onap.org/policy/drools-pdp/tree/policy-management/src/main/java/org/onap/policy/drools/features/PolicyEngineFeatureApi.java>`__
+to observe and alter the default *PolicyEngine* behavior.
+
+The *PolicyEngine* implements the `*Startable* <https://git.onap.org/policy/common/tree/capabilities/src/main/java/org/onap/policy/common/capabilities/Startable.java>`__ and `*Lockable* <https://git.onap.org/policy/common/tree/capabilities/src/main/java/org/onap/policy/common/capabilities/Lockable.java>`__ interfaces. These operations
+have a cascading effect on the resources the *PolicyEngine* holds, as it is the top level entity, thus
+affecting *controllers* and *endpoints*. These capabilities are intended to be used for extensions,
+for example active/standby multi-node capabilities. This programmability is
+exposed via the *telemetry* API, and *feature* hooks.
+
+Configuration
+^^^^^^^^^^^^^
+
+*PolicyEngine* related configuration is located in the
+`engine.properties <https://git.onap.org/policy/drools-pdp/tree/policy-management/src/main/server/config/engine.properties>`__,
+and `engine-system.properties <https://git.onap.org/policy/drools-pdp/tree/policy-management/src/main/server/config/engine.properties>`__.
+
+The *engine* configuration files reside in the *$POLICY_CONFIG* directory.
+
+PolicyController
+""""""""""""""""
+
+A *PolicyController* represents an application. Each *PolicyController* has an instance of a
+`DroolsController <https://git.onap.org/policy/drools-pdp/tree/policy-management/src/main/java/org/onap/policy/drools/system/PolicyController.java>`__. The *PolicyController* provides the means to group application specific resources
+into a single unit. Such resources include the application's *maven coordinates*, *endpoint references*, and *coders*.
+
+A *PolicyController* uses a
+`DroolsController <https://git.onap.org/policy/drools-pdp/tree/policy-management/src/main/java/org/onap/policy/drools/controller/DroolsController.java>`__ to interface with the *core* layer (*PolicyContainer* and *PolicySession*).
+
+The relationship between the *PolicyController* and the *DroolsController* is one-to-one.
+The *DroolsController* currently supports 2 implementations, the
+`MavenDroolsController <https://git.onap.org/policy/drools-pdp/tree/policy-management/src/main/java/org/onap/policy/drools/controller/internal/MavenDroolsController.java>`__, and the
+`NullDroolsController <https://git.onap.org/policy/drools-pdp/tree/policy-management/src/main/java/org/onap/policy/drools/controller/internal/NullDroolsController.java>`__.
+The *DroolsController*'s polymorphic behavior depends on whether a maven artifact is attached to the controller or not.
+
+Configuration
+^^^^^^^^^^^^^
+
+The *controllers* configuration resides in the *$POLICY_CONFIG* directory.
+
+Programmability
+~~~~~~~~~~~~~~~
+
+PDP-D is programmable through:
+
+- Features and Event Listeners.
+- Maven-Drools applications.
+
+Using Features and Listeners
+""""""""""""""""""""""""""""
+
+Features hook into the interception points provided by the the *PDP-D* main entities.
+
+*Endpoint Listeners*, see `here <https://git.onap.org/policy/common/tree/policy-endpoints/src/main/java/org/onap/policy/common/endpoints/event/comm/TopicListener.java>`__
+and `here <https://git.onap.org/policy/common/tree/policy-endpoints/src/main/java/org/onap/policy/common/endpoints/listeners>`__, can be used in conjuction with features for additional capabilities.
+
+Using Maven-Drools applications
+"""""""""""""""""""""""""""""""
+
+Maven-based drools applications can run any arbitrary functionality structured with rules and java logic.
+
+Recommended Flow
+""""""""""""""""
+
+Whenever possible it is suggested that PDP-D related operations flow through the
+*PolicyEngine* downwards in a top-down manner. This imposed order implies that
+all the feature hooks are always invoked in a deterministic fashion. It is also
+a good mechanism to safeguard against deadlocks.
+
+Telemetry Extensions
+""""""""""""""""""""
+
+It is recommended to *features* (extensions) to offer a diagnostics REST API
+to integrate with the telemetry API. This is done by placing JAX-RS files under
+the package *org.onap.policy.drools.server.restful*. The root context path
+for all the telemetry services is */policy/pdp/engine*.
+
+Features
+========
+
+*Features* is an extension mechanism for the PDP-D functionality.
+Features can be toggled on and off.
+A feature is composed of:
+
+- Java libraries.
+- Scripts and configuration files.
+
+Java Extensions
+~~~~~~~~~~~~~~~
+
+Additional functionality can be provided in the form of java libraries that hook into the
+*PolicyEngine*, *PolicyController*, *DroolsController*, and *PolicySession* interception
+points to observe or alter the PDP-D logic.
+
+See the Feature APIs available in the
+`management <https://git.onap.org/policy/drools-pdp/tree/policy-management/src/main/java/org/onap/policy/drools/features>`__
+and
+`core <https://git.onap.org/policy/drools-pdp/tree/policy-core/src/main/java/org/onap/policy/drools/core/PolicySessionFeatureApi.java>`__ layers.
+
+The convention used for naming these extension modules are *api-<name>* for interfaces,
+and *feature-<name>* for the actual java extensions.
+
+Configuration Items
+~~~~~~~~~~~~~~~~~~~
+
+Installation items such as scripts, SQL, maven artifacts, and configuration files.
+
+The reader can refer to the `policy/drools-pdp repository <https://git.onap.org/policy/drools-pdp>`__
+and the <https://git.onap.org/policy/drools-applications>`__ repository for miscellaneous feature
+implementations.
+
+Layout
+""""""
+
+A feature is packaged in a *feature-<name>.zip* and has this internal layout:
+
+.. code-block:: bash
+
+ # #######################################################################################
+ # Features Directory Layout:
+ #
+ # $POLICY_HOME/
+ # L─ features/
+ # L─ <feature-name>*/
+ #     L─ [config]/
+ #     |   L─ <config-file>+
+ #     L─ [bin]/
+ #     |   L─ <bin-file>+
+ #     L─ lib/
+ #     |  L─ [dependencies]/
+ #     |  | L─ <dependent-jar>+
+ #     │  L─ feature/
+ #     │  L─ <feature-jar>
+ #     L─ [db]/
+ #     │   L─ <db-name>/+
+ #     │  L─ sql/
+ #     │ L─ <sql-scripts>*
+ #     L─ [artifacts]/
+ #      L─ <artifact>+
+ #     L─ [install]
+ #      L─ [enable]
+ #      L─ [disable]
+ #      L─ [other-directories-or-files]
+ #
+ # notes: [] = optional , * = 0 or more , + = 1 or more
+ # <feature-name> directory without "feature-" prefix.
+ # [config] feature configuration directory that contains all configuration
+ # needed for this features
+ # [config]/<config-file> preferably named with "feature-<feature-name>" prefix to
+ # precisely match it against the exact features, source code, and
+ # associated wiki page for configuration details.
+ # [bin] feature bin directory that contains helper scripts for this feature
+ # [bin]/<executable-file> preferably named with "feature-<feature-name>" prefix.
+ # lib jar libraries needed by this features
+ # lib/[dependencies] 3rd party jar dependencies not provided by base installation
+ # of pdp-d that are necessary for <feature-name> to operate
+ # correctly.
+ # lib/feature the single feature jar that implements the feature.
+ # [db] database directory, if the feature contains sql.
+ # [db]/<db-name> database to which underlying sql scripts should be applied.
+ # ideally, <db-name> = <feature-name> so it is easily to associate
+ # the db data with a feature itself. In addition, since a feature is
+ # a somewhat independent isolated unit of functionality,the <db-name>
+ # database ideally isolates all its data.
+ # [db]/<db-name>/sql directory with all the sql scripts.
+ # [db]/<db-name>/sql/<sql-scripts> for this feature, sql
+ # upgrade scripts should be suffixed with ".upgrade.sql"
+ # and downgrade scripts should be suffixed with ".downgrade.sql"
+ # [artifacts] maven artifacts to be deployed in a maven repository.
+ # [artifacts]/<artifact> maven artifact with identifiable maven coordinates embedded
+ # in the artifact.
+ # [install] custom installation directory where custom enable or disable scripts
+ # and other free form data is included to be used for the enable and
+ # and disable scripts.
+ # [install]/[enable] enable script executed when the enable operation is invoked in
+ # the feature.
+ # [install]/[disable] disable script executed when the disable operation is invoked in
+ # the feature.
+ # [install]/[other-directories-or-files] other executables, or data that can be used
+ # by the feature for any of its operations. The content is determined
+ # by the feature designer.
+ # ########################################################################################
+
+The `features <https://git.onap.org/policy/drools-pdp/tree/policy-management/src/main/server-gen/bin/features>`__
+is the tool used for administration purposes:
+
+.. code-block:: bash
+
+ Usage: features status
+ Get enabled/disabled status on all features
+ features enable <feature> ...
+ Enable the specified feature
+ features disable <feature> ...
+ Disable the specified feature
+ features install [ <feature> | <file-name> ] ...
+ Install the specified feature
+ features uninstall <feature> ...
+ Uninstall the specified feature
+
+Features available in the Docker image
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The only enabled feature in the *onap/policy-drools* image is:
+
+- **lifecycle**: enables the lifecycle capability to integrate with the Policy Framework components.
+
+The following features are included in the image but disabled.
+
+- **distributed locking**: distributed resource locking.
+- **healthcheck**: basic PDP-D Engine healthcheck.
+
+Healthcheck
+"""""""""""
+
+The Healthcheck feature provides reports used to verify the health of *PolicyEngine.manager* in addition to the construction, operation, and deconstruction of HTTP server/client objects.
+
+When enabled, the feature takes as input a properties file named "*feature-healtcheck.properties*.
+This file should contain configuration properties necessary for the construction of HTTP client and server objects.
+
+Upon initialization, the feature first constructs HTTP server and client objects using the properties
+from its properties file. A healthCheck operation is then triggered. The logic of the healthCheck verifies
+that *PolicyEngine.manager* is alive, and iteratively tests each HTTP server object by sending HTTP GET
+requests using its respective client object. If a server returns a "200 OK" message, it is marked as "healthy"
+in its individual report. Any other return code results in an "unhealthy" report.
+
+After the testing of the server objects has completed, the feature returns a single consolidated report.
+
+Lifecycle
+"""""""""
+
+The "lifecycle" feature enables a PDP-D to work with the architectural framework introduced in the
+Dublin release.
+
+The lifecycle feature maintains three states: TERMINATED, PASSIVE, and ACTIVE.
+The PAP interacts with the lifecycle feature to put a PDP-D in PASSIVE or ACTIVE states.
+The PASSIVE state allows for Tosca Operational policies to be deployed.
+Policy execution is enabled when the PDP-D transitions to the ACTIVE state.
+
+This feature can coexist side by side with the legacy mode of operation that pre-dates the Dublin release.
+
+Distributed Locking
+"""""""""""""""""""
+
+The Distributed Locking Feature provides locking of resources across a pool of PDP-D hosts.
+The list of locks is maintained in a database, where each record includes a resource identifier,
+an owner identifier, and an expiration time. Typically, a drools application will unlock the resource
+when it's operation completes. However, if it fails to do so, then the resource will be automatically
+released when the lock expires, thus preventing a resource from becoming permanently locked.
+
+Other features
+~~~~~~~~~~~~~~
+
+The following features have been contributed to the *policy/drools-pdp* but are either
+unnecessary or have not been thoroughly tested:
+
+.. toctree::
+ :maxdepth: 1
+
+ feature_activestdbymgmt.rst
+ feature_controllerlogging.rst
+ feature_eelf.rst
+ feature_mdcfilters.rst
+ feature_pooling.rst
+ feature_sesspersist.rst
+ feature_statemgmt.rst
+ feature_testtransaction.rst
+
+Data Migration
+==============
+
+PDP-D data is migrated across releases with the
+`db-migrator <https://git.onap.org/policy/drools-pdp/tree/policy-management/src/main/server-gen/bin/db-migrator>`__.
+
+The migration occurs when different release data is detected. *db-migrator* will look under the
+*$POLICY_HOME/etc/db/migration* for databases and SQL scripts to migrate.
+
+.. code-block:: bash
+
+ $POLICY_HOME/etc/db/migration/<schema-name>/sql/<sql-file>
+
+where *<sql-file>* is of the form:
+
+.. code-block:: bash
+
+ <VERSION>-<pdp|feature-name>[-description](.upgrade|.downgrade).sql
+
+The db-migrator tool syntax is
+
+.. code-block:: bash
+
+ syntax: db-migrator
+ -s <schema-name>
+ [-b <migration-dir>]
+ [-f <from-version>]
+ [-t <target-version>]
+ -o <operations>
+
+ where <operations>=upgrade|downgrade|auto|version|erase|report
+
+ Configuration Options:
+ -s|--schema|--database: schema to operate on ('ALL' to apply on all)
+ -b|--basedir: overrides base DB migration directory
+ -f|--from: overrides current release version for operations
+ -t|--target: overrides target release to upgrade/downgrade
+
+ Operations:
+ upgrade: upgrade operation
+ downgrade: performs a downgrade operation
+ auto: autonomous operation, determines upgrade or downgrade
+ version: returns current version, and in conjunction if '-f' sets the current version
+ erase: erase all data related <schema> (use with care)
+ report: migration detailed report on an schema
+ ok: is the migration status valid
+
+See the
+`feature-distributed-locking sql directory <https://git.onap.org/policy/drools-pdp/tree/feature-distributed-locking/src/main/feature/db/pooling/sql>`__
+for an example of upgrade/downgrade scripts.
+
+The following command will provide a report on the upgrade or downgrade activies:
+
+.. code-block:: bash
+
+ db-migrator -s ALL -o report
+
+For example in the official frankfurt delivery:
+
+.. code-block:: bash
+
+ policy@dev-drools-0:/tmp/policy-install$ db-migrator -s ALL -o report
+ +---------+---------+
+ | name | version |
+ +---------+---------+
+ | pooling | 1811 |
+ +---------+---------+
+ +-------------------------------------+-----------+---------+---------------------+
+ | script | operation | success | atTime |
+ +-------------------------------------+-----------+---------+---------------------+
+ | 1804-distributedlocking.upgrade.sql | upgrade | 1 | 2020-05-22 19:33:09 |
+ | 1811-distributedlocking.upgrade.sql | upgrade | 1 | 2020-05-22 19:33:09 |
+ +-------------------------------------+-----------+---------+---------------------+
+
+In order to use the *db-migrator* tool, the system must be configured with a database.
+
+.. code-block:: bash
+
+ SQL_HOST=mariadb
+
+Maven Repositories
+==================
+
+The drools libraries in the PDP-D uses maven to fetch rules artifacts and software dependencies.
+
+The default *settings.xml* file specifies the repositories to search. This configuration
+can be overriden with a custom copy that would sit in a mounted configuration
+directory. See an example of the OOM override
+`settings.xml <https://git.onap.org/oom/tree/kubernetes/policy/charts/drools/resources/configmaps/settings.xml>`__.
+
+The default ONAP installation of the *control loop* child image *onap/policy-pdpd-cl:1.6.4* is *OFFLINE*.
+In this configuration, the *rules* artifact and the *dependencies* retrieves all the artifacts from the local
+maven repository. Of course, this requires that the maven dependencies are preloaded in the local
+repository for it to work.
+
+An offline configuration requires two items:
+
+- *OFFLINE* environment variable set to true.
+- override *settings.xml* customization, see
+ `settings.xml <https://git.onap.org/oom/tree/kubernetes/policy/charts/drools/resources/configmaps/settings.xml>`__.
+
+The default mode in the *onap/policy-drools:1.6.3* is ONLINE instead.
+
+In *ONLINE* mode, the *controller* initialization can take a significant amount of time.
+
+The Policy ONAP installation includes a *nexus* repository component that can be used to host any arbitrary
+artifacts that an PDP-D application may require.
+The following environment variables configure its location:
+
+.. code-block:: bash
+
+ SNAPSHOT_REPOSITORY_ID=policy-nexus-snapshots
+ SNAPSHOT_REPOSITORY_URL=http://nexus:8080/nexus/content/repositories/snapshots/
+ RELEASE_REPOSITORY_ID=policy-nexus-releases
+ RELEASE_REPOSITORY_URL=http://nexus:8080/nexus/content/repositories/releases/
+ REPOSITORY_OFFLINE=false
+
+The *deploy-artifact* tool is used to deploy artifacts to the local or remote maven repositories.
+It also allows for dependencies to be installed locally. The *features* tool invokes it when artifacts are
+to be deployed as part of a feature. The tool can be useful for developers to test a new application
+in a container.
+
+.. code-block:: bash
+
+ syntax: deploy-artifact
+ [-f|-l|-d]
+ -s <custom-settings>
+ -a <artifact>
+
+ Options:
+ -f|--file-repo: deploy in the file repository
+ -l|--local-repo: install in the local repository
+ -d|--dependencies: install dependencies in the local repository
+ -s|--settings: custom settings.xml
+ -a|--artifact: file artifact (jar or pom) to deploy and/or install
+
+AAF
+===
+
+Policy can talk to AAF for authorization requests. To enable AAF set
+the following environment variables:
+
+.. code-block:: bash
+
+ AAF=true
+ AAF_NAMESPACE=org.onap.policy
+ AAF_HOST=aaf-locate.onap
+
+By default AAF is disabled.
+
+Policy Tool
+===========
+
+The *policy* tool can be used to stop, start, and provide status on the PDP-D.
+
+.. code-block:: bash
+
+ syntax: policy [--debug] status|start|stop
+
+The *status* option provides generic status of the system.
+
+.. code-block:: bash
+
+ [drools-pdp-controllers]
+ L []: Policy Management (pid 408) is running
+ 0 cron jobs installed.
+
+ [features]
+ name version status
+ ---- ------- ------
+ healthcheck 1.6.3 enabled
+ distributed-locking 1.6.3 enabled
+ lifecycle 1.6.3 enabled
+ controlloop-management 1.6.4 enabled
+ controlloop-utils 1.6.4 enabled
+ controlloop-trans 1.6.4 enabled
+ controlloop-frankfurt 1.6.4 enabled
+ controlloop-usecases 1.6.4 disabled
+
+ [migration]
+ pooling: OK @ 1811
+
+It contains 3 sections:
+
+- *PDP-D* running status
+- *features* applied
+- Data migration status on a per database basis.
+
+The *start* and *stop* commands are useful for developers testing functionality on a docker container instance.
+
+Telemetry Shell
+===============
+
+*PDP-D* offers an ample set of REST APIs to debug, introspect, and change state on a running PDP-D. This is known as the
+*telemetry* API. The *telemetry* shell wraps these APIs for shell-like access using
+`http-prompt <http://http-prompt.com/>`__.
+
+.. code-block:: bash
+
+ policy@dev-drools-0:~$ telemetry
+ Version: 1.0.0
+ https://localhost:9696/policy/pdp/engine> get controllers
+ HTTP/1.1 200 OK
+ Content-Length: 13
+ Content-Type: application/json
+ Date: Thu, 04 Jun 2020 01:07:38 GMT
+ Server: Jetty(9.4.24.v20191120)
+
+ [
+ "frankfurt"
+ ]
+
+ https://localhost:9696/policy/pdp/engine> exit
+ Goodbye!
+ policy@dev-drools-0:~$
+
+
+Other tools
+===========
+
+Refer to the *$POLICY_HOME/bin/* directory for additional tooling.
+
+PDP-D Docker Container Configuration
+====================================
+
+Both the PDP-D *onap/policy-drools* and *onap/policy-pdpd-cl* images can be used without other components.
+
+There are 2 types of configuration data provided to the container:
+
+1. environment variables.
+2. configuration files and shell scripts.
+
+Environment variables
+~~~~~~~~~~~~~~~~~~~~~
+
+As it was shown in the *controller* and *endpoint* sections, PDP-D configuration can rely
+on environment variables. In a container environment, these variables are set up by the user
+in the host environment.
+
+Configuration Files and Shell Scripts
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+PDP-D is very flexible in its configuration.
+
+The following file types are recognized when mounted under */tmp/policy-install/config*.
+
+These are the configuration items that can reside externally and override the default configuration:
+
+- **settings.xml** if working with external nexus repositories.
+- **standalone-settings.xml** if an external *policy* nexus repository is not available.
+- ***.conf** files containing environment variables. This is an alternative to use environment variables,
+ as these files will be sourced in before the PDP-D starts.
+- **features*.zip** to load any arbitrary feature not present in the image.
+- ***.pre.sh** scripts that will be executed before the PDP-D starts.
+- ***.post.sh** scripts that will be executed after the PDP-D starts.
+- **policy-keystore** to override the default PDP-D java keystore.
+- **policy-truststore** to override the default PDP-D java truststore.
+- **aaf-cadi.keyfile** to override the default AAF CADI Key generated by AAF.
+- ***.properties** to override or add any properties file for the PDP-D, this includes *controller*, *endpoint*,
+ *engine* or *system* configurations.
+- **logback*.xml** to override the default logging configuration.
+- ***.xml** to override other .xml configuration that may be used for example by an *application*.
+- ***.json** *json* configuration that may be used by an *application*.
+
+
+Running PDP-D with a single container
+=====================================
+
+Environment File
+~~~~~~~~~~~~~~~~
+
+First create an environment file (in this example *env.conf*) to configure the PDP-D.
+
+.. code-block:: bash
+
+ # SYSTEM software configuration
+
+ POLICY_HOME=/opt/app/policy
+ POLICY_LOGS=/var/log/onap/policy/pdpd
+ KEYSTORE_PASSWD=Pol1cy_0nap
+ TRUSTSTORE_PASSWD=Pol1cy_0nap
+
+ # Telemetry credentials
+
+ TELEMETRY_PORT=9696
+ TELEMETRY_HOST=0.0.0.0
+ TELEMETRY_USER=demo@people.osaaf.org
+ TELEMETRY_PASSWORD=demo123456!
+
+ # nexus repository
+
+ SNAPSHOT_REPOSITORY_ID=
+ SNAPSHOT_REPOSITORY_URL=
+ RELEASE_REPOSITORY_ID=
+ RELEASE_REPOSITORY_URL=
+ REPOSITORY_USERNAME=
+ REPOSITORY_PASSWORD=
+ REPOSITORY_OFFLINE=true
+
+ # Relational (SQL) DB access
+
+ SQL_HOST=
+ SQL_USER=
+ SQL_PASSWORD=
+
+ # AAF
+
+ AAF=false
+ AAF_NAMESPACE=org.onap.policy
+ AAF_HOST=aaf.api.simpledemo.onap.org
+
+ # PDP-D DMaaP configuration channel
+
+ PDPD_CONFIGURATION_TOPIC=PDPD-CONFIGURATION
+ PDPD_CONFIGURATION_API_KEY=
+ PDPD_CONFIGURATION_API_SECRET=
+ PDPD_CONFIGURATION_CONSUMER_GROUP=
+ PDPD_CONFIGURATION_CONSUMER_INSTANCE=
+ PDPD_CONFIGURATION_PARTITION_KEY=
+
+ # PAP-PDP configuration channel
+
+ POLICY_PDP_PAP_TOPIC=POLICY-PDP-PAP
+ POLICY_PDP_PAP_API_KEY=
+ POLICY_PDP_PAP_API_SECRET=
+
+ # DMaaP
+
+ DMAAP_SERVERS=localhost
+
+Note that *SQL_HOST*, and *REPOSITORY* are empty, so the PDP-D does not attempt
+to integrate with those components.
+
+Configuration
+~~~~~~~~~~~~~
+
+In order to avoid the noise in the logs that relate to dmaap configuration, a startup script (*noop.pre.sh*) is added
+to convert *dmaap* endpoints to *noop* in the host directory to be mounted.
+
+noop.pre.sh
+"""""""""""
+
+.. code-block:: bash
+
+ #!/bin/bash -x
+
+ sed -i "s/^dmaap/noop/g" $POLICY_HOME/config/*.properties
+
+
+active.post.sh
+""""""""""""""
+
+To put the controller directly in active mode at initialization, place an *active.post.sh* script under the
+mounted host directory:
+
+.. code-block:: bash
+
+ #!/bin/bash -x
+
+ bash -c "http --verify=no -a ${TELEMETRY_USER}:${TELEMETRY_PASSWORD} PUT https://localhost:9696/policy/pdp/engine/lifecycle/state/ACTIVE"
+
+Bring up the PDP-D
+~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+ docker run --rm -p 9696:9696 -v ${PWD}/config:/tmp/policy-install/config --env-file ${PWD}/env/env.conf -it --name PDPD -h pdpd nexus3.onap.org:10001/onap/policy-drools:1.6.3
+
+To run the container in detached mode, add the *-d* flag.
+
+Note that in this command, we are opening the *9696* telemetry API port to the outside world, the config directory
+(where the *noop.pre.sh* customization script resides) is mounted as /tmp/policy-install/config,
+and the customization environment variables (*env/env.conf*) are passed into the container.
+
+To open a shell into the PDP-D:
+
+.. code-block:: bash
+
+ docker exec -it pdp-d bash
+
+Once in the container, run tools such as *telemetry*, *db-migrator*, *policy* to look at the system state:
+
+To run the *telemetry shell* and other tools from the host:
+
+.. code-block:: bash
+
+ docker exec -it PDPD bash -c "/opt/app/policy/bin/telemetry"
+ docker exec -it PDPD bash -c "/opt/app/policy/bin/policy status"
+ docker exec -it PDPD bash -c "/opt/app/policy/bin/db-migrator -s ALL -o report"
+
+Controlled instantiation of the PDP-D
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sometimes a developer may want to start and stop the PDP-D manually:
+
+.. code-block:: bash
+
+ # start a bash
+
+ docker run --rm -p 9696:9696 -v ${PWD}/config:/tmp/policy-install/config --env-file ${PWD}/env/env.conf -it --name PDPD -h pdpd nexus3.onap.org:10001/onap/policy-drools:1.6.3 bash
+
+ # use this command to start policy applying host customizations from /tmp/policy-install/config
+
+ pdpd-entrypoint.sh vmboot
+
+ # or use this command to start policy without host customization
+
+ policy start
+
+ # at any time use the following command to stop the PDP-D
+
+ policy stop
+
+ # and this command to start the PDP-D back again
+
+ policy start
+
+Running PDP-D with nexus and mariadb
+====================================
+
+*docker-compose* can be used to test the PDP-D with other components. This is an example configuration
+that brings up *nexus*, *mariadb* and the PDP-D (*docker-compose-pdp.yml*)
+
+docker-compose-pdp.yml
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+ version: '3'
+ services:
+ mariadb:
+ image: mariadb:10.2.25
+ container_name: mariadb
+ hostname: mariadb
+ command: ['--lower-case-table-names=1', '--wait_timeout=28800']
+ env_file:
+ - ${PWD}/db/db.conf
+ volumes:
+ - ${PWD}/db:/docker-entrypoint-initdb.d
+ ports:
+ - "3306:3306"
+ nexus:
+ image: sonatype/nexus:2.14.8-01
+ container_name: nexus
+ hostname: nexus
+ ports:
+ - "8081:8081"
+ drools:
+ image: nexus3.onap.org:10001/onap/policy-drools:1.6.3
+ container_name: drools
+ depends_on:
+ - mariadb
+ - nexus
+ hostname: drools
+ ports:
+ - "9696:9696"
+ volumes:
+ - ${PWD}/config:/tmp/policy-install/config
+ env_file:
+ - ${PWD}/env/env.conf
+
+with *${PWD}/db/db.conf*:
+
+db.conf
+~~~~~~~
+
+.. code-block:: bash
+
+ MYSQL_ROOT_PASSWORD=secret
+ MYSQL_USER=policy_user
+ MYSQL_PASSWORD=policy_user
+
+and *${PWD}/db/db.sh*:
+
+db.sh
+~~~~~
+
+.. code-block:: bash
+
+ for db in support onap_sdk log migration operationshistory10 pooling policyadmin operationshistory
+ do
+ mysql -uroot -p"${MYSQL_ROOT_PASSWORD}" --execute "CREATE DATABASE IF NOT EXISTS ${db};"
+ mysql -uroot -p"${MYSQL_ROOT_PASSWORD}" --execute "GRANT ALL PRIVILEGES ON \`${db}\`.* TO '${MYSQL_USER}'@'%' ;"
+ done
+
+ mysql -uroot -p"${MYSQL_ROOT_PASSWORD}" --execute "FLUSH PRIVILEGES;"
+
+env.conf
+~~~~~~~~
+
+The environment file *env/env.conf* for *PDP-D* can be set up with appropriate variables to point to the *nexus* instance
+and the *mariadb* database:
+
+.. code-block:: bash
+
+ # SYSTEM software configuration
+
+ POLICY_HOME=/opt/app/policy
+ POLICY_LOGS=/var/log/onap/policy/pdpd
+ KEYSTORE_PASSWD=Pol1cy_0nap
+ TRUSTSTORE_PASSWD=Pol1cy_0nap
+
+ # Telemetry credentials
+
+ TELEMETRY_PORT=9696
+ TELEMETRY_HOST=0.0.0.0
+ TELEMETRY_USER=demo@people.osaaf.org
+ TELEMETRY_PASSWORD=demo123456!
+
+ # nexus repository
+
+ SNAPSHOT_REPOSITORY_ID=policy-nexus-snapshots
+ SNAPSHOT_REPOSITORY_URL=http://nexus:8081/nexus/content/repositories/snapshots/
+ RELEASE_REPOSITORY_ID=policy-nexus-releases
+ RELEASE_REPOSITORY_URL=http://nexus:8081/nexus/content/repositories/releases/
+ REPOSITORY_USERNAME=admin
+ REPOSITORY_PASSWORD=admin123
+ REPOSITORY_OFFLINE=false
+
+ MVN_SNAPSHOT_REPO_URL=https://nexus.onap.org/content/repositories/snapshots/
+ MVN_RELEASE_REPO_URL=https://nexus.onap.org/content/repositories/releases/
+
+ # Relational (SQL) DB access
+
+ SQL_HOST=mariadb
+ SQL_USER=policy_user
+ SQL_PASSWORD=policy_user
+
+ # AAF
+
+ AAF=false
+ AAF_NAMESPACE=org.onap.policy
+ AAF_HOST=aaf.api.simpledemo.onap.org
+
+ # PDP-D DMaaP configuration channel
+
+ PDPD_CONFIGURATION_TOPIC=PDPD-CONFIGURATION
+ PDPD_CONFIGURATION_API_KEY=
+ PDPD_CONFIGURATION_API_SECRET=
+ PDPD_CONFIGURATION_CONSUMER_GROUP=
+ PDPD_CONFIGURATION_CONSUMER_INSTANCE=
+ PDPD_CONFIGURATION_PARTITION_KEY=
+
+ # PAP-PDP configuration channel
+
+ POLICY_PDP_PAP_TOPIC=POLICY-PDP-PAP
+ POLICY_PDP_PAP_API_KEY=
+ POLICY_PDP_PAP_API_SECRET=
+
+ # DMaaP
+
+ DMAAP_SERVERS=localhost
+
+prepare.pre.sh
+~~~~~~~~~~~~~~
+
+A pre-start script *config/prepare.pres.sh"can be added the custom config directory
+to prepare the PDP-D to activate the distributed-locking feature (using the database)
+and to use "noop" topics instead of *dmaap* topics:
+
+.. code-block:: bash
+
+ #!/bin/bash
+
+ bash -c "/opt/app/policy/bin/features enable distributed-locking"
+ sed -i "s/^dmaap/noop/g" $POLICY_HOME/config/*.properties
+
+active.post.sh
+~~~~~~~~~~~~~~
+
+A post-start script *config/active.post.sh* can place PDP-D in *active* mode at initialization:
+
+ .. code-block:: bash
+
+ bash -c "http --verify=no -a ${TELEMETRY_USER}:${TELEMETRY_PASSWORD} PUT https://localhost:9696/policy/pdp/engine/lifecycle/state/ACTIVE"
+
+Bring up the PDP-D, nexus, and mariadb
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To bring up the containers:
+
+.. code-block:: bash
+
+ docker-compose -f docker-compose-pdpd.yaml up -d
+
+To take it down:
+
+.. code-block:: bash
+
+ docker-compose -f docker-compose-pdpd.yaml down -v
+
+Other examples
+~~~~~~~~~~~~~~
+
+The reader can also look at the `integration/csit repository <https://git.onap.org/integration/csit>`__.
+More specifically, these directories have examples of other PDP-D configurations:
+
+* `plans <https://git.onap.org/integration/csit/tree/plans/policy/drools-pdp>`__: startup scripts.
+* `scripts <https://git.onap.org/integration/csit/tree/scripts/policy/docker-compose-drools.yml>`__: docker-compose related files.
+* `plans <https://git.onap.org/integration/csit/tree/tests/policy/drools-pdp>`__: test plan.
+
+Configuring the PDP-D in an OOM Kubernetes installation
+=======================================================
+
+The `PDP-D OOM chart <https://git.onap.org/oom/tree/kubernetes/policy/charts/drools>`__ can be
+customized at the following locations:
+
+* `values.yaml <https://git.onap.org/oom/tree/kubernetes/policy/charts/drools/values.yaml>`__: custom values for your installation.
+* `configmaps <https://git.onap.org/oom/tree/kubernetes/policy/charts/drools/resources/configmaps>`__: place in this directory any configuration extensions or overrides to customize the PDP-D that does not contain sensitive information.
+* `secrets <https://git.onap.org/oom/tree/kubernetes/policy/charts/drools/resources/secrets>`__: place in this directory any configuration extensions or overrides to customize the PDP-D that does contain sensitive information.
+
+The same customization techniques described in the docker sections for PDP-D, fully apply here, by placing the corresponding
+files or scripts in these two directories.
+
+Additional information
+======================
+
+For additional information, please see the
+`Drools PDP Development and Testing (In Depth) <https://wiki.onap.org/display/DW/2020+Frankfurt+Tutorials>`__ page.