solution/integration/README.md

   1 # Service Management and Orchestration (SMO)
   2
   3 ##### Table of Contents
   4 [Service Management and Orchestration (SMO)](#service-management-and-orchestration-smo)
   5 - [Introduction](#introduction)
   6 - [Overview](#overview)
   7 - [Prerequisites](#prerequisites)
   8 - [Usage](#usage)
   9   - [Bring Up Solution](#bring-up-solution)
  10   - [Log files and karaf console](#log-files-and-karaf-console)
  11   - [Customizing Solution](#customizing-solution)
  12   - [Verification Solution](#verification-solution)
  13     - [Access to SDN-R UX](#access-to-sdn-r-ux)
  14   - [Terminate solution](#terminate-solution)
  15   - [Cleanup](#cleanup)
  16   - [Troubleshooting](#troubleshooting)
  17
  18 ## Introduction
  19
  20 With respect to OAM the SMO implements the O1-interface consumers. According to the O-RAN OAM Architecture and the O-RAN OAM Interface Specification, the SMO implements a NetConf Client for configuration and a HTTP/REST/VES server for receiving all kind of events in a VES format.
  21
  22 The setup contains an OpenDaylight based NetConf client and a VES Collector.
  23
  24 ## Overview
  25
  26 This docker-compose file starts a pre-configured, self-contained SDN-R solution
  27 for developer test or demo purposes
  28
  29   * **Identity**
  30     ... representing an KeyCloak based identity service for centralized user
  31     management. Please note that the implementation does not support IPv6.
  32     Therefore, its own network is required called 'DMZ'.
  33     In this configuration the external https port is 8463.
  34
  35   * **SDN-R** single node instance
  36
  37     ... representing the NetConf consumer on the Service Management and
  38     Orchestration framework (SMO) for the O1 interface based on
  39     ODL-Silicon/ONAP-Istanbul
  40     SDN-R comes with is own web-portal the external port is 8463.
  41
  42   * **VES collector**
  43
  44     ... representing the VES (REST) provider at SMO for all kind of events. In this configuration the external https port is 8443.
  45
  46   * **DMaaP**
  47     ... representing SMO DMaaP component, includes message-router
  48
  49   * **ONAP-Policy**
  50     ... representing all the components of ONAP policy framework, in particular
  51     the policy-apex-pdp which executes the apex policies deployed in the framework
  52     when a certain event occurs.
  53
  54   * **Non-RT-RIC**
  55     ... representing all the components of Non-RT-RIC, includes Non-RT-RIC Control Panel, Non-RT-RIC (Spring Cloud) Service Gateway, A1 Policy Management Services,
  56     Enrichment Data Coordinator, Non-RT-RIC App Catalogue, "HelloWorld" O-RU Fronthaul Recovery use-case, Near-RT RIC A1 Simulator etc.
  57
  58 ## Prerequisites
  59
  60 ```
  61 $ cat /etc/os-release | grep PRETTY_NAME
  62 PRETTY_NAME="Ubuntu 20.04.2 LTS"
  63
  64 $ docker --version
  65 Docker version 20.10.7, build 20.10.7-0ubuntu1~20.04.2
  66
  67 $ docker-compose version
  68 docker-compose version 1.29.1, build c34c88b2
  69 docker-py version: 5.0.0
  70 CPython version: 3.7.10
  71 OpenSSL version: OpenSSL 1.1.0l  10 Sep 2019
  72
  73
  74 $ git --version
  75 git version 2.25.1
  76
  77 ```
  78 Please modify the /etc/hosts of your system.
  79
  80 * <your-system>: is the hostname of the system, where the browser is started
  81
  82 * <deployment-system-ipv4>: is the IP address of the system where the solution will be deployed
  83
  84 For development purposes <your-system> and <deployment-system> may reference the same system.
  85
  86 ```
  87 $ cat /etc/hosts
  88 127.0.0.1                     localhost
  89 127.0.1.1                     <your-system>
  90 <deployment-system-ipv4>   sdnc-web <your-system>
  91 <deployment-system-ipv4>   identity <your-system>
  92 ```
  93
  94 It is beneficial (but not mandatory) adding the following line add the
  95 end of your ~/.bashrc file. I will suppress warnings when python script
  96 do not verify self signed certificates for HTTPS communication.
  97 ```
  98 export PYTHONWARNINGS="ignore:Unverified HTTPS request"
  99 ```
 100
 101 Please ensure that you download and copy the required 3GPP OpenAPIs for VES-stndDefined
 102 message validation into the folder './solution/integration/smo/oam/ves-collector/externalRepo'.
 103
 104 Please follow the instructions in ./solution/integration/smo/oam/ves-collector/externalRepo/3gpp/rep/sa5/MnS/blob/Rel16/OpenAPI/README.md.
 105
 106 The following tree shows the successfully tested folder structure. It combines different versions of the schemas ('Rel16' and 'SA88-Rel16') using 3GPP branch names.
 107
 108 ```
 109 $ tree solution/integration/smo/oam/ves-collector/externalRepo/
 110 solution/integration/smo/oam/ves-collector/externalRepo/
 111 ├── 3gpp
 112 │   └── rep
 113 │       └── sa5
 114 │           └── MnS
 115 │               └── blob
 116 │                   ├── Rel16
 117 │                   │   └── OpenAPI
 118 │                   │       ├── TS28532_FaultMnS.yaml
 119 │                   │       ├── TS28532_FileDataReportingMnS.yaml
 120 │                   │       ├── TS28532_HeartbeatNtf.yaml
 121 │                   │       ├── TS28532_PerfMnS.yaml
 122 │                   │       ├── TS28532_ProvMnS.yaml
 123 │                   │       ├── TS28532_StreamingDataMnS.yaml
 124 │                   │       ├── TS28536_CoslaNrm.yaml
 125 │                   │       ├── TS28541_5GcNrm.yaml
 126 │                   │       ├── TS28541_NrNrm.yaml
 127 │                   │       ├── TS28541_SliceNrm.yaml
 128 │                   │       ├── TS28550_PerfMeasJobCtrlMnS.yaml
 129 │                   │       ├── TS28623_ComDefs.yaml
 130 │                   │       ├── TS28623_GenericNrm.yaml
 131 │                   │       ├── TS29512_Npcf_SMPolicyControl.yaml
 132 │                   │       ├── TS29514_Npcf_PolicyAuthorization.yaml
 133 │                   │       └── TS29571_CommonData.yaml
 134 │                   └── SA88-Rel16
 135 │                       └── OpenAPI
 136 │                           ├── 5gcNrm.yaml
 137 │                           ├── PerDataFileReportMnS.yaml
 138 │                           ├── PerMeasJobCtlMnS.yaml
 139 │                           ├── PerThresMonMnS.yaml
 140 │                           ├── PerfDataStreamingMnS.yaml
 141 │                           ├── README.md
 142 │                           ├── comDefs.yaml
 143 │                           ├── coslaNrm.yaml
 144 │                           ├── faultMnS.yaml
 145 │                           ├── genericNrm.yaml
 146 │                           ├── heartbeatNtf.yaml
 147 │                           ├── nrNrm.yaml
 148 │                           ├── provMnS.yaml
 149 │                           ├── sliceNrm.yaml
 150 │                           └── streamingDataMnS.yaml
 151 ```
 152
 153 ## Expected Folder Structure
 154
 155 ```
 156 ├── network
 157 │   ├── .env
 158 │   ├── config.py
 159 │   ├── docker-compose.yml
 160 │   │
 161 │   ├── ntsim-ng-o-du
 162 │   └── ntsim-ng-o-ru
 163 └── smo
 164     ├── common
 165     │   ├── .env
 166     │   ├── docker-compose.yml
 167     │   │
 168     │   ├── dmaap
 169     │   ├── docker
 170     │   ├── identity
 171     │   ├── kafka
 172     │   ├── o-ran-sc-topology-service
 173     │   └── zookeeper
 174     ├── non-rt-ric
 175     │   ├── docker-compose.yml
 176     │   │
 177     │   ├── test
 178     │   ├── data
 179     │   └── config
 180     ├── oam
 181     │   ├── docker-compose.yml
 182     │   │
 183     │   ├── sdnc-web
 184     │   ├── sdnr
 185     │   └── ves-collector
 186     └── onap-policy
 187         ├── docker-compose.yml
 188         │
 189         ├── config
 190         └── wait_for_port.sh
 191 ```
 192
 193 ## Usage
 194
 195 ### Bring Up Solution
 196
 197 #### Check (adjust if required) environment variables
 198
 199 ```
 200 nano smo/common/.env
 201 nano smo/non-rt-ric/.env
 202 nano smo/oam/.env
 203 nano network/.env
 204 ```
 205
 206 The tested configuration uses the following external https ports:
 207
 208  * 8443 for the ves-collector
 209  * 8453 for web access to ODLUX (SDNC_WEB_PORT)
 210  * 8463 for the keyclock web administrator user interface.
 211
 212 #### Startup solution
 213
 214 Please note that it is necessary to configure first the identity service,
 215 before starting further docker images.
 216
 217 The several docker-compose yml files must be started in the right order as listed below:
 218
 219 ```
 220 docker-compose -f smo/common/docker-compose.yml up -d
 221 python smo/common/identity/config.py
 222 ```
 223
 224 The python script configure the users within the identity service (keycloak).
 225 A system user (%USER) is also created with administration rights.
 226
 227 ```
 228 docker-compose -f smo/onap-policy/docker-compose.yml up -d
 229 docker-compose -f smo/oam/docker-compose.yml up -d
 230 docker-compose -f smo/non-rt-ric/docker-compose.yml up -d
 231 ```
 232
 233 In order to create/deploy the apex policy for O-RU closed loop recovery use case,
 234 refer to the section named "Create/Deploy apex policy for O-RU & O-DU use case" in
 235 this page:
 236 https://wiki.o-ran-sc.org/pages/viewpage.action?pageId=35881325
 237
 238 Please note that the above instructions assume that the ToscaPolicy.json file
 239 with default config needs to be deployed. However, when there is a need to update
 240 the config (for example, to change the O-RU to O-DU mapping), a new ToscaPolicy.json
 241 file needs to be created. Refer to the section named "Workflow for updating the policy config"
 242 in this page:
 243 https://wiki.o-ran-sc.org/pages/viewpage.action?pageId=35881325
 244
 245 Please wait about 2min until all the service are up and running.
 246 If you see the login page (https://sdnc-web:8453) you are good to go and can start the (simulated) network.
 247
 248 ### populate data into Non-RT-RIC
 249
 250 Full instruction on how to run Non-RT-RIC can be found in this page:
 251 <https://wiki.o-ran-sc.org/display/RICNR/Release+D>
 252
 253 When containers in Non-RT-RIC are all up, by default, there is no data running inside. Folder `non-rt-ric/data/` contains several scripts to populate data into Non-RT-RIC for test & demo purpose.
 254
 255 ```
 256 bash prepareDmaapMsg.sh
 257 ```
 258
 259 script `prepareDmaapMsg.sh` sends messages to DMaaP message router, then Non-RT-RIC policy-agent service polls messages from DMaaP, and creates policy instances accordingly.
 260
 261 ```
 262 bash preparePmsData.sh
 263 ```
 264
 265 script `preparePmsData.sh` sends http requests to policy-agent service, and creates policy instances accordingly.
 266
 267 ```
 268 bash prepareEcsData.sh
 269 ```
 270
 271 script `prepareIcsData.sh` sends http requests to ics service, and creates data accordingly.
 272
 273 Afterwards, open webpage:
 274 <http://localhost:8182/>
 275 Now we should see some data in the page.
 276
 277 ```
 278 docker-compose -f network/docker-compose.yml up -d
 279 ```
 280
 281 Usually the first ves:event gets lost. Please restart the O-DU docker container(s) to send a second ves:pnfRegistration.
 282
 283 ```
 284 docker-compose -f network/docker-compose.yml restart ntsim-ng-o-du-1122
 285 python network/config.py
 286 ```
 287
 288 The python script configures the simulated O-DU and O-RU according to O-RAN hybrid architecture.
 289
 290 O-DU - NETCONF Call HOME and NETCONF notifications
 291 O-RU - ves:pnfRegistration and ves:fault, ves:heartbeat
 292
 293
 294 ![ves:pnfRegistration in ODLUX](docs/nstim-ng-connected-after-ves-pnf-registration-in-odlux.png "ves:pnfRegistration in ODLUX")
 295
 296 'True' indicated that the settings through SDN-R to the NETCONF server were
 297 successful.
 298
 299 SDN-R reads the fault events from DMaaP and processes them.
 300 Finally the fault events are visible in ODLUX.
 301
 302 ![ves:fault in ODLUX](docs/ves-fault-in-odlux.png "ves:fault in ODLUX")
 303
 304
 305 ### Log files and karaf console
 306
 307 #### ODL karaf.logs
 308
 309 ```
 310 docker exec -it sdnr tail -f /opt/opendaylight/data/log/karaf.log
 311 ```
 312
 313 #### karaf console access (karaf:karaf)
 314
 315 ```
 316 ssh karaf@localhost -p 8101
 317 ```
 318
 319 #### ves-collector logs
 320
 321 ```
 322 docker logs -f ves-collector
 323 ```
 324
 325 #### onap-policy apex logs
 326
 327 ```
 328 docker logs policy-apex-pdp
 329 ```
 330
 331 #### Non-RT-RIC logs
 332
 333 ```
 334 docker logs policy-agent
 335 docker logs oru-app
 336 docker logs ecs
 337 ```
 338
 339 ### Customizing Solution
 340
 341 '.env' file contains customizing parameters
 342
 343 ### Verification Solution
 344
 345 #### Access to SDN-R ODLUX
 346
 347 ##### Login into SDN-R
 348
 349     https://sdnc-web:8453
 350
 351     User: admin // see .env file
 352
 353     Password: Kp8bJ4SXszM0WXlhak3eHlcse2gAw84vaoGGmJvUy2U
 354
 355 In case of trouble, please update the commands with your customized '.env' file.
 356
 357 #### Access to Topology Service
 358
 359 ```
 360 curl -u admin:admin http://localhost:18181/rests/data/network-topology:network-topology/topology=topology-netconf/node=o-ran-sc-topology-service/yang-ext:mount/tapi-common:context/tapi-topology:topology-context
 361 ```
 362
 363 #### Access to Wireshark
 364
 365 ```
 366   http://localhost:3000
 367 ```
 368
 369 Select the interfaces you would like to capture.
 370 As first guess, please select the bridge interfaces.
 371 ### Terminate solution
 372
 373 To stop all container please respect the following order
 374
 375 ```
 376 docker-compose -f network/docker-compose.yml down
 377 docker-compose -f smo/oam/docker-compose.yml down
 378 docker-compose -f smo/onap-policy/docker-compose.yml down
 379 docker-compose -f smo/non-rt-ric/docker-compose.yml down
 380 docker-compose -f smo/common/docker-compose.yml down
 381 ```
 382
 383 ### Cleanup
 384
 385 !!! be careful if other stopped containers are on the same system
 386 ```
 387 docker system prune -a -f
 388 ```
 389 ### Troubleshooting
 390
 391 In most cases the .env setting do not fit to the environment and need to be
 392 adjusted.
 393
 394 Please make sure that the network settings to not overlap with other networks.
 395
 396 The commands ...
 397 ```
 398 docker ps -a
 399 docker-compose ps
 400
 401 ## Prerequisites
 402 # python3, tmux, libtmux
 403 tmux new-session -n workspace -s integration
 404
 405 # within tmux session
 406 python tmux-logging.py
 407 ```
 408 ... are your friends.
 409
 410 ![tmux logging](docs/tmux-logging.png "tmux logging")