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