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