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.
  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 │                   │       ├── README.md
 101 │                   │       ├── TS28532_FaultMnS.yaml
 102 │                   │       ├── TS28532_FileDataReportingMnS.yaml
 103 │                   │       ├── TS28532_HeartbeatNtf.yaml
 104 │                   │       ├── TS28532_PerfMnS.yaml
 105 │                   │       ├── TS28532_ProvMnS.yaml
 106 │                   │       ├── TS28532_StreamingDataMnS.yaml
 107 │                   │       ├── TS28536_CoslaNrm.yaml
 108 │                   │       ├── TS28541_5GcNrm.yaml
 109 │                   │       ├── TS28541_NrNrm.yaml
 110 │                   │       ├── TS28541_SliceNrm.yaml
 111 │                   │       ├── TS28550_PerfMeasJobCtrlMnS.yaml
 112 │                   │       ├── TS28623_ComDefs.yaml
 113 │                   │       ├── TS28623_GenericNrm.yaml
 114 │                   │       ├── TS29512_Npcf_SMPolicyControl.yaml
 115 │                   │       ├── TS29514_Npcf_PolicyAuthorization.yaml
 116 │                   │       └── TS29571_CommonData.yaml
 117 │                   └── SA88-Rel16
 118 │                       └── OpenAPI
 119 │                           ├── 5gcNrm.yaml
 120 │                           ├── PerDataFileReportMnS.yaml
 121 │                           ├── PerMeasJobCtlMnS.yaml
 122 │                           ├── PerThresMonMnS.yaml
 123 │                           ├── PerfDataStreamingMnS.yaml
 124 │                           ├── README.md
 125 │                           ├── comDefs.yaml
 126 │                           ├── coslaNrm.yaml
 127 │                           ├── faultMnS.yaml
 128 │                           ├── genericNrm.yaml
 129 │                           ├── heartbeatNtf.yaml
 130 │                           ├── nrNrm.yaml
 131 │                           ├── provMnS.yaml
 132 │                           ├── sliceNrm.yaml
 133 │                           └── streamingDataMnS.yaml
 134 ```
 135
 136 ## Expected Folder Structure
 137
 138 The following figure show the expected folder structure for the different
 139 docker-compose file and its configurations.
 140
 141 ```
 142 ├── network
 143 │   ├── .env
 144 │   ├── config.py
 145 │   ├── docker-compose.yml
 146 │   │
 147 │   ├── ntsim-ng-o-du
 148 │   └── ntsim-ng-o-ru
 149 └── smo
 150     ├── common
 151     │   ├── .env
 152     │   ├── docker-compose.yml
 153     │   │
 154     │   ├── dmaap
 155     │   ├── docker
 156     │   ├── identity
 157     │   ├── kafka
 158     │   └── zookeeper
 159     └── oam
 160         ├── .env
 161         ├── docker-compose.yml
 162         │
 163         ├── web
 164         ├── controller
 165         └── ves-collector
 166 ```
 167
 168 ## Usage
 169
 170 ### Bring Up Solution
 171
 172 #### Short story
 173
 174 The following commands should be invoked. More detailed can be found in the
 175 next chapters.
 176
 177 ```
 178 docker-compose -f smo/common/docker-compose.yml up -d
 179 # wait until the cpu load is low again
 180 python smo/common/identity/config.py
 181
 182 docker-compose -f smo/oam/docker-compose.yml up -d
 183 # wait until the cpu load is low again
 184
 185 docker-compose -f network/docker-compose.yml up -d
 186 # wait about 2min
 187 docker restart ntsim-ng-o-du-1122
 188 python network/config.py
 189 ```
 190
 191 #### Check (adjust if required) environment variables
 192
 193 ```
 194 nano smo/common/.env
 195 nano smo/oam/.env
 196 nano network/.env
 197 ```
 198
 199 The tested configuration uses the following external https ports:
 200
 201  * 8443 for the ves-collector
 202  * 8453 for web access to ODLUX (SDNC_WEB_PORT)
 203  * 8463 for the keyclock web administrator user interface.
 204
 205 #### Startup solution
 206
 207 Please note that it is necessary to configure first the identity service,
 208 before starting further docker images.
 209
 210 The several docker-compose yml files must be started in the right order as listed below:
 211
 212 ```
 213 docker-compose -f smo/common/docker-compose.yml up -d
 214 python smo/common/identity/config.py
 215 ```
 216
 217 The python script configure the users within the identity service (keycloak).
 218 A system user (%USER) is also created with administration rights.
 219
 220
 221 ```
 222 docker-compose -f smo/oam/docker-compose.yml up -d
 223 ```
 224
 225 Looking into the ONAP SDN-R logs will give you the startup procedure.
 226
 227 ```
 228 docker logs -f sdnr
 229 ```
 230
 231 The startup was successful when you see the following line:
 232
 233 ```
 234 Everything OK in Certificate Installation
 235 ```
 236
 237 If you see the login page (https://sdnc-web:8453) you are good to go and can start the (simulated) network.
 238
 239 ```
 240 docker-compose -f network/docker-compose.yml up -d
 241 ```
 242
 243 Usually the first ves:event gets lost. Please restart the O-DU docker container(s) to send a second ves:pnfRegistration.
 244
 245 ```
 246 docker-compose -f network/docker-compose.yml restart ntsim-ng-o-du-1122
 247 python network/config.py
 248 ```
 249
 250 The python script configures the simulated O-DU and O-RU according to O-RAN hybrid architecture.
 251
 252 O-DU - NETCONF Call HOME and NETCONF notifications
 253 O-RU - ves:pnfRegistration and ves:fault, ves:heartbeat
 254
 255 ![ves:pnfRegistration in ODLUX](docs/nstim-ng-connected-after-ves-pnf-registration-in-odlux.png "ves:pnfRegistration in ODLUX")
 256
 257 'True' indicated that the settings through SDN-R to the NETCONF server were
 258 successful.
 259
 260 SDN-R reads the fault events from DMaaP and processes them.
 261 Finally the fault events are visible in ODLUX.
 262
 263 ![ves:fault in ODLUX](docs/ves-fault-in-odlux.png "ves:fault in ODLUX")
 264
 265
 266 ### Log files and karaf console
 267
 268 #### ODL karaf.logs
 269
 270 ```
 271 docker exec -it sdnr tail -f /opt/opendaylight/data/log/karaf.log
 272 ```
 273
 274 #### ves-collector logs
 275
 276 ```
 277 docker logs -f ves-collector
 278 ```
 279
 280 ### Customizing Solution
 281
 282 '.env' file contains customizing parameters
 283
 284 ### Verification Solution
 285
 286 #### Access to SDN-R ODLUX
 287
 288 ##### Login into SDN-R
 289
 290     https://sdnc-web:8453
 291
 292     User: admin // see .env file
 293
 294     Password: Kp8bJ4SXszM0WXlhak3eHlcse2gAw84vaoGGmJvUy2U
 295
 296 In case of trouble, please update the commands with your customized '.env' file.
 297
 298 ### Terminate solution
 299
 300 To stop all container please respect the following order
 301
 302 ```
 303 docker-compose -f network/docker-compose.yml down
 304 docker-compose -f smo/oam/docker-compose.yml down
 305 docker-compose -f smo/common/docker-compose.yml down
 306 ```
 307
 308 ### Cleanup
 309
 310 !!! be careful if other stopped containers are on the same system
 311 ```
 312 docker system prune -a -f
 313 ```
 314 ### Troubleshooting
 315
 316 In most cases the .env setting do not fit to the environment and need to be
 317 adjusted.
 318
 319 Please make sure that the network settings to not overlap with other networks.
 320
 321 The commands ...
 322 ```
 323 docker ps -a
 324 docker-compose ps