docs/apex/APEX-OnapPf-Guide.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3
   4
   5 APEX OnapPf Guide
   6 *****************
   7
   8 .. contents::
   9     :depth: 3
  10
  11 Installation
  12 ^^^^^^^^^^^^
  13
  14 Build and Install
  15 -----------------
  16
  17    .. container:: paragraph
  18
  19       Refer to
  20       :ref:`Apex User Manual <apex-user-manual-label>` to find details on the build and installation of the APEX component. Information on the requirements and system configuration can also be found here.
  21
  22 Installation Layout
  23 -------------------
  24
  25    .. container:: paragraph
  26
  27       A full installation of APEX comes with the following layout.
  28
  29    .. container:: listingblock
  30
  31       .. container:: content
  32
  33          ::
  34
  35             $APEX_HOME
  36                 ├───bin             (1)
  37                 ├───etc             (2)
  38                 │   ├───editor
  39                 │   ├───hazelcast
  40                 │   ├───infinispan
  41                 │   └───META-INF
  42                 │   ├───onappf
  43                 |       └───config      (3)
  44                 │   └───ssl             (4)
  45                 ├───examples            (5)
  46                 │   ├───config          (6)
  47                 │   ├───docker          (7)
  48                 │   ├───events          (8)
  49                 │   ├───html            (9)
  50                 │   ├───models          (10)
  51                 │   └───scripts         (11)
  52                 ├───lib             (12)
  53                 │   └───applications        (13)
  54                 └───war             (14)
  55
  56    .. container:: colist arabic
  57
  58       +-----------------------------------+-----------------------------------+
  59       | **1**                             | binaries, mainly scripts (bash    |
  60       |                                   | and bat) to start the APEX engine |
  61       |                                   | and applications                  |
  62       +-----------------------------------+-----------------------------------+
  63       | **2**                             | configuration files, such as      |
  64       |                                   | logback (logging) and third party |
  65       |                                   | library configurations            |
  66       +-----------------------------------+-----------------------------------+
  67       | **3**                             | configuration file for            |
  68       |                                   | APEXOnapPf, such as               |
  69       |                                   | OnapPfConfig.json (initial        |
  70       |                                   | configuration for APEXOnapPf)     |
  71       +-----------------------------------+-----------------------------------+
  72       | **4**                             | ssl related files such as         |
  73       |                                   | policy-keystore and               |
  74       |                                   | policy-truststore                 |
  75       +-----------------------------------+-----------------------------------+
  76       | **5**                             | example policy models to get      |
  77       |                                   | started                           |
  78       +-----------------------------------+-----------------------------------+
  79       | **6**                             | configurations for the examples   |
  80       |                                   | (with sub directories for         |
  81       |                                   | individual examples)              |
  82       +-----------------------------------+-----------------------------------+
  83       | **7**                             | Docker files and additional       |
  84       |                                   | Docker instructions for the       |
  85       |                                   | examples                          |
  86       +-----------------------------------+-----------------------------------+
  87       | **8**                             | example events for the examples   |
  88       |                                   | (with sub directories for         |
  89       |                                   | individual examples)              |
  90       +-----------------------------------+-----------------------------------+
  91       | **9**                             | HTML files for some examples,     |
  92       |                                   | e.g. the Decisionmaker example    |
  93       +-----------------------------------+-----------------------------------+
  94       | **10**                            | the policy models, generated for  |
  95       |                                   | each example (with sub            |
  96       |                                   | directories for individual        |
  97       |                                   | examples)                         |
  98       +-----------------------------------+-----------------------------------+
  99       | **11**                            | additional scripts for the        |
 100       |                                   | examples (with sub directories    |
 101       |                                   | for individual examples)          |
 102       +-----------------------------------+-----------------------------------+
 103       | **12**                            | the library folder with all Java  |
 104       |                                   | JAR files                         |
 105       +-----------------------------------+-----------------------------------+
 106       | **13**                            | applications, also known as jar   |
 107       |                                   | with dependencies (or fat jars),  |
 108       |                                   | individually deployable           |
 109       +-----------------------------------+-----------------------------------+
 110       | **14**                            | WAR files for web applications    |
 111       +-----------------------------------+-----------------------------------+
 112
 113
 114 Verify the APEXOnapPf Installation
 115 ----------------------------------
 116
 117    .. container:: paragraph
 118
 119       When APEX is installed and all settings are realized, the
 120       installation can be verified.
 121
 122 Verify Installation - run APEXOnapPf
 123 ####################################
 124
 125       .. container:: paragraph
 126
 127          A simple verification of an APEX installation can be done by
 128          simply starting the APEXOnapPf without any configuration. On
 129          Unix (or Cygwin) start the engine using
 130          ``$APEX_HOME/bin/apexOnapPf.sh``. On Windows start the engine
 131          using ``%APEX_HOME%\bin\apexOnapPf.bat``. The engine will fail
 132          to fully start. However, if the output looks similar to the
 133          following line, the APEX installation is realized.
 134
 135       .. container:: listingblock
 136
 137          .. container:: content
 138
 139             .. code::
 140                :number-lines:
 141
 142                Apex [main] INFO o.o.p.a.s.onappf.ApexStarterMain - In ApexStarter with parameters []
 143                Apex [main] ERROR o.o.p.a.s.onappf.ApexStarterMain - start of services-onappf failed
 144                org.onap.policy.apex.services.onappf.exception.ApexStarterException: apex starter configuration file was not specified as an argument
 145                at org.onap.policy.apex.services.onappf.ApexStarterCommandLineArguments.validateReadableFile(ApexStarterCommandLineArguments.java:278)
 146                        at org.onap.policy.apex.services.onappf.ApexStarterCommandLineArguments.validate(ApexStarterCommandLineArguments.java:165)
 147                        at org.onap.policy.apex.services.onappf.ApexStarterMain.<init>(ApexStarterMain.java:66)
 148                        at org.onap.policy.apex.services.onappf.ApexStarterMain.main(ApexStarterMain.java:165)
 149
 150
 151          .. container:: paragraph
 152
 153             To fully verify the installation, run the ApexOnapPf by providing the configuration files.
 154
 155          .. container:: paragraph
 156
 157             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 also specified in the this file. Provide this file as argument while running the ApexOnapPf.
 158
 159          .. container:: listingblock
 160
 161             .. container:: content
 162
 163                .. code::
 164                       :number-lines:
 165
 166                       # $APEX_HOME/bin/apexOnapPf.sh -c $APEX_HOME/etc/onappf/config/OnapPfConfig.json (1)
 167                       # $APEX_HOME/bin/apexOnapPf.sh -c C:/apex/apex-full-2.0.0-SNAPSHOT/etc/onappf/config/OnapPfConfig.json (2)
 168                       >%APEX_HOME%\bin\apexOnapPf.bat -c %APEX_HOME%\etc\onappf\config\OnapPfConfig.json (3)
 169
 170          .. container:: colist arabic
 171
 172             +-------+---------+
 173             | **1** | UNIX    |
 174             +-------+---------+
 175             | **2** | Cygwin  |
 176             +-------+---------+
 177             | **3** | Windows |
 178             +-------+---------+
 179
 180          .. container:: paragraph
 181
 182             The APEXOnapPf should start successfully. Assuming the logging levels are
 183             not changed (default level is ``info``), the output should look
 184             similar to this (last few lines)
 185
 186          .. container:: listingblock
 187
 188             .. container:: content
 189
 190                .. code::
 191                   :number-lines:
 192
 193                   In ApexStarter with parameters [-c, C:/apex/etc/onappf/config/OnapPfConfig.json] . . .
 194                   Apex [main] INFO o.o.p.c.u.services.ServiceManager - service manager starting set alive
 195                   Apex [main] INFO o.o.p.c.u.services.ServiceManager - service manager starting register pdp status context object
 196                   Apex [main] INFO o.o.p.c.u.services.ServiceManager - service manager starting topic sinks
 197                   Apex [main] INFO o.o.p.c.u.services.ServiceManager - service manager starting Pdp Status publisher
 198                   Apex [main] INFO o.o.p.c.u.services.ServiceManager - service manager starting Register pdp update listener
 199                   Apex [main] INFO o.o.p.c.u.services.ServiceManager - service manager starting Register pdp state change request dispatcher
 200                   Apex [main] INFO o.o.p.c.u.services.ServiceManager - service manager starting Message Dispatcher . . .
 201                   Apex [main] INFO o.o.p.c.u.services.ServiceManager - service manager starting Rest Server . . .
 202                   Apex [main] INFO o.o.p.c.u.services.ServiceManager - service manager started
 203                   Apex [main] INFO o.o.p.a.s.onappf.ApexStarterMain - Started ApexStarter service
 204
 205          .. container:: paragraph
 206
 207             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.
 208
 209          .. container:: paragraph
 210
 211             Terminate APEX by simply using ``CTRL+C`` in the console.
 212
 213 Running APEXOnapPf in Docker
 214 ----------------------------
 215
 216       .. container:: paragraph
 217
 218          Running APEX from the ONAP docker repository only requires 2
 219          commands:
 220
 221       .. container:: olist arabic
 222
 223          1. Log into the ONAP docker repo
 224
 225          .. container:: listingblock
 226
 227             .. container:: content
 228
 229                ::
 230
 231                   docker login -u docker -p docker nexus3.onap.org:10003
 232
 233
 234          2. Run the APEX docker image
 235
 236          .. container:: listingblock
 237
 238             .. container:: content
 239
 240                ::
 241
 242                   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"
 243
 244       .. container:: paragraph
 245
 246          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.
 247
 248 Build a Docker Image
 249 ####################
 250
 251       .. container:: paragraph
 252
 253          Alternatively, one can use the Dockerfile defined in the Docker
 254          package to build an image.
 255
 256       .. container:: listingblock
 257
 258          .. container:: title
 259
 260             APEX Dockerfile
 261
 262          .. container:: content
 263
 264             .. code::
 265                :number-lines:
 266
 267                #
 268                # Docker file to build an image that runs APEX on Java 11 or better in alpine
 269                #
 270                FROM onap/policy-jre-alpine:2.0.1
 271
 272                LABEL maintainer="Policy Team"
 273
 274                ARG POLICY_LOGS=/var/log/onap/policy/apex-pdp
 275                ENV POLICY_HOME=/opt/app/policy/apex-pdp
 276                ENV POLICY_LOGS=$POLICY_LOGS
 277
 278                RUN apk add --no-cache \
 279                        vim \
 280                        iproute2 \
 281                        iputils \
 282                    && addgroup -S apexuser && adduser -S apexuser -G apexuser \
 283                    && mkdir -p $POLICY_HOME \
 284                    && mkdir -p $POLICY_LOGS \
 285                    && chown -R apexuser:apexuser $POLICY_LOGS \
 286                    && mkdir /packages
 287
 288                COPY /maven/apex-pdp-package-full.tar.gz /packages
 289                RUN tar xvfz /packages/apex-pdp-package-full.tar.gz --directory $POLICY_HOME \
 290                    && rm /packages/apex-pdp-package-full.tar.gz \
 291                    && find /opt/app -type d -perm 755 \
 292                    && find /opt/app -type f -perm 644 \
 293                    && chmod 755 $POLICY_HOME/bin/* \
 294                    && cp -pr $POLICY_HOME/examples /home/apexuser \
 295                    && chown -R apexuser:apexuser /home/apexuser/* $POLICY_HOME \
 296                    && chmod 644 $POLICY_HOME/etc/*
 297
 298                USER apexuser
 299                ENV PATH $POLICY_HOME/bin:$PATH
 300                WORKDIR /home/apexuser
 301
 302
 303 APEXOnapPf Configuration File Explained
 304 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 305
 306          .. container:: paragraph
 307
 308             The ApexOnapPf is initialized using a configuration file:
 309
 310          .. container:: ulist
 311
 312             -  OnapPfConfig.json
 313
 314 Format of the configuration file (OnapPfConfig.json) explained
 315 --------------------------------------------------------------
 316
 317          .. container:: paragraph
 318
 319             The configuration file is a JSON file containing the initial values for configuring the rest server for healthcheck and the pdp itself.
 320             The topic infrastructure and the topics to be used for sending or receiving messages is specified in this configuration file.
 321             A sample can be found below:
 322
 323          .. container:: listingblock
 324
 325             .. container:: content
 326
 327                .. code::
 328
 329                   {
 330                       "name":"ApexStarterParameterGroup",
 331                       "restServerParameters": {  (1)
 332                           "host": "0.0.0.0",
 333                           "port": 6969,
 334                           "userName": "...",
 335                           "password": "...",
 336                           "https": true  (2)
 337                       },
 338                       "pdpStatusParameters":{
 339                           "timeIntervalMs": 120000,  (3)
 340                           "pdpType":"apex",  (4)
 341                           "pdpGroup":"defaultGroup",  (5)
 342                           "description":"Pdp Heartbeat",
 343                           "supportedPolicyTypes":[{"name":"onap.policies.controlloop.operational.Apex","version":"1.0.0"}]  (6)
 344                       },
 345                       "topicParameterGroup": {
 346                           "topicSources" : [{  (7)
 347                               "topic" : "POLICY-PDP-PAP",  (8)
 348                               "servers" : [ "message-router" ],  (9)
 349                               "topicCommInfrastructure" : "dmaap"  (10)
 350                           }],
 351                           "topicSinks" : [{  (11)
 352                               "topic" : "POLICY-PDP-PAP",  (12)
 353                               "servers" : [ "message-router" ],  (13)
 354                               "topicCommInfrastructure" : "dmaap"  (14)
 355                           }]
 356                       }
 357                   }
 358
 359          .. container:: colist arabic
 360
 361             +-----------------------------------+-------------------------------------------------+
 362             | **1**                             | parameters for setting up the                   |
 363             |                                   | rest server such as host, port                  |
 364             |                                   | userName and password.                          |
 365             +-----------------------------------+-------------------------------------------------+
 366             | **2**                             | https flag if enabled will enable               |
 367             |                                   | https support by the rest server.               |
 368             +-----------------------------------+-------------------------------------------------+
 369             | **3**                             | time interval in which PDP-A                    |
 370             |                                   | has to send heartbeats to PAP.                  |
 371             |                                   | Specified in milliseconds.                      |
 372             +-----------------------------------+-------------------------------------------------+
 373             | **4**                             | Type of the pdp.                                |
 374             +-----------------------------------+-------------------------------------------------+
 375             | **5**                             | The group to which the pdp belong to.           |
 376             +-----------------------------------+-------------------------------------------------+
 377             | **6**                             | List of policy types supported by               |
 378             |                                   | the PDP. A trailing “.*” can be used to         |
 379             |                                   | specify multiple policy types; for example,     |
 380             |                                   | “onap.policies.controlloop.operational.apex.*”  |
 381             |                                   | would match any policy type beginning with      |
 382             |                                   | “onap.policies.controlloop.operational.apex.”   |
 383             +-----------------------------------+-------------------------------------------------+
 384             | **7**                             | List of topics' details from                    |
 385             |                                   | which messages are received.                    |
 386             +-----------------------------------+-------------------------------------------------+
 387             | **8**                             | Topic name of the source to which               |
 388             |                                   | PDP-A listens to for messages                   |
 389             |                                   | from PAP.                                       |
 390             +-----------------------------------+-------------------------------------------------+
 391             | **9**                             | List of servers for the source                  |
 392             |                                   | topic.                                          |
 393             +-----------------------------------+-------------------------------------------------+
 394             | **10**                            | The source topic infrastructure.                |
 395             |                                   | For e.g. dmaap, noop, ueb                       |
 396             +-----------------------------------+-------------------------------------------------+
 397             | **11**                            | List of topics' details to which                |
 398             |                                   | messages are sent.                              |
 399             +-----------------------------------+-------------------------------------------------+
 400             | **12**                            | Topic name of the sink to which                 |
 401             |                                   | PDP-A sends messages.                           |
 402             +-----------------------------------+-------------------------------------------------+
 403             | **13**                            | List of servers for the sink                    |
 404             |                                   | topic.                                          |
 405             +-----------------------------------+-------------------------------------------------+
 406             | **14**                            | The sink topic infrastructure.                  |
 407             |                                   | For e.g. dmaap, noop, ueb                       |
 408             +-----------------------------------+-------------------------------------------------+