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

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

::

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

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

.. code::

:number-lines:

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

.. code::

:number-lines:

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

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

| **1** | UNIX |

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

| **2** | Cygwin |

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

| **3** | Windows |

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

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

.. code::

:number-lines:

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

::

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

::

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.

Build a Docker Image

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

.. container:: paragraph

251

252

Alternatively, one can use the Dockerfile defined in the Docker

253

package to build an image.

254

255

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

268

#

269

FROM onap/policy-base-alpine:1.4.0

270

271

LABEL maintainer="Policy Team"

272

273

ARG BUILD_VERSION=${BUILD_VERSION}

274

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

275

276

ENV BUILD_VERSION ${BUILD_VERSION}

277

ENV POLICY_HOME=/opt/app/policy

278

ENV POLICY_APEX_PDP_HOME=${POLICY_HOME}/apex-pdp

279

ENV POLICY_LOGS=${POLICY_LOGS}

280

281

RUN apk add --no-cache \

vim \

iproute2 \

iputils

# Create apex user and group

287

RUN addgroup -S apexuser && adduser -S apexuser -G apexuser

288

289

290

# Add Apex-specific directories and set ownership as the Apex admin user

291

RUN mkdir -p ${POLICY_APEX_PDP_HOME} \

292

&& mkdir -p ${POLICY_LOGS} \

293

&& chown -R apexuser:apexuser ${POLICY_LOGS}

# Unpack the tarball

RUN mkdir /packages

COPY apex-pdp-package-full.tar.gz /packages

298

RUN tar xvfz /packages/apex-pdp-package-full.tar.gz --directory ${POLICY_APEX_PDP_HOME} \

299

&& rm /packages/apex-pdp-package-full.tar.gz

300

301

# Ensure everything has the correct permissions

302

RUN find /opt/app -type d -perm 755 \

303

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

304

&& chmod a+x ${POLICY_APEX_PDP_HOME}/bin/*

305

306

# Copy examples to Apex user area

307

RUN cp -pr ${POLICY_APEX_PDP_HOME}/examples /home/apexuser \

308

&& chown -R apexuser:apexuser /home/apexuser/*

309

310

USER apexuser

311

ENV PATH ${POLICY_APEX_PDP_HOME}/bin:$PATH

312

WORKDIR /home/apexuser

313

314

315

APEXOnapPf Configuration File Explained

316

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

317

318

.. container:: paragraph

319

320

The ApexOnapPf is initialized using a configuration file:

.. container:: ulist

- OnapPfConfig.json

Format of the configuration file (OnapPfConfig.json) explained

327

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

328

329

.. container:: paragraph

330

331

The configuration file is a JSON file containing the initial values for configuring the rest server for healthcheck and the pdp itself.

332

The topic infrastructure and the topics to be used for sending or receiving messages is specified in this configuration file.

333

A sample can be found below:

334

335

.. container:: listingblock

336

337

.. container:: content

.. code::

{

"name":"ApexStarterParameterGroup",

343

"restServerParameters": { (1)

"host": "0.0.0.0",

"port": 6969,

"userName": "...",

"password": "...",

"https": true (2)

},

"pdpStatusParameters":{

351

"timeIntervalMs": 120000, (3)

352

"pdpType":"apex", (4)

353

"description":"Pdp Heartbeat",

354

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

355

},

356

"topicParameterGroup": {

357

"topicSources" : [{ (6)

358

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

359

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

360

"topicCommInfrastructure" : "dmaap" (9)

361

}],

362

"topicSinks" : [{ (10)

363

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

364

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

365

"topicCommInfrastructure" : "dmaap" (13)

}]

}

}

.. container:: colist arabic

371

372

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

373

| **1** | parameters for setting up the |

374

| | rest server such as host, port |

375

| | userName and password. |

376

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

377

| **2** | https flag if enabled will enable |

378

| | https support by the rest server. |

379

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

380

| **3** | time interval in which PDP-A |

381

| | has to send heartbeats to PAP. |

382

| | Specified in milliseconds. |

383

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

384

| **4** | Type of the pdp. |

385

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

386

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

387

| | the PDP. |

388

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

389

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

390

| | which messages are received. |

391

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

392

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

393

| | PDP-A listens to for messages |

394

| | from PAP. |

395

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

396

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

397

| | topic. |

398

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

399

| **9** | The source topic infrastructure. |

400

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

401

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

402

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

403

| | messages are sent to. |

404

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

405

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

406

| | PDP-A sends messages to. |

407

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

408

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

409

| | topic. |

410

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

411

| **13** | The sink topic infrastructure. |

412

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

413

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