solution/operation-and-maintenance/README.md

   1 # Service Management and Orchestration (SMO)
   2
   3 This project focus on a docker-compose deployment solution for SMO/OAM Components.
   4
   5 ## Introduction
   6
   7 With respect to OAM the SMO implements the O1-interface consumers.
   8 According to the O-RAN OAM Architecture and the O-RAN OAM Interface Specification,
   9 the SMO implements a NETCONF Client for configuration and a HTTP/REST/VES server
  10 for receiving all kind of events in VES format.
  11
  12 The setup contains an OpenDaylight based NETCONF client and an ONAP VES Collector.
  13
  14 ## SMO OAM Components
  15
  16 This docker-compose file starts a pre-configured, self-contained SDN-R solution
  17 with the following components.
  18
  19   * **Identity**
  20     ... representing an KeyCloak based identity service for centralized user
  21     management. Please note that the implementation does not support IPv6.
  22     Therefore, its own network is required called 'DMZ'.
  23     In this configuration the external https port is 8463.
  24
  25   * **SDN-R** single node instance
  26
  27     ... representing the NETCONF consumer on the Service Management and
  28     Orchestration framework (SMO) for the O1 interface based on
  29     ODL-Phosphorus.
  30     SDN-R comes with is own web-portal the external port is 8463.
  31
  32   * **VES collector**
  33
  34     ... representing the VES (REST) provider at SMO for all kind of events. In this configuration the external https port is 8443.
  35
  36   * **DMaaP**
  37     ... representing SMO DMaaP component, includes message-router
  38
  39 ## Prerequisites
  40
  41 ```
  42 $ cat /etc/os-release | grep PRETTY_NAME
  43 PRETTY_NAME="Ubuntu 20.04.2 LTS"
  44
  45 $ docker --version
  46 Docker version 20.10.7, build 20.10.7-0ubuntu1~20.04.2
  47
  48 $ docker-compose version
  49 docker-compose version 1.29.1, build c34c88b2
  50 docker-py version: 5.0.0
  51 CPython version: 3.7.10
  52 OpenSSL version: OpenSSL 1.1.0l  10 Sep 2019
  53
  54
  55 $ git --version
  56 git version 2.25.1
  57
  58 ```
  59 Please modify the /etc/hosts of your system.
  60
  61 * \<your-system>: is the hostname of the system, where the browser is started
  62
  63 * \<deployment-system-ipv4>: is the IP address of the system where the solution will be deployed
  64
  65 For development purposes <your-system> and <deployment-system> may reference the same system.
  66
  67 ```
  68 $ cat /etc/hosts
  69 127.0.0.1                      localhost
  70 127.0.1.1                      <your-system>
  71 <deployment-system-ipv4>   sdnc-web <your-system>
  72 <deployment-system-ipv4>   identity <your-system>
  73 ```
  74
  75 It is beneficial (but not mandatory) adding the following line add the
  76 end of your ~/.bashrc file. I will suppress warnings when python script
  77 do not verify self signed certificates for HTTPS communication.
  78
  79 ```
  80 export PYTHONWARNINGS="ignore:Unverified HTTPS request"
  81 ```
  82
  83 Please ensure that you download and copy the required 3GPP OpenAPIs for VES-stndDefined
  84 message validation into the folder './solution/operation-and-maintenance/smo/oam/ves-collector/externalRepo'.
  85
  86 Please follow the instructions in ./solution/operation-and-maintenance/smo/oam/ves-collector/externalRepo/3gpp/rep/sa5/MnS/blob/Rel16/OpenAPI/README.md.
  87
  88 The following tree shows the successfully tested folder structure. It combines different versions of the schemas ('Rel16' and 'SA88-Rel16') using 3GPP branch names.
  89
  90 ```
  91 $ tree solution/operation-and-maintenance/smo/oam/ves-collector/externalRepo/
  92 solution/operation-and-maintenance/smo/oam/ves-collector/externalRepo/
  93 ├── 3gpp
  94 │   └── rep
  95 │       └── sa5
  96 │           └── MnS
  97 │               └── blob
  98 │                   ├── Rel16
  99 │                   │   └── OpenAPI
 100 │                   │       ├── 5gcNrm.yaml
 101 │                   │       ├── PerfMeasJobCtrlMnS.yaml
 102 │                   │       ├── README.md
 103 │                   │       ├── comDefs.yaml
 104 │                   │       ├── coslaNrm.yaml
 105 │                   │       ├── faultMnS.yaml
 106 │                   │       ├── fileDataReportingMnS.yaml
 107 │                   │       ├── genericNrm.yaml
 108 │                   │       ├── heartbeatNtf.yaml
 109 │                   │       ├── nrNrm.yaml
 110 │                   │       ├── perfMnS.yaml
 111 │                   │       ├── provMnS.yaml
 112 │                   │       ├── sliceNrm.yaml
 113 │                   │       └── streamingDataMnS.yaml
 114 │                   └── SA88-Rel16
 115 │                       └── OpenAPI
 116 │                           ├── 5gcNrm.yaml
 117 │                           ├── PerDataFileReportMnS.yaml
 118 │                           ├── PerMeasJobCtlMnS.yaml
 119 │                           ├── PerThresMonMnS.yaml
 120 │                           ├── PerfDataStreamingMnS.yaml
 121 │                           ├── README.md
 122 │                           ├── comDefs.yaml
 123 │                           ├── coslaNrm.yaml
 124 │                           ├── faultMnS.yaml
 125 │                           ├── genericNrm.yaml
 126 │                           ├── heartbeatNtf.yaml
 127 │                           ├── nrNrm.yaml
 128 │                           ├── provMnS.yaml
 129 │                           ├── sliceNrm.yaml
 130 │                           └── streamingDataMnS.yaml
 131 ```
 132
 133 ## Expected Folder Structure
 134
 135 The following figure show the expected folder structure for the different
 136 docker-compose file and its configurations.
 137
 138 ```
 139 ├── network
 140 │   ├── .env
 141 │   ├── config.py
 142 │   ├── docker-compose.yml
 143 │   │
 144 │   ├── ntsim-ng-o-du
 145 │   └── ntsim-ng-o-ru
 146 └── smo
 147     ├── common
 148     │   ├── .env
 149     │   ├── docker-compose.yml
 150     │   │
 151     │   ├── dmaap
 152     │   ├── docker
 153     │   ├── identity
 154     │   ├── kafka
 155     │   └── zookeeper
 156     └── oam
 157         ├── .env
 158         ├── docker-compose.yml
 159         │
 160         ├── web
 161         ├── controller
 162         └── ves-collector
 163 ```
 164
 165 ## Usage
 166
 167 ### Bring Up Solution
 168
 169 #### Short story
 170
 171 The following commands should be invoked. More detailed can be found in the
 172 next chapters.
 173
 174 ```
 175 docker-compose -f smo/common/docker-compose.yml up -d
 176 # wait until the cpu load is low again
 177 python smo/common/identity/config.py
 178
 179 docker-compose -f smo/oam/docker-compose.yml up -d
 180 # wait until the cpu load is low again
 181
 182 docker-compose -f network/docker-compose.yml up -d
 183 # wait about 2min
 184 docker restart ntsim-ng-o-du-1122
 185 python network/config.py
 186 ```
 187
 188 #### Check (adjust if required) environment variables
 189
 190 ```
 191 nano smo/.env
 192 nano network/.env
 193 ```
 194
 195 The tested configuration uses the following external https ports:
 196
 197  * 8443 for the ves-collector
 198  * 8453 for web access to ODLUX (SDNC_WEB_PORT)
 199  * 8463 for the keyclock web administrator user interface.
 200
 201 #### Startup solution
 202
 203 Please note that it is necessary to configure first the identity service,
 204 before starting further docker images.
 205
 206 The several docker-compose yml files must be started in the right order as listed below:
 207
 208 ```
 209 docker-compose -f smo/common/docker-compose.yml up -d
 210 python smo/identity/config.py
 211 ```
 212
 213 The python script configure the users within the identity service (keycloak).
 214 A system user (%USER) is also created with administration rights.
 215
 216
 217 ```
 218 docker-compose -f smo/oam/docker-compose.yml up -d
 219 python smo/identity/config.py
 220 ```
 221
 222 Please wait about 2min until all the service are up and running.
 223 If you see the login page (https://sdnc-web:8453) you are good to go and can start the (simulated) network.
 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 ![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 #### ves-collector logs
 261
 262 ```
 263 docker logs -f ves-collector
 264 ```
 265
 266 ### Customizing Solution
 267
 268 '.env' file contains customizing parameters
 269
 270 ### Verification Solution
 271
 272 #### Access to SDN-R ODLUX
 273
 274 ##### Login into SDN-R
 275
 276     https://sdnc-web:8453
 277
 278     User: admin // see .env file
 279
 280     Password: Kp8bJ4SXszM0WXlhak3eHlcse2gAw84vaoGGmJvUy2U
 281
 282 In case of trouble, please update the commands with your customized '.env' file.
 283
 284 ### Terminate solution
 285
 286 To stop all container please respect the following order
 287
 288 ```
 289 docker-compose -f network/docker-compose.yml down
 290 docker-compose -f smo/oam/docker-compose.yml down
 291 docker-compose -f smo/common/docker-compose.yml down
 292 ```
 293
 294 ### Cleanup
 295
 296 !!! be careful if other stopped containers are on the same system
 297 ```
 298 docker system prune -a -f
 299 ```
 300 ### Troubleshooting
 301
 302 In most cases the .env setting do not fit to the environment and need to be
 303 adjusted.
 304
 305 Please make sure that the network settings to not overlap with other networks.
 306
 307 The commands ...
 308 ```
 309 docker ps -a
 310 docker-compose ps