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
  34   * **SDN-R** single node instance
  35
  36     ... representing the NetConf consumer on the Service Management and
  37     Orchestration framework (SMO) for the O1 interface based on
  38     ODL-Silicon/ONAP-Istanbul
  39
  40   * **VES collector**
  41
  42     ... representing the VES (REST) provider at SMO for all kind of events.
  43
  44   * **DMaaP**
  45     ... representing SMO DMaaP component, includes message-router
  46
  47   * **ONAP-Policy**
  48     ... representing all the components of ONAP policy framework, in particular
  49     the policy-apex-pdp which executes the apex policies deployed in the framework
  50     when a certain event occurs.
  51
  52 ## Prerequisites
  53
  54 ```
  55 $ cat /etc/os-release | grep PRETTY_NAME
  56 PRETTY_NAME="Ubuntu 20.04.2 LTS"
  57
  58 $ docker --version
  59 Docker version 20.10.2, build 20.10.2-0ubuntu1~20.04.2
  60
  61 $ docker-compose version
  62 docker-compose version 1.29.1, build c34c88b2
  63 docker-py version: 5.0.0
  64 CPython version: 3.7.10
  65 OpenSSL version: OpenSSL 1.1.0l  10 Sep 2019
  66
  67 $ git --version
  68 git version 2.25.1
  69
  70 ```
  71 Please modify the /etc/hosts of your system.
  72
  73 * <your-system>: is the hostname of the system, where the browser is started
  74
  75 * <deployment-system-ipv4>: is the IP address of the system where the solution will be deployed
  76
  77 For development purposes <your-system> and <deployment-system> may reference the same system.
  78
  79 ```
  80 $ cat /etc/hosts
  81 127.0.0.1                     localhost
  82 127.0.1.1                     <your-system>
  83 <deployment-system-ipv4>   sdnc-web <your-system>
  84 <deployment-system-ipv4>   identity <your-system>
  85 ```
  86
  87 ## Expected Folder Structure
  88
  89 ```
  90 ├── network
  91 │   ├── .env
  92 │   ├── config.py
  93 │   ├── docker-compose.yml
  94 │   │
  95 │   ├── ntsim-ng-o-du
  96 │   └── ntsim-ng-o-ru
  97 └── smo
  98     ├── common
  99     │   ├── .env
 100     │   ├── docker-compose.yml
 101     │   │
 102     │   ├── dmaap
 103     │   ├── docker
 104     │   ├── identity
 105     │   ├── kafka
 106     │   └── zookeeper
 107     ├── non-rt-ric
 108     │   ├── .env
 109     │   ├── docker-compose.yml
 110     │   │
 111     │   └── <config-folders>
 112     ├── oam
 113     │   ├── docker-compose.yml
 114     │   │
 115     │   ├── sdnc-web
 116     │   ├── sdnr
 117     │   └── ves-collector
 118     └── onap-policy
 119         ├── docker-compose.yml
 120         │
 121         ├── config
 122         └── wait_for_port.sh
 123 ```
 124
 125 ## Usage
 126
 127 ### Bring Up Solution
 128
 129 #### Check (adjust if required) environment variables
 130
 131 ```
 132 nano smo/common/.env
 133 nano smo/non-rt-ric/.env
 134 nano smo/oam/.env
 135 nano network/.env
 136 ```
 137
 138 #### Startup solution
 139
 140 Please note that it is necessary to configure first the identity service,
 141 before starting further docker images.
 142
 143 The several docker-compose yml files must be started in the right order as listed below:
 144
 145 ```
 146 docker-compose -f smo/common/docker-compose.yml up -d
 147 python smo/common/identity/config.py
 148 ```
 149
 150 The python script configure the users within the identity service (keycloak).
 151 A system user (%USER) is also created with administration rights.
 152
 153 ```
 154 docker-compose -f smo/non-rt-ric/docker-compose.yml up -d
 155 docker-compose -f smo/onap-policy/docker-compose.yml up -d
 156 docker-compose -f smo/oam/docker-compose.yml up -d
 157 ```
 158
 159 In order to create/deploy the apex policy for O-RU closed loop recovery usecase,
 160 refer to the section named "Create/Deploy apex policy for O-RU & O-DU use case" in
 161 this page:
 162 https://wiki.o-ran-sc.org/pages/viewpage.action?pageId=35881325
 163
 164 Please note that the above instructions assume that the ToscaPolicy.json file
 165 with default config needs to be deployed. However, when there is a need to update
 166 the config (for example, to change the O-RU to O-DU mapping), a new ToscaPolicy.json
 167 file needs to be created. Refer to the section named "Workflow for updating the policy config"
 168 in this page:
 169 https://wiki.o-ran-sc.org/pages/viewpage.action?pageId=35881325
 170
 171 Please wait about 2min until all the service are up and running.
 172 If you see the login page (https://sdnc-web:8453) you are good to go and can start the (simulated) network.
 173
 174 ```
 175 docker-compose -f network/docker-compose.yml up -d
 176 ```
 177
 178 Usually the first ves:event gets lost. Please restart the O-DU docker container(s) to send a second ves:pnfRegistration.
 179
 180 ```
 181 docker-compose -f network/docker-compose.yml restart ntsim-ng-o-du-1122
 182 python network/config.py
 183 ```
 184
 185 The python script configures the simulated O-DU and O-RU according to O-RAN hybrid architecture.
 186
 187 O-DU - NETCONF Call HOME and NETCONF notifications
 188 O-RU - ves:pnfRegistration and ves:fault, ves:heartbeat
 189
 190
 191 ![ves:pnfRegistration in ODLUX](docs/nstim-ng-connected-after-ves-pnf-registration-in-odlux.png "ves:pnfRegistration in ODLUX")
 192
 193 'True' indicated that the settings through SDN-R to the NETCONF server were
 194 successful.
 195
 196 SDN-R reads the fault events from DMaaP and processes them.
 197 Finally the fault events are visible in ODLUX.
 198
 199 ![ves:fault in ODLUX](docs/ves-fault-in-odlux.png "ves:fault in ODLUX")
 200
 201
 202 ### Log files and karaf console
 203
 204 #### ODL karaf.logs
 205
 206 ```
 207 docker exec -it sdnr tail -f /opt/opendaylight/data/log/karaf.log
 208 ```
 209
 210 #### karaf console access (karaf:karaf)
 211
 212 ```
 213 ssh karaf@localhost -p 8101
 214 ```
 215
 216 #### ves-collector logs
 217
 218 ```
 219 docker logs -f ves-collector
 220 ```
 221
 222 #### onap-policy apex logs
 223
 224 ```
 225 docker logs policy-apex-pdp
 226 ```
 227
 228 ### Customizing Solution
 229
 230 '.env' file contains customizing parameters
 231
 232 ### Verification Solution
 233
 234 #### Access to SDN-R ODLUX
 235
 236 ##### Login into SDN-R
 237
 238     https://sdnc-web:8453
 239
 240     User: admin // see .env file
 241
 242     Password: Kp8bJ4SXszM0WXlhak3eHlcse2gAw84vaoGGmJvUy2U
 243
 244 In case of trouble, please update the commands with your customized '.env' file.
 245
 246 ### Terminate solution
 247
 248 To stop all container please respect the following order
 249
 250 ```
 251 docker-compose -f network/docker-compose.yml down
 252 docker-compose -f smo/oam/docker-compose.yml down
 253 docker-compose -f smo/onap-policy/docker-compose.yml down
 254 docker-compose -f smo/non-rt-ric/docker-compose.yml down
 255 docker-compose -f smo/common/docker-compose.yml down
 256 ```
 257
 258 ### Cleanup
 259
 260 !!! be careful if other stopped containers are on the same system
 261 ```
 262 docker system prune -a -f
 263 ```
 264 ### Troubleshooting
 265
 266 In most cases the .env setting do not fit to the environment and need to be
 267 adjusted.
 268
 269 Please make sure that the network settings to not overlap with other networks.
 270
 271 The commands ...
 272 ```
 273 docker ps -a
 274 docker-compose ps
 275
 276 ## Prerequisites
 277 # python3, tmux, libtmux
 278 tmux new-session -n workspace -s integration
 279
 280 # within tmux session
 281 python tmux-logging.py
 282 ```
 283 ... are your friends.
 284
 285 ![tmux logging](docs/tmux-logging.png "tmux logging")