1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
2 .. http://creativecommons.org/licenses/by/4.0
17 .. container:: paragraph
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.
24 .. container:: paragraph
26 A full installation of APEX comes with the following layout.
28 .. container:: listingblock
30 .. container:: content
52 │ └───applications (13)
55 .. container:: colist arabic
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 |
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 |
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 |
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 |
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 +-----------------------------------+-----------------------------------+
113 Verify the APEXOnapPf Installation
114 ----------------------------------
116 .. container:: paragraph
118 When APEX is installed and all settings are realized, the
119 installation can be verified.
121 Verify Installation - run APEXOnapPf
122 ####################################
124 .. container:: paragraph
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.
134 .. container:: listingblock
136 .. container:: content
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)
150 .. container:: paragraph
152 To fully verify the installation, run the ApexOnapPf by providing the configuration files.
154 .. container:: paragraph
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.
158 .. container:: listingblock
160 .. container:: content
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)
169 .. container:: colist arabic
179 .. container:: paragraph
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)
185 .. container:: listingblock
187 .. container:: content
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
204 .. container:: paragraph
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.
208 .. container:: paragraph
210 Terminate APEX by simply using ``CTRL+C`` in the console.
212 Running APEXOnapPf in Docker
213 ----------------------------
215 .. container:: paragraph
217 Running APEX from the ONAP docker repository only requires 2
220 .. container:: olist arabic
222 1. Log into the ONAP docker repo
224 .. container:: listingblock
226 .. container:: content
230 docker login -u docker -p docker nexus3.onap.org:10003
233 2. Run the APEX docker image
235 .. container:: listingblock
237 .. container:: content
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"
243 .. container:: paragraph
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.
250 .. container:: paragraph
252 Alternatively, one can use the Dockerfile defined in the Docker
253 package to build an image.
255 .. container:: listingblock
261 .. container:: content
267 # Docker file to build an image that runs APEX on Java 11 or better in alpine
269 FROM onap/policy-jre-alpine:2.0.1
271 LABEL maintainer="Policy Team"
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
277 RUN apk add --no-cache \
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 \
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/*
298 ENV PATH $POLICY_HOME/bin:$PATH
299 WORKDIR /home/apexuser
302 APEXOnapPf Configuration File Explained
303 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
305 .. container:: paragraph
307 The ApexOnapPf is initialized using a configuration file:
313 Format of the configuration file (OnapPfConfig.json) explained
314 --------------------------------------------------------------
316 .. container:: paragraph
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:
322 .. container:: listingblock
324 .. container:: content
329 "name":"ApexStarterParameterGroup",
330 "restServerParameters": { (1)
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)
344 "topicParameterGroup": {
345 "topicSources" : [{ (7)
346 "topic" : "POLICY-PDP-PAP", (8)
347 "servers" : [ "message-router" ], (9)
348 "topicCommInfrastructure" : "dmaap" (10)
350 "topicSinks" : [{ (11)
351 "topic" : "POLICY-PDP-PAP", (12)
352 "servers" : [ "message-router" ], (13)
353 "topicCommInfrastructure" : "dmaap" (14)
358 .. container:: colist arabic
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 |
389 +-----------------------------------+-------------------------------------------------+
390 | **9** | List of servers for the source |
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 |
404 +-----------------------------------+-------------------------------------------------+
405 | **14** | The sink topic infrastructure. |
406 | | For e.g. dmaap, noop, ueb |
407 +-----------------------------------+-------------------------------------------------+