Blame - docs/apex/APEX-OnapPf-Guide.rst - onap/policy/parent

2019-07-10 11:25:37 +0000

[diff] [blame]

Installation Layout

-------------------

.. container:: paragraph

26

27

A full installation of APEX comes with the following layout.

28

29

.. container:: listingblock

30

31

.. 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)

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

.. code::

:number-lines:

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

.. code::

:number-lines:

# $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

+-------+---------+

| **1** | UNIX |

+-------+---------+

| **2** | Cygwin |

+-------+---------+

| **3** | Windows |

+-------+---------+

.. 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

.. code::

:number-lines:

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

::

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

::

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.

Build a Docker Image

####################

.. container:: paragraph

252

253

Alternatively, one can use the Dockerfile defined in the Docker

254

package to build an image.

255

256

.. container:: listingblock

.. container:: title

APEX Dockerfile

.. container:: content

.. code::

:number-lines:

#

a.sreekumar

2020-03-16 13:36:45 +0000

[diff] [blame]

268

# Docker file to build an image that runs APEX on Java 11 or better in alpine

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

269

#

a.sreekumar

2020-03-16 13:36:45 +0000

[diff] [blame]

270

FROM onap/policy-jre-alpine:2.0.1

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

271

272

LABEL maintainer="Policy Team"

273

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

274

ARG POLICY_LOGS=/var/log/onap/policy/apex-pdp

a.sreekumar

2020-03-16 13:36:45 +0000

[diff] [blame]

275

ENV POLICY_HOME=/opt/app/policy/apex-pdp

276

ENV POLICY_LOGS=$POLICY_LOGS

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

277

278

RUN apk add --no-cache \

a.sreekumar

2020-03-16 13:36:45 +0000

[diff] [blame]

vim \

iproute2 \

iputils \

&& 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

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

287

a.sreekumar

2020-03-16 13:36:45 +0000

[diff] [blame]

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 \

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

292

&& find /opt/app -type f -perm 644 \

a.sreekumar

2020-03-16 13:36:45 +0000

[diff] [blame]

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/*

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

297

298

USER apexuser

a.sreekumar

2020-03-16 13:36:45 +0000

[diff] [blame]

299

ENV PATH $POLICY_HOME/bin:$PATH

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

300

WORKDIR /home/apexuser

301

302

303

APEXOnapPf Configuration File Explained

liamfallon

688a2dd

2022-11-01 13:16:21 +0000

[diff] [blame^]

304

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

305

306

.. container:: paragraph

307

308

The ApexOnapPf is initialized using a configuration file:

.. container:: ulist

- OnapPfConfig.json

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

.. code::

{

"name":"ApexStarterParameterGroup",

331

"restServerParameters": { (1)

"host": "0.0.0.0",

"port": 6969,

"userName": "...",

"password": "...",

"https": true (2)

},

"pdpStatusParameters":{

339

"timeIntervalMs": 120000, (3)

340

"pdpType":"apex", (4)

a.sreekumar

2020-03-16 13:36:45 +0000

[diff] [blame]

341

"pdpGroup":"defaultGroup", (5)

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

342

"description":"Pdp Heartbeat",

a.sreekumar

2020-03-16 13:36:45 +0000

[diff] [blame]

343

"supportedPolicyTypes":[{"name":"onap.policies.controlloop.operational.Apex","version":"1.0.0"}] (6)

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

344

},

345

"topicParameterGroup": {

a.sreekumar

2020-03-16 13:36:45 +0000

[diff] [blame]

346

"topicSources" : [{ (7)

347

"topic" : "POLICY-PDP-PAP", (8)

348

"servers" : [ "message-router" ], (9)

349

"topicCommInfrastructure" : "dmaap" (10)

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

350

}],

a.sreekumar

2020-03-16 13:36:45 +0000

[diff] [blame]

351

"topicSinks" : [{ (11)

352

"topic" : "POLICY-PDP-PAP", (12)

353

"servers" : [ "message-router" ], (13)

354

"topicCommInfrastructure" : "dmaap" (14)

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

}]

}

}

.. container:: colist arabic

360

Saryu Shah

2019-11-25 18:08:00 +0000

[diff] [blame]

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

+-----------------------------------+-------------------------------------------------+

a.sreekumar

2020-03-16 13:36:45 +0000

[diff] [blame]

375

| **5** | The group to which the pdp belong to. |

376

+-----------------------------------+-------------------------------------------------+

377

| **6** | List of policy types supported by |

Saryu Shah

2019-11-25 18:08:00 +0000

[diff] [blame]

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

+-----------------------------------+-------------------------------------------------+

a.sreekumar

2020-03-16 13:36:45 +0000

[diff] [blame]

384

| **7** | List of topics' details from |

Saryu Shah

2019-11-25 18:08:00 +0000

[diff] [blame]

385

| | which messages are received. |

386

+-----------------------------------+-------------------------------------------------+

a.sreekumar

2020-03-16 13:36:45 +0000

[diff] [blame]

387

| **8** | Topic name of the source to which |

Saryu Shah

2019-11-25 18:08:00 +0000

[diff] [blame]

388

| | PDP-A listens to for messages |

389

| | from PAP. |

390

+-----------------------------------+-------------------------------------------------+

a.sreekumar

2020-03-16 13:36:45 +0000

[diff] [blame]

391

| **9** | List of servers for the source |

Saryu Shah

2019-11-25 18:08:00 +0000

[diff] [blame]

392

| | topic. |

393

+-----------------------------------+-------------------------------------------------+

a.sreekumar

2020-03-16 13:36:45 +0000

[diff] [blame]

394

| **10** | The source topic infrastructure. |

Saryu Shah

2019-11-25 18:08:00 +0000

[diff] [blame]

395

| | For e.g. dmaap, noop, ueb |

396

+-----------------------------------+-------------------------------------------------+

a.sreekumar

2020-03-16 13:36:45 +0000

[diff] [blame]

397

| **11** | List of topics' details to which |

Saryu Shah

2019-11-25 18:08:00 +0000

[diff] [blame]

398

| | messages are sent. |

399

+-----------------------------------+-------------------------------------------------+

a.sreekumar

2020-03-16 13:36:45 +0000

[diff] [blame]

400

| **12** | Topic name of the sink to which |

Saryu Shah

2019-11-25 18:08:00 +0000

[diff] [blame]

401

| | PDP-A sends messages. |

402

+-----------------------------------+-------------------------------------------------+

a.sreekumar

2020-03-16 13:36:45 +0000

[diff] [blame]

403

| **13** | List of servers for the sink |

Saryu Shah

2019-11-25 18:08:00 +0000

[diff] [blame]

404

| | topic. |

405

+-----------------------------------+-------------------------------------------------+

a.sreekumar

2020-03-16 13:36:45 +0000

[diff] [blame]

406

| **14** | The sink topic infrastructure. |

Saryu Shah