1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
|
.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. http://creativecommons.org/licenses/by/4.0
APEX-OnapPf Guide
*****************
.. contents::
:depth: 3
Installation
^^^^^^^^^^^^
Build and Install
-------------------
.. container:: paragraph
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.
Installation Layout
-------------------
.. container:: paragraph
A full installation of APEX comes with the following layout.
.. container:: listingblock
.. container:: content
::
$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)
.. container:: colist arabic
+-----------------------------------+-----------------------------------+
| **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
----------------------------------
.. container:: paragraph
When APEX is installed and all settings are realized, the
installation can be verified.
Verify Installation - run APEXOnapPf
####################################
.. container:: paragraph
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.
.. container:: listingblock
.. container:: content
.. code::
:number-lines:
Apex [main] INFO o.o.p.a.s.onappf.ApexStarterMain - In ApexStarter with parameters []
Apex [main] ERROR o.o.p.a.s.onappf.ApexStarterMain - start of services-onappf failed
org.onap.policy.apex.services.onappf.exception.ApexStarterException: apex starter configuration file was not specified as an argument
at org.onap.policy.apex.services.onappf.ApexStarterCommandLineArguments.validateReadableFile(ApexStarterCommandLineArguments.java:278)
at org.onap.policy.apex.services.onappf.ApexStarterCommandLineArguments.validate(ApexStarterCommandLineArguments.java:165)
at org.onap.policy.apex.services.onappf.ApexStarterMain.<init>(ApexStarterMain.java:66)
at org.onap.policy.apex.services.onappf.ApexStarterMain.main(ApexStarterMain.java:165)
.. container:: paragraph
To fully verify the installation, run the ApexOnapPf by providing the configuration files.
.. container:: paragraph
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.
.. container:: listingblock
.. container:: content
.. code::
:number-lines:
# $APEX_HOME/bin/apexOnapPf.sh -c $APEX_HOME/etc/onappf/config/OnapPfConfig.json -p $APEX_HOME/etc/onappf/config/topic.properties (1)
# $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)
>%APEX_HOME%\bin\apexOnapPf.bat -c %APEX_HOME%\etc\onappf\config\OnapPfConfig.json -p %APEX_HOME%\etc\onappf\config\topic.properties (3)
.. container:: colist arabic
+-------+---------+
| **1** | UNIX |
+-------+---------+
| **2** | Cygwin |
+-------+---------+
| **3** | Windows |
+-------+---------+
.. container:: paragraph
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)
.. container:: listingblock
.. container:: content
.. code::
:number-lines:
In ApexStarter with parameters [-c, C:/apex/etc/onappf/config/OnapPfConfig.json, -p, C:/apex/etc/onappf/config/topic.properties] . . .
Apex [main] INFO o.o.p.c.u.services.ServiceManager - service manager starting set alive
Apex [main] INFO o.o.p.c.u.services.ServiceManager - service manager starting register pdp status context object
Apex [main] INFO o.o.p.c.u.services.ServiceManager - service manager starting topic sinks
Apex [main] INFO o.o.p.c.u.services.ServiceManager - service manager starting Pdp Status publisher
Apex [main] INFO o.o.p.c.u.services.ServiceManager - service manager starting Register pdp update listener
Apex [main] INFO o.o.p.c.u.services.ServiceManager - service manager starting Register pdp state change request dispatcher
Apex [main] INFO o.o.p.c.u.services.ServiceManager - service manager starting Message Dispatcher . . .
Apex [main] INFO o.o.p.c.u.services.ServiceManager - service manager starting Rest Server . . .
Apex [main] INFO o.o.p.c.u.services.ServiceManager - service manager started
Apex [main] INFO o.o.p.a.s.onappf.ApexStarterMain - Started ApexStarter service
.. container:: paragraph
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.
.. container:: paragraph
Terminate APEX by simply using ``CTRL+C`` in the console.
Running APEXOnapPf in Docker
----------------------------
.. container:: paragraph
Running APEX from the ONAP docker repository only requires 2
commands:
.. container:: olist arabic
1. Log into the ONAP docker repo
.. container:: listingblock
.. container:: content
::
docker login -u docker -p docker nexus3.onap.org:10003
2. Run the APEX docker image
.. container:: listingblock
.. container:: content
::
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"
.. container:: paragraph
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
####################
.. container:: paragraph
Alternatively, one can use the Dockerfile defined in the Docker
package to build an image.
.. container:: listingblock
.. container:: title
APEX Dockerfile
.. container:: content
.. code::
:number-lines:
#
# Docker file to build an image that runs APEX on Java 8 in alpine
#
FROM onap/policy-base-alpine:1.4.0
LABEL maintainer="Policy Team"
ARG BUILD_VERSION=${BUILD_VERSION}
ARG POLICY_LOGS=/var/log/onap/policy/apex-pdp
ENV BUILD_VERSION ${BUILD_VERSION}
ENV POLICY_HOME=/opt/app/policy
ENV POLICY_APEX_PDP_HOME=${POLICY_HOME}/apex-pdp
ENV POLICY_LOGS=${POLICY_LOGS}
RUN apk add --no-cache \
vim \
iproute2 \
iputils
# Create apex user and group
RUN addgroup -S apexuser && adduser -S apexuser -G apexuser
# Add Apex-specific directories and set ownership as the Apex admin user
RUN mkdir -p ${POLICY_APEX_PDP_HOME} \
&& mkdir -p ${POLICY_LOGS} \
&& chown -R apexuser:apexuser ${POLICY_LOGS}
# Unpack the tarball
RUN mkdir /packages
COPY apex-pdp-package-full.tar.gz /packages
RUN tar xvfz /packages/apex-pdp-package-full.tar.gz --directory ${POLICY_APEX_PDP_HOME} \
&& rm /packages/apex-pdp-package-full.tar.gz
# Ensure everything has the correct permissions
RUN find /opt/app -type d -perm 755 \
&& find /opt/app -type f -perm 644 \
&& chmod a+x ${POLICY_APEX_PDP_HOME}/bin/*
# Copy examples to Apex user area
RUN cp -pr ${POLICY_APEX_PDP_HOME}/examples /home/apexuser \
&& chown -R apexuser:apexuser /home/apexuser/*
USER apexuser
ENV PATH ${POLICY_APEX_PDP_HOME}/bin:$PATH
WORKDIR /home/apexuser
APEXOnapPf Configuration Files Explained
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. container:: paragraph
The ApexOnapPf is initialized using two files:
.. container:: ulist
- OnapPfConfig.json
- topic.properties
Format of the configuration file (OnapPfConfig.json) explained
--------------------------------------------------------------
.. container:: paragraph
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:
.. container:: listingblock
.. container:: content
.. code::
{
"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)
}
}
.. container:: colist arabic
+-----------------------------------+-----------------------------------+
| **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
----------------------------------------------------------
.. container:: paragraph
The dmaap topics to be used for sending or receiving messages is specified in the topic.properties file. A sample can be found below:
.. container:: listingblock
.. container:: content
.. code::
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)
.. container:: colist arabic
+-----------------------------------+-----------------------------------+
| **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. |
+-----------------------------------+-----------------------------------+
|
