solution/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   * **Controller** 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.
  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   * **Messages**
  37     ... representing SMO MessageRouter component, includes message-router
  38
  39 ## Prerequisites
  40
  41 ```
  42 $ cat /etc/os-release | grep PRETTY_NAME
  43 PRETTY_NAME="Ubuntu 22.04.1 LTS"
  44
  45 $ docker --version
  46 Docker version 20.10.12, build 20.10.12-0ubuntu4
  47
  48 $ docker-compose version
  49 docker-compose version 1.29.2, build unknown
  50 docker-py version: <module 'docker.version' from '/usr/local/lib/python3.10/dist-packages/docker/version.py'>
  51 CPython version: 3.10.6
  52 OpenSSL version: OpenSSL 3.0.2 15 Mar 2022
  53
  54
  55 $ git --version
  56 git version 2.34.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
  72 # SMO OAM development system
  73 <deployment-system-ipv4>                   smo.o-ran-sc.org
  74 <deployment-system-ipv4>           gateway.smo.o-ran-sc.org
  75 <deployment-system-ipv4>          identity.smo.o-ran-sc.org
  76 <deployment-system-ipv4>          messages.smo.o-ran-sc.org
  77 <deployment-system-ipv4> ves-collector.oam.smo.o-ran-sc.org
  78 <deployment-system-ipv4>         odlux.oam.smo.o-ran-sc.org
  79 <deployment-system-ipv4>    controller.oam.smo.o-ran-sc.org
  80
  81 ```
  82
  83 It is beneficial (but not mandatory) adding the following line add the
  84 end of your ~/.bashrc file. I will suppress warnings when python script
  85 do not verify self signed certificates for HTTPS communication.
  86
  87 ```
  88 export PYTHONWARNINGS="ignore:Unverified HTTPS request"
  89 ```
  90
  91 Please ensure that you download and copy the required 3GPP OpenAPIs for VES-stndDefined
  92 message validation into the folder './solution/operation-and-maintenance/smo/oam/ves-collector/externalRepo'.
  93
  94 Please follow the instructions in ./solution/operation-and-maintenance/smo/oam/ves-collector/externalRepo/3gpp/rep/sa5/MnS/blob/Rel16/OpenAPI/README.md.
  95
  96 The following tree shows the successfully tested folder structure. It combines different versions of the schemas ('Rel16' and 'SA88-Rel16') using 3GPP branch names.
  97
  98 ```
  99 $ tree solution/operation-and-maintenance/smo/oam/ves-collector/externalRepo/
 100 solution/operation-and-maintenance/smo/oam/ves-collector/externalRepo/
 101 ├── 3gpp
 102 │   └── rep
 103 │       └── sa5
 104 │           └── MnS
 105 │               └── blob
 106 │                   ├── Rel16
 107 │                   │   └── OpenAPI
 108 │                   │       ├── README.md
 109 │                   │       ├── TS28532_FaultMnS.yaml
 110 │                   │       ├── TS28532_FileDataReportingMnS.yaml
 111 │                   │       ├── TS28532_HeartbeatNtf.yaml
 112 │                   │       ├── TS28532_PerfMnS.yaml
 113 │                   │       ├── TS28532_ProvMnS.yaml
 114 │                   │       ├── TS28532_StreamingDataMnS.yaml
 115 │                   │       ├── TS28536_CoslaNrm.yaml
 116 │                   │       ├── TS28541_5GcNrm.yaml
 117 │                   │       ├── TS28541_NrNrm.yaml
 118 │                   │       ├── TS28541_SliceNrm.yaml
 119 │                   │       ├── TS28550_PerfMeasJobCtrlMnS.yaml
 120 │                   │       ├── TS28623_ComDefs.yaml
 121 │                   │       ├── TS28623_GenericNrm.yaml
 122 │                   │       ├── TS29512_Npcf_SMPolicyControl.yaml
 123 │                   │       ├── TS29514_Npcf_PolicyAuthorization.yaml
 124 │                   │       └── TS29571_CommonData.yaml
 125 │                   └── SA88-Rel16
 126 │                       └── OpenAPI
 127 │                           ├── 5gcNrm.yaml
 128 │                           ├── PerDataFileReportMnS.yaml
 129 │                           ├── PerMeasJobCtlMnS.yaml
 130 │                           ├── PerThresMonMnS.yaml
 131 │                           ├── PerfDataStreamingMnS.yaml
 132 │                           ├── README.md
 133 │                           ├── comDefs.yaml
 134 │                           ├── coslaNrm.yaml
 135 │                           ├── faultMnS.yaml
 136 │                           ├── genericNrm.yaml
 137 │                           ├── heartbeatNtf.yaml
 138 │                           ├── nrNrm.yaml
 139 │                           ├── provMnS.yaml
 140 │                           ├── sliceNrm.yaml
 141 │                           └── streamingDataMnS.yaml
 142 ```
 143
 144 ## Expected Folder Structure
 145
 146 The following figure show the expected folder structure for the different
 147 docker-compose file and its configurations.
 148
 149 ```
 150 ├── network
 151 │   ├── .env
 152 │   ├── config.py
 153 │   ├── docker-compose.yml
 154 │   │
 155 │   ├── ntsim-ng-o-du
 156 │   └── ntsim-ng-o-ru
 157 └── smo
 158     ├── common
 159     │   ├── .env
 160     │   ├── docker-compose.yml
 161     │   │
 162     │   ├── messages
 163     │   ├── docker
 164     │   ├── identity
 165     │   ├── kafka
 166     │   └── zookeeper
 167     └── oam
 168         ├── .env
 169         ├── docker-compose.yml
 170         │
 171         ├── odlux
 172         ├── controller
 173         └── ves-collector
 174 ```
 175
 176 ## Usage
 177
 178 ### Bring Up Solution
 179
 180 #### Short story
 181
 182 The following commands should be invoked. More detailed can be found in the
 183 next chapters.
 184
 185 ```
 186 docker-compose -f smo/common/docker-compose.yml up -d
 187 # wait until the cpu load is low again
 188 python smo/common/identity/config.py
 189
 190 docker-compose -f smo/oam/docker-compose.yml up -d
 191 # wait until the cpu load is low again
 192
 193 docker-compose -f network/docker-compose.yml up -d
 194 # wait about 2min
 195 docker restart ntsim-ng-o-du-1122
 196 python network/config.py
 197 ```
 198
 199 #### Check (adjust if required) environment variables
 200
 201 ```
 202 nano smo/common/.env
 203 nano smo/oam/.env
 204 nano network/.env
 205 ```
 206
 207 The tested configuration uses the following external https ports:
 208
 209  * 8443 for the ves-collector
 210  * 8453 for web access to ODLUX (SDNC_WEB_PORT)
 211  * 8463 for the keyclock web administrator user interface.
 212
 213 #### Startup solution
 214
 215 Please note that it is necessary to configure first the identity service,
 216 before starting further docker images.
 217
 218 The several docker-compose yml files must be started in the right order as listed below:
 219
 220 ```
 221 docker-compose -f smo/common/docker-compose.yml up -d
 222 python smo/common/identity/config.py
 223 ```
 224
 225 The python script configure the users within the identity service (keycloak).
 226 A system user (%USER) is also created with administration rights.
 227
 228
 229 ```
 230 docker-compose -f smo/oam/docker-compose.yml up -d
 231 ```
 232
 233 Looking into the ONAP SDN-R logs will give you the startup procedure.
 234
 235 ```
 236 docker logs -f sdnr
 237 ```
 238
 239 The startup was successful when you see the following line:
 240
 241 ```
 242 Everything OK in Certificate Installation
 243 ```
 244
 245 If you see the login page (https://sdnc-web:8453) you are good to go and can start the (simulated) network.
 246
 247 ```
 248 docker-compose -f network/docker-compose.yml up -d
 249 ```
 250
 251 Usually the first ves:event gets lost. Please restart the O-DU docker container(s) to send a second ves:pnfRegistration.
 252
 253 ```
 254 docker-compose -f network/docker-compose.yml restart ntsim-ng-o-du-1122
 255 python network/config.py
 256 ```
 257
 258 The python script configures the simulated O-DU and O-RU according to O-RAN hybrid architecture.
 259
 260 O-DU - NETCONF Call HOME and NETCONF notifications
 261 O-RU - ves:pnfRegistration and ves:fault, ves:heartbeat
 262
 263 ![ves:pnfRegistration in ODLUX](docs/nstim-ng-connected-after-ves-pnf-registration-in-odlux.png "ves:pnfRegistration in ODLUX")
 264
 265 'True' indicated that the settings through SDN-R to the NETCONF server were
 266 successful.
 267
 268 SDN-R reads the fault events from DMaaP and processes them.
 269 Finally the fault events are visible in ODLUX.
 270
 271 ![ves:fault in ODLUX](docs/ves-fault-in-odlux.png "ves:fault in ODLUX")
 272
 273
 274 ### Log files and karaf console
 275
 276 #### ODL karaf.logs
 277
 278 ```
 279 docker exec -it sdnr tail -f /opt/opendaylight/data/log/karaf.log
 280 ```
 281
 282 #### ves-collector logs
 283
 284 ```
 285 docker logs -f ves-collector
 286 ```
 287
 288 ### Customizing Solution
 289
 290 '.env' file contains customizing parameters
 291
 292 ### Verification Solution
 293
 294 #### Access to SDN-R ODLUX
 295
 296 ##### Login into SDN-R
 297
 298     https://sdnc-web:8453
 299
 300     User: admin // see .env file
 301
 302     Password: Kp8bJ4SXszM0WXlhak3eHlcse2gAw84vaoGGmJvUy2U
 303
 304 In case of trouble, please update the commands with your customized '.env' file.
 305
 306 ### Terminate solution
 307
 308 To stop all container please respect the following order
 309
 310 ```
 311 docker-compose -f network/docker-compose.yml down
 312 docker-compose -f smo/oam/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