Merge "drools documentation redo"

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.