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 docker-compose -f smo/apps/docker-compose.yml up -d
 192
 193 # wait until the cpu load is low again
 194
 195 docker-compose -f network/docker-compose.yml up -d
 196 # wait about 2min
 197 docker restart ntsim-ng-o-du-1122
 198 python network/config.py
 199 ```
 200
 201 #### Check (adjust if required) environment variables
 202
 203 ```
 204 nano smo/common/.env
 205 nano smo/oam/.env
 206 nano network/.env
 207 ```
 208
 209 The tested configuration uses the following external https ports:
 210
 211  * 8443 for the ves-collector
 212  * 8453 for web access to ODLUX (SDNC_WEB_PORT)
 213  * 8463 for the keyclock web administrator user interface.
 214
 215 #### Startup solution
 216
 217 Please note that it is necessary to configure first the identity service,
 218 before starting further docker images.
 219
 220 The several docker-compose yml files must be started in the right order as listed below:
 221
 222 ```
 223 docker-compose -f smo/common/docker-compose.yml up -d
 224 python smo/common/identity/config.py
 225 ```
 226
 227 The python script configure the users within the identity service (keycloak).
 228 A system user (%USER) is also created with administration rights.
 229
 230
 231 ```
 232 docker-compose -f smo/oam/docker-compose.yml up -d
 233 ```
 234
 235 Looking into the ONAP SDN-R logs will give you the startup procedure.
 236
 237 ```
 238 docker logs -f sdnr
 239 ```
 240
 241 The startup was successful when you see the following line:
 242
 243 ```
 244 Everything OK in Certificate Installation
 245 ```
 246
 247 If you see the login page (https://sdnc-web:8453) you are good to go and can start the (simulated) network.
 248
 249 ```
 250 docker-compose -f network/docker-compose.yml up -d
 251 ```
 252
 253 Usually the first ves:event gets lost. Please restart the O-DU docker container(s) to send a second ves:pnfRegistration.
 254
 255 ```
 256 docker-compose -f network/docker-compose.yml restart ntsim-ng-o-du-1122
 257 python network/config.py
 258 ```
 259
 260 The python script configures the simulated O-DU and O-RU according to O-RAN hybrid architecture.
 261
 262 O-DU - NETCONF Call HOME and NETCONF notifications
 263 O-RU - ves:pnfRegistration and ves:fault, ves:heartbeat
 264
 265 ![ves:pnfRegistration in ODLUX](docs/nstim-ng-connected-after-ves-pnf-registration-in-odlux.png "ves:pnfRegistration in ODLUX")
 266
 267 'True' indicated that the settings through SDN-R to the NETCONF server were
 268 successful.
 269
 270 SDN-R reads the fault events from DMaaP and processes them.
 271 Finally the fault events are visible in ODLUX.
 272
 273 ![ves:fault in ODLUX](docs/ves-fault-in-odlux.png "ves:fault in ODLUX")
 274
 275
 276 ### Log files and karaf console
 277
 278 #### ODL karaf.logs
 279
 280 ```
 281 docker exec -it sdnr tail -f /opt/opendaylight/data/log/karaf.log
 282 ```
 283
 284 #### ves-collector logs
 285
 286 ```
 287 docker logs -f ves-collector
 288 ```
 289
 290 ### Customizing Solution
 291
 292 '.env' file contains customizing parameters
 293
 294 ### Verification Solution
 295
 296 #### Access to SDN-R ODLUX
 297
 298 ##### Login into SDN-R
 299
 300     https://sdnc-web:8453
 301
 302     User: admin // see .env file
 303
 304     Password: Kp8bJ4SXszM0WXlhak3eHlcse2gAw84vaoGGmJvUy2U
 305
 306 In case of trouble, please update the commands with your customized '.env' file.
 307
 308 ### Terminate solution
 309
 310 To stop all container please respect the following order
 311
 312 ```
 313 docker-compose -f network/docker-compose.yml down
 314 docker-compose -f smo/oam/docker-compose.yml down
 315 docker-compose -f smo/common/docker-compose.yml down
 316 ```
 317
 318 ### Cleanup
 319
 320 !!! be careful if other stopped containers are on the same system
 321 ```
 322 docker system prune -a -f
 323 ```
 324 ### Troubleshooting
 325
 326 In most cases the .env setting do not fit to the environment and need to be
 327 adjusted.
 328
 329 Please make sure that the network settings to not overlap with other networks.
 330
 331 The commands ...
 332 ```
 333 docker ps -a
 334 docker-compose ps