APEX-OnapPf Guide

Installation

Build and Install

Refer Apex User Manual to find details on the build and installation of the APEX component. Information on the requirements and system configuration can also be found here.

Installation Layout

A full installation of APEX comes with the following layout.
$APEX_HOME
    ├───bin             (1)
    ├───etc             (2)
    │   ├───editor
    │   ├───hazelcast
    │   ├───infinispan
    │   └───META-INF
    │   ├───onappf
    |       └───config      (3)
    │   └───ssl             (4)
    ├───examples            (5)
    │   ├───config          (6)
    │   ├───docker          (7)
    │   ├───events          (8)
    │   ├───html            (9)
    │   ├───models          (10)
    │   └───scripts         (11)
    ├───lib             (12)
    │   └───applications        (13)
    └───war             (14)
1 binaries, mainly scripts (bash and bat) to start the APEX engine and applications
2 configuration files, such as logback (logging) and third party library configurations
3 configuration files for APEXOnapPf, such as OnapPfConfig.json (initial configuration for APEXOnapPf) and topic.properties (dmaap topics)
4 ssl related files such as policy-keystore and policy-truststore
5 example policy models to get started
6 configurations for the examples (with sub directories for individual examples)
7 Docker files and additional Docker instructions for the examples
8 example events for the examples (with sub directories for individual examples)
9 HTML files for some examples, e.g. the Decisionmaker example
10 the policy models, generated for each example (with sub directories for individual examples)
11 additional scripts for the examples (with sub directories for individual examples)
12 the library folder with all Java JAR files
13 applications, also known as jar with dependencies (or fat jars), individually deployable
14 WAR files for web applications

Verify the APEXOnapPf Installation

When APEX is installed and all settings are realized, the installation can be verified.

Verify Installation - run APEXOnapPf

A simple verification of an APEX installation can be done by simply starting the APEXOnapPf without any configuration. On Unix (or Cygwin) start the engine using $APEX_HOME/bin/apexOnapPf.sh. On Windows start the engine using %APEX_HOME%\bin\apexOnapPf.bat. The engine will fail to fully start. However, if the output looks similar to the following line, the APEX installation is realized.
1 Apex [main] INFO o.o.p.a.s.onappf.ApexStarterMain - In ApexStarter with parameters []
2 Apex [main] ERROR o.o.p.a.s.onappf.ApexStarterMain - start of services-onappf failed
3 org.onap.policy.apex.services.onappf.exception.ApexStarterException: apex starter configuration file was not specified as an argument
4 at org.onap.policy.apex.services.onappf.ApexStarterCommandLineArguments.validateReadableFile(ApexStarterCommandLineArguments.java:278)
5         at org.onap.policy.apex.services.onappf.ApexStarterCommandLineArguments.validate(ApexStarterCommandLineArguments.java:165)
6         at org.onap.policy.apex.services.onappf.ApexStarterMain.<init>(ApexStarterMain.java:66)
7         at org.onap.policy.apex.services.onappf.ApexStarterMain.main(ApexStarterMain.java:165)
To fully verify the installation, run the ApexOnapPf by providing the configuration files.
OnapPfConfig.json is the file which contains the initial configuration to startup the ApexStarter service. The dmaap topics to be used for sending or receiving messages is specified in the topic.properties file. Provide these two files as arguments while running the ApexOnapPf.
1 # $APEX_HOME/bin/apexOnapPf.sh -c $APEX_HOME/etc/onappf/config/OnapPfConfig.json -p $APEX_HOME/etc/onappf/config/topic.properties (1)
2 # $APEX_HOME/bin/apexOnapPf.sh -c C:/apex/apex-full-2.0.0-SNAPSHOT/etc/onappf/config/OnapPfConfig.json -p C:/apex/apex-full-2.0.0-SNAPSHOT/etc/onappf/config/topic.properties (2)
3 >%APEX_HOME%\bin\apexOnapPf.bat -c %APEX_HOME%\etc\onappf\config\OnapPfConfig.json -p %APEX_HOME%\etc\onappf\config\topic.properties (3)
1 UNIX
2 Cygwin
3 Windows
The APEXOnapPf should start successfully. Assuming the logging levels are not changed (default level is info), the output should look similar to this (last few lines)
 1 In ApexStarter with parameters [-c, C:/apex/etc/onappf/config/OnapPfConfig.json, -p, C:/apex/etc/onappf/config/topic.properties] . . .
 2 Apex [main] INFO o.o.p.c.u.services.ServiceManager - service manager starting set alive
 3 Apex [main] INFO o.o.p.c.u.services.ServiceManager - service manager starting register pdp status context object
 4 Apex [main] INFO o.o.p.c.u.services.ServiceManager - service manager starting topic sinks
 5 Apex [main] INFO o.o.p.c.u.services.ServiceManager - service manager starting Pdp Status publisher
 6 Apex [main] INFO o.o.p.c.u.services.ServiceManager - service manager starting Register pdp update listener
 7 Apex [main] INFO o.o.p.c.u.services.ServiceManager - service manager starting Register pdp state change request dispatcher
 8 Apex [main] INFO o.o.p.c.u.services.ServiceManager - service manager starting Message Dispatcher . . .
 9 Apex [main] INFO o.o.p.c.u.services.ServiceManager - service manager starting Rest Server . . .
