Gitiles
Code Review Sign In
gerrit.nordix.org / onap / policy / parent / 5cce8d7d5fa269cb43981dadbed96a4821f3366a / . / docs / apex / APEX-OnapPf-Guide.rst
blob: 0fe38025d897b29f79e273981ec4e49c384ec1cd [file] [log] [blame]
ramverma3b71c972019-07-10 11:25:37 +0000[diff] [blame]1.. This work is licensed under a Creative Commons Attribution 4.0 International License.
2.. http://creativecommons.org/licenses/by/4.0
3
4
ramverma7fd4a6e2019-07-11 14:38:25 +0000[diff] [blame]5APEX OnapPf Guide
ramverma3b71c972019-07-10 11:25:37 +0000[diff] [blame]6*****************
7
8.. contents::
9 :depth: 3
10
11Installation
12^^^^^^^^^^^^
13
14Build 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
21Installation 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
113Verify 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
121Verify 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
212Running 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
247Build 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 #
a.sreekumarcc0e9172020-03-16 13:36:45 +0000[diff] [blame]267 # Docker file to build an image that runs APEX on Java 11 or better in alpine
ramverma3b71c972019-07-10 11:25:37 +0000[diff] [blame]268 #
a.sreekumarcc0e9172020-03-16 13:36:45 +0000[diff] [blame]269 FROM onap/policy-jre-alpine:2.0.1
ramverma3b71c972019-07-10 11:25:37 +0000[diff] [blame]270
271 LABEL maintainer="Policy Team"
272
ramverma3b71c972019-07-10 11:25:37 +0000[diff] [blame]273 ARG POLICY_LOGS=/var/log/onap/policy/apex-pdp
a.sreekumarcc0e9172020-03-16 13:36:45 +0000[diff] [blame]274 ENV POLICY_HOME=/opt/app/policy/apex-pdp
275 ENV POLICY_LOGS=$POLICY_LOGS
ramverma3b71c972019-07-10 11:25:37 +0000[diff] [blame]276
277 RUN apk add --no-cache \
a.sreekumarcc0e9172020-03-16 13:36:45 +0000[diff] [blame]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
ramverma3b71c972019-07-10 11:25:37 +0000[diff] [blame]286
a.sreekumarcc0e9172020-03-16 13:36:45 +0000[diff] [blame]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 \
ramverma3b71c972019-07-10 11:25:37 +0000[diff] [blame]291 && find /opt/app -type f -perm 644 \
a.sreekumarcc0e9172020-03-16 13:36:45 +0000[diff] [blame]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/*
ramverma3b71c972019-07-10 11:25:37 +0000[diff] [blame]296
297 USER apexuser
a.sreekumarcc0e9172020-03-16 13:36:45 +0000[diff] [blame]298 ENV PATH $POLICY_HOME/bin:$PATH
ramverma3b71c972019-07-10 11:25:37 +0000[diff] [blame]299 WORKDIR /home/apexuser
300
301
302APEXOnapPf 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
313Format 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)
a.sreekumarcc0e9172020-03-16 13:36:45 +0000[diff] [blame]340 "pdpGroup":"defaultGroup", (5)
ramverma3b71c972019-07-10 11:25:37 +0000[diff] [blame]341 "description":"Pdp Heartbeat",
a.sreekumarcc0e9172020-03-16 13:36:45 +0000[diff] [blame]342 "supportedPolicyTypes":[{"name":"onap.policies.controlloop.operational.Apex","version":"1.0.0"}] (6)
ramverma3b71c972019-07-10 11:25:37 +0000[diff] [blame]343 },
344 "topicParameterGroup": {
a.sreekumarcc0e9172020-03-16 13:36:45 +0000[diff] [blame]345 "topicSources" : [{ (7)
346 "topic" : "POLICY-PDP-PAP", (8)
347 "servers" : [ "message-router" ], (9)
348 "topicCommInfrastructure" : "dmaap" (10)
ramverma3b71c972019-07-10 11:25:37 +0000[diff] [blame]349 }],
a.sreekumarcc0e9172020-03-16 13:36:45 +0000[diff] [blame]350 "topicSinks" : [{ (11)
351 "topic" : "POLICY-PDP-PAP", (12)
352 "servers" : [ "message-router" ], (13)
353 "topicCommInfrastructure" : "dmaap" (14)
ramverma3b71c972019-07-10 11:25:37 +0000[diff] [blame]354 }]
355 }
356 }
357
358 .. container:: colist arabic
359
Saryu Shah1c3ea0b2019-11-25 18:08:00 +0000[diff] [blame]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 +-----------------------------------+-------------------------------------------------+
a.sreekumarcc0e9172020-03-16 13:36:45 +0000[diff] [blame]374 | **5** | The group to which the pdp belong to. |
375 +-----------------------------------+-------------------------------------------------+
376 | **6** | List of policy types supported by |
Saryu Shah1c3ea0b2019-11-25 18:08:00 +0000[diff] [blame]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 +-----------------------------------+-------------------------------------------------+
a.sreekumarcc0e9172020-03-16 13:36:45 +0000[diff] [blame]383 | **7** | List of topics' details from |
Saryu Shah1c3ea0b2019-11-25 18:08:00 +0000[diff] [blame]384 | | which messages are received. |
385 +-----------------------------------+-------------------------------------------------+
a.sreekumarcc0e9172020-03-16 13:36:45 +0000[diff] [blame]386 | **8** | Topic name of the source to which |
Saryu Shah1c3ea0b2019-11-25 18:08:00 +0000[diff] [blame]387 | | PDP-A listens to for messages |
388 | | from PAP. |
389 +-----------------------------------+-------------------------------------------------+
a.sreekumarcc0e9172020-03-16 13:36:45 +0000[diff] [blame]390 | **9** | List of servers for the source |
Saryu Shah1c3ea0b2019-11-25 18:08:00 +0000[diff] [blame]391 | | topic. |
392 +-----------------------------------+-------------------------------------------------+
a.sreekumarcc0e9172020-03-16 13:36:45 +0000[diff] [blame]393 | **10** | The source topic infrastructure. |
Saryu Shah1c3ea0b2019-11-25 18:08:00 +0000[diff] [blame]394 | | For e.g. dmaap, noop, ueb |
395 +-----------------------------------+-------------------------------------------------+
a.sreekumarcc0e9172020-03-16 13:36:45 +0000[diff] [blame]396 | **11** | List of topics' details to which |
Saryu Shah1c3ea0b2019-11-25 18:08:00 +0000[diff] [blame]397 | | messages are sent. |
398 +-----------------------------------+-------------------------------------------------+
a.sreekumarcc0e9172020-03-16 13:36:45 +0000[diff] [blame]399 | **12** | Topic name of the sink to which |
Saryu Shah1c3ea0b2019-11-25 18:08:00 +0000[diff] [blame]400 | | PDP-A sends messages. |
401 +-----------------------------------+-------------------------------------------------+
a.sreekumarcc0e9172020-03-16 13:36:45 +0000[diff] [blame]402 | **13** | List of servers for the sink |
Saryu Shah1c3ea0b2019-11-25 18:08:00 +0000[diff] [blame]403 | | topic. |
404 +-----------------------------------+-------------------------------------------------+
a.sreekumarcc0e9172020-03-16 13:36:45 +0000[diff] [blame]405 | **14** | The sink topic infrastructure. |
Saryu Shah1c3ea0b2019-11-25 18:08:00 +0000[diff] [blame]406 | | For e.g. dmaap, noop, ueb |
407 +-----------------------------------+-------------------------------------------------+