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 ## Expected Folder Structure
 102
 103 ```
 104 ├── network
 105 │   ├── .env
 106 │   ├── config.py
 107 │   ├── docker-compose.yml
 108 │   │
 109 │   ├── ntsim-ng-o-du
 110 │   └── ntsim-ng-o-ru
 111 └── smo
 112     ├── common
 113     │   ├── .env
 114     │   ├── docker-compose.yml
 115     │   │
 116     │   ├── dmaap
 117     │   ├── docker
 118     │   ├── identity
 119     │   ├── kafka
 120     │   └── zookeeper
 121     ├── non-rt-ric
 122     │   ├── docker-compose.yml
 123     │   │
 124     │   ├── test
 125     │   ├── data
 126     │   └── config
 127     ├── oam
 128     │   ├── docker-compose.yml
 129     │   │
 130     │   ├── sdnc-web
 131     │   ├── sdnr
 132     │   └── ves-collector
 133     └── onap-policy
 134         ├── docker-compose.yml
 135         │
 136         ├── config
 137         └── wait_for_port.sh
 138 ```
 139
 140 ## Usage
 141
 142 ### Bring Up Solution
 143
 144 #### Check (adjust if required) environment variables
 145
 146 ```
 147 nano smo/common/.env
 148 nano smo/non-rt-ric/.env
 149 nano smo/oam/.env
 150 nano network/.env
 151 ```
 152
 153 The tested configuration uses the following external https ports:
 154
 155  * 8443 for the ves-collector
 156  * 8453 for web access to ODLUX (SDNC_WEB_PORT)
 157  * 8463 for the keyclock web administrator user interface.
 158
 159 #### Startup solution
 160
 161 Please note that it is necessary to configure first the identity service,
 162 before starting further docker images.
 163
 164 The several docker-compose yml files must be started in the right order as listed below:
 165
 166 ```
 167 docker-compose -f smo/common/docker-compose.yml up -d
 168 python smo/common/identity/config.py
 169 ```
 170
 171 The python script configure the users within the identity service (keycloak).
 172 A system user (%USER) is also created with administration rights.
 173
 174 ```
 175 docker-compose -f smo/onap-policy/docker-compose.yml up -d
 176 docker-compose -f smo/oam/docker-compose.yml up -d
 177 docker-compose -f smo/non-rt-ric/docker-compose.yml up -d
 178 ```
 179
 180 In order to create/deploy the apex policy for O-RU closed loop recovery usecase,
 181 refer to the section named "Create/Deploy apex policy for O-RU & O-DU use case" in
 182 this page:
 183 https://wiki.o-ran-sc.org/pages/viewpage.action?pageId=35881325
 184
 185 Please note that the above instructions assume that the ToscaPolicy.json file
 186 with default config needs to be deployed. However, when there is a need to update
 187 the config (for example, to change the O-RU to O-DU mapping), a new ToscaPolicy.json
 188 file needs to be created. Refer to the section named "Workflow for updating the policy config"
 189 in this page:
 190 https://wiki.o-ran-sc.org/pages/viewpage.action?pageId=35881325
 191
 192 Please wait about 2min until all the service are up and running.
 193 If you see the login page (https://sdnc-web:8453) you are good to go and can start the (simulated) network.
 194
 195 ### populate data into Non-RT-RIC
 196
 197 Full instrucion on how to run Non-RT-RIC can be found in this page:
 198 <https://wiki.o-ran-sc.org/display/RICNR/Release+D>
 199
 200 When containers in Non-RT-RIC are all up, by default, there is no data running inside. Folder `non-rt-ric/data/` contains serveral scripts to populate data into Non-RT-RIC for test & demo purpose.
 201
 202 ```
 203 bash prepareDmaapMsg.sh
 204 ```
 205
 206 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.
 207
 208 ```
 209 bash preparePmsData.sh
 210 ```
 211
 212 script `preparePmsData.sh` sends http requests to policy-agent service, and creates policy instances accordingly.
 213
 214 ```
 215 bash prepareEcsData.sh
 216 ```
 217
 218 script `prepareEcsData.sh` sends http requests to ecs service, and creates data accordingly.
 219
 220 Afterwards, open webpage:
 221 <http://localhost:8182/>
 222 Now we should see some data in the page.
 223
 224 ```
 225 docker-compose -f network/docker-compose.yml up -d
 226 ```
 227
 228 Usually the first ves:event gets lost. Please restart the O-DU docker container(s) to send a second ves:pnfRegistration.
 229
 230 ```
 231 docker-compose -f network/docker-compose.yml restart ntsim-ng-o-du-1122
 232 python network/config.py
 233 ```
 234
 235 The python script configures the simulated O-DU and O-RU according to O-RAN hybrid architecture.
 236
 237 O-DU - NETCONF Call HOME and NETCONF notifications
 238 O-RU - ves:pnfRegistration and ves:fault, ves:heartbeat
 239
 240
 241 ![ves:pnfRegistration in ODLUX](docs/nstim-ng-connected-after-ves-pnf-registration-in-odlux.png "ves:pnfRegistration in ODLUX")
 242
 243 'True' indicated that the settings through SDN-R to the NETCONF server were
 244 successful.
 245
 246 SDN-R reads the fault events from DMaaP and processes them.
 247 Finally the fault events are visible in ODLUX.
 248
 249 ![ves:fault in ODLUX](docs/ves-fault-in-odlux.png "ves:fault in ODLUX")
 250
 251
 252 ### Log files and karaf console
 253
 254 #### ODL karaf.logs
 255
 256 ```
 257 docker exec -it sdnr tail -f /opt/opendaylight/data/log/karaf.log
 258 ```
 259
 260 #### karaf console access (karaf:karaf)
 261
 262 ```
 263 ssh karaf@localhost -p 8101
 264 ```
 265
 266 #### ves-collector logs
 267
 268 ```
 269 docker logs -f ves-collector
 270 ```
 271
 272 #### onap-policy apex logs
 273
 274 ```
 275 docker logs policy-apex-pdp
 276 ```
 277
 278 #### Non-RT-RIC logs
 279
 280 ```
 281 docker logs policy-agent
 282 docker logs oru-app
 283 docker logs ecs
 284 ```
 285
 286 ### Customizing Solution
 287
 288 '.env' file contains customizing parameters
 289
 290 ### Verification Solution
 291
 292 #### Access to SDN-R ODLUX
 293
 294 ##### Login into SDN-R
 295
 296     https://sdnc-web:8453
 297
 298     User: admin // see .env file
 299
 300     Password: Kp8bJ4SXszM0WXlhak3eHlcse2gAw84vaoGGmJvUy2U
 301
 302 In case of trouble, please update the commands with your customized '.env' file.
 303
 304 ### Terminate solution
 305
 306 To stop all container please respect the following order
 307
 308 ```
 309 docker-compose -f network/docker-compose.yml down
 310 docker-compose -f smo/oam/docker-compose.yml down
 311 docker-compose -f smo/onap-policy/docker-compose.yml down
 312 docker-compose -f smo/non-rt-ric/docker-compose.yml down
 313 docker-compose -f smo/common/docker-compose.yml down
 314 ```
 315
 316 ### Cleanup
 317
 318 !!! be careful if other stopped containers are on the same system
 319 ```
 320 docker system prune -a -f
 321 ```
 322 ### Troubleshooting
 323
 324 In most cases the .env setting do not fit to the environment and need to be
 325 adjusted.
 326
 327 Please make sure that the network settings to not overlap with other networks.
 328
 329 The commands ...
 330 ```
 331 docker ps -a
 332 docker-compose ps
 333
 334 ## Prerequisites
 335 # python3, tmux, libtmux
 336 tmux new-session -n workspace -s integration
 337
 338 # within tmux session
 339 python tmux-logging.py
 340 ```
 341 ... are your friends.
 342
 343 ![tmux logging](docs/tmux-logging.png "tmux logging")