10 Apex [main] INFO o.o.p.c.u.services.ServiceManager - service manager started
11 Apex [main] INFO o.o.p.a.s.onappf.ApexStarterMain - Started ApexStarter service
The ApexOnapPf service is now running, sending heartbeat messages to dmaap (which will be received by PAP) and listening for messages from PAP on the dmaap topic specified. Based on instructions from PAP, the ApexOnapPf will deploy or undeploy policies on the ApexEngine.
Terminate APEX by simply using CTRL+C in the console.

Running APEXOnapPf in Docker

Running APEX from the ONAP docker repository only requires 2 commands:
  1. Log into the ONAP docker repo
docker login -u docker -p docker nexus3.onap.org:10003
  1. Run the APEX docker image
docker run -p 6969:6969 -p 23324:23324 -it --rm  nexus3.onap.org:10001/onap/policy-apex-pdp:2.1-SNAPSHOT-latest /bin/bash -c "/opt/app/policy/apex-pdp/bin/apexOnapPf.sh -c /opt/app/policy/apex-pdp/etc/onappf/config/OnapPfConfig.json -p /opt/app/policy/apex-pdp/etc/onappf/config/topic.properties"
To run the ApexOnapPf, the startup script apexOnapPf.sh along with the required configuration files are specified. Also, the ports 6969 (healthcheck) and 23324 (deployment port for the ApexEngine) are exposed.

Build a Docker Image

Alternatively, one can use the Dockerfile defined in the Docker package to build an image.
APEX Dockerfile
 1 #
 2 # Docker file to build an image that runs APEX on Java 8 in alpine
 3 #
 4 FROM onap/policy-base-alpine:1.4.0
 5 
 6 LABEL maintainer="Policy Team"
 7 
 8 ARG BUILD_VERSION=${BUILD_VERSION}
 9 ARG POLICY_LOGS=/var/log/onap/policy/apex-pdp
10 
11 ENV BUILD_VERSION ${BUILD_VERSION}
12 ENV POLICY_HOME=/opt/app/policy
13 ENV POLICY_APEX_PDP_HOME=${POLICY_HOME}/apex-pdp
14 ENV POLICY_LOGS=${POLICY_LOGS}
15 
16 RUN apk add --no-cache \
17     vim \
18     iproute2 \
19     iputils
20 
21 # Create apex user and group
22 RUN addgroup -S apexuser && adduser -S apexuser -G apexuser
23 
24 
25 # Add Apex-specific directories and set ownership as the Apex admin user
26 RUN mkdir -p ${POLICY_APEX_PDP_HOME} \
27     && mkdir -p ${POLICY_LOGS} \
28     && chown -R apexuser:apexuser ${POLICY_LOGS}
29 
30 # Unpack the tarball
31 RUN mkdir /packages
32 COPY apex-pdp-package-full.tar.gz /packages
33 RUN tar xvfz /packages/apex-pdp-package-full.tar.gz --directory ${POLICY_APEX_PDP_HOME} \
34     && rm /packages/apex-pdp-package-full.tar.gz
35 
36 # Ensure everything has the correct permissions
37 RUN find /opt/app -type d -perm 755 \
38     && find /opt/app -type f -perm 644 \
39     && chmod a+x ${POLICY_APEX_PDP_HOME}/bin/*
40 
41 # Copy examples to Apex user area
42 RUN cp -pr ${POLICY_APEX_PDP_HOME}/examples /home/apexuser \
43     && chown -R apexuser:apexuser /home/apexuser/*
44 
45 USER apexuser
46 ENV PATH ${POLICY_APEX_PDP_HOME}/bin:$PATH
47 WORKDIR /home/apexuser

APEXOnapPf Configuration Files Explained

The ApexOnapPf is initialized using two files:
  • OnapPfConfig.json
  • topic.properties

Format of the configuration file (OnapPfConfig.json) explained

The configuration file is a JSON file containing the initial values for configuring the rest server for healthcheck and the pdp itself. A sample can be found below:
{
    "name":"ApexStarterParameterGroup",
    "restServerParameters": {  (1)
        "host": "0.0.0.0",
        "port": 6969,
        "userName": "...",
        "password": "...",
        "https": true  (2)
    },
    "pdpStatusParameters":{
        "timeIntervalMs": 120000,  (3)
        "pdpType":"apex",  (4)
        "description":"Pdp Heartbeat",
        "supportedPolicyTypes":[{"name":"onap.policies.controlloop.operational.Apex","version":"1.0.0"}]  (5)
    }
}
1 parameters for setting up the rest server such as host, port userName and password.
2 https flag if enabled will enable https support by the rest server.
3 time interval in which PDP-A has to send heartbeats to PAP. Specified in milliseconds.
4 Type of the pdp.
5 List of policy types supported by the PDP.

Format of the properties file (topic.properties) explained

The dmaap topics to be used for sending or receiving messages is specified in the topic.properties file. A sample can be found below:
dmaap.source.topics=POLICY-PDP-PAP  (1)
dmaap.sink.topics=POLICY-PDP-PAP  (2)
dmaap.source.topics.POLICY-PDP-PAP.servers= message-router  (3)
dmaap.sink.topics.POLICY-PDP-PAP.servers= message-router  (4)
1 DMaap topic name of the source to which PDP-A listens to for messages from PAP.
2 DMaap topic name of the sink to which PDP sends messages to.
3 DMaap source server.
4 DMaap sink server.