docs/deployment.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. SPDX-License-Identifier: CC-BY-4.0
   3 .. Copyright (C) 2022 highstreet technologies and others
   4
   5 Deployment
   6 ==========
   7
   8 OAM Components are deployed in different context and for different use cases.
   9 Please see the Kubernetes deployment within the `it/deb <https://gerrit.o-ran-sc.org/r/gitweb?p=it/dep>`__ repository and its description in `O-RAN-SC wiki <https://wiki.o-ran-sc.org/display/IAT/Automated+deployment+and+testing+-+using+SMO+package+and+ONAP+Python+SDK>`__.
  10
  11 The main OAM Components are:
  12
  13 - OAM-Controller from ONAP SDN-R using OpenDaylight for O1-NETCONF and OpenFronthaul-Management-NETCONF support.
  14 - VES-Collector from ONAP DCAE for processing O1-VES messages.
  15 - Message-router from ONAP DMaaP using Kafka
  16 - Identity service from Keycloak for AAA support.
  17
  18
  19 This page focus on a lightweight deployment using docker-compose on an Ubuntu system for experience with SMO OAM Components and/or development.
  20
  21
  22 Prerequisites
  23 -------------
  24
  25 The following command are used to verify your system and it installed software package.
  26 In general new version then display here should be fine.::
  27
  28    $ cat /etc/os-release | grep PRETTY_NAME
  29    PRETTY_NAME="Ubuntu 20.04.2 LTS"
  30
  31    $ docker --version
  32    Docker version 20.10.7, build 20.10.7-0ubuntu1~20.04.2
  33
  34    $ docker-compose version
  35    docker-compose version 1.29.1, build c34c88b2
  36    docker-py version: 5.0.0
  37    CPython version: 3.7.10
  38    OpenSSL version: OpenSSL 1.1.0l  10 Sep 2019
  39
  40    $ git --version
  41    git version 2.25.1
  42
  43 The communication between the components bases on domain-names. For a lightweight
  44 deployment on a single laptop or virtual-machine the /etc/hosts file should be
  45 modified as a simple DNS.
  46
  47 Please modify the /etc/hosts of your system.
  48
  49 * \<your-system>: is the hostname of the system, where the browser is started
  50
  51 * \<deployment-system-ipv4>: is the IP address of the system where the solution will be deployed
  52
  53 For development purposes <your-system> and <deployment-system> may reference the same system.::
  54
  55    $ cat /etc/hosts
  56    127.0.0.1                   localhost
  57    127.0.1.1                   <your-system>
  58    <deployment-system-ipv4>   sdnc-web <your-system>
  59    <deployment-system-ipv4>   identity <your-system>
  60
  61 Docker Enable IPv6
  62 ^^^^^^^^^^^^^^^^^^
  63
  64 The O-RAN Alliance specifications target the support of IPv6.
  65 To support IPv6 by docker the docker configuration must be modified.
  66
  67 Please see:
  68 https://docs.docker.com/config/daemon/ipv6/
  69
  70 1. Edit /etc/docker/daemon.json, set the ipv6 key to true and the fixed-cidr-v6 key to your IPv6 subnet. In this example we are setting it to 2001:db8:1::/64.
  71
  72 .. code-block:: json
  73
  74   {
  75       "dns": ["1.1.1.1"],
  76       "registry-mirrors": [
  77           "https://nexus3.o-ran-sc.org:10002",
  78           "https://nexus3.onap.org:10001"
  79       ],
  80       "log-driver": "json-file",
  81       "log-opts": {
  82           "max-size": "10m",
  83           "max-file": "3"
  84       },
  85       "ipv6": true,
  86       "fixed-cidr-v6": "2001:db8:1::/64"
  87   }
  88
  89 2. Reload the Docker configuration file.
  90
  91 .. code-block:: bash
  92
  93   $ systemctl reload docker
  94
  95 It is beneficial (but not mandatory) adding the following line add the
  96 end of your ~/.bashrc file. I will suppress warnings when python script
  97 do not verify self signed certificates for HTTPS communication.::
  98
  99    export PYTHONWARNINGS="ignore:Unverified HTTPS request"
 100
 101 Please ensure that you download and copy the required 3GPP OpenAPIs for VES-stndDefined
 102 message validation into the folder './solution/operation-and-maintenance/smo/oam/ves-collector/externalRepo'.
 103
 104 Please follow the instructions in ./solution/operation-and-maintenance/smo/oam/ves-collector/externalRepo/3gpp/rep/sa5/MnS/blob/Rel16/OpenAPI/README.md.
 105
 106 The following tree shows the successfully tested folder structure. It combines different versions of the schemas ('Rel16' and 'SA88-Rel16') using 3GPP branch names.::
 107
 108    $ tree solution/operation-and-maintenance/smo/oam/ves-collector/externalRepo/
 109    solution/operation-and-maintenance/smo/oam/ves-collector/externalRepo/
 110    ├── 3gpp
 111    │   └── rep
 112    │       └── sa5
 113    │           └── MnS
 114    │               └── blob
 115    │                   ├── Rel16
 116    │                   │   └── OpenAPI
 117    │                   │       ├── README.md
 118    │                   │       ├── TS28532_FaultMnS.yaml
 119    │                   │       ├── TS28532_FileDataReportingMnS.yaml
 120    │                   │       ├── TS28532_HeartbeatNtf.yaml
 121    │                   │       ├── TS28532_PerfMnS.yaml
 122    │                   │       ├── TS28532_ProvMnS.yaml
 123    │                   │       ├── TS28532_StreamingDataMnS.yaml
 124    │                   │       ├── TS28536_CoslaNrm.yaml
 125    │                   │       ├── TS28541_5GcNrm.yaml
 126    │                   │       ├── TS28541_NrNrm.yaml
 127    │                   │       ├── TS28541_SliceNrm.yaml
 128    │                   │       ├── TS28550_PerfMeasJobCtrlMnS.yaml
 129    │                   │       ├── TS28623_ComDefs.yaml
 130    │                   │       ├── TS28623_GenericNrm.yaml
 131    │                   │       ├── TS29512_Npcf_SMPolicyControl.yaml
 132    │                   │       ├── TS29514_Npcf_PolicyAuthorization.yaml
 133    │                   │       └── TS29571_CommonData.yaml
 134    │                   └── SA88-Rel16
 135    │                       └── OpenAPI
 136    │                           ├── 5gcNrm.yaml
 137    │                           ├── PerDataFileReportMnS.yaml
 138    │                           ├── PerMeasJobCtlMnS.yaml
 139    │                           ├── PerThresMonMnS.yaml
 140    │                           ├── PerfDataStreamingMnS.yaml
 141    │                           ├── README.md
 142    │                           ├── comDefs.yaml
 143    │                           ├── coslaNrm.yaml
 144    │                           ├── faultMnS.yaml
 145    │                           ├── genericNrm.yaml
 146    │                           ├── heartbeatNtf.yaml
 147    │                           ├── nrNrm.yaml
 148    │                           ├── provMnS.yaml
 149    │                           ├── sliceNrm.yaml
 150    │                           └── streamingDataMnS.yaml
 151
 152 Expected Folder Structure
 153 -------------------------
 154
 155 The following figure show the expected folder structure for the different
 156 docker-compose file and its configurations.::
 157
 158    ├── network
 159    │   ├── .env
 160    │   ├── config.py
 161    │   ├── docker-compose.yaml
 162    │   │
 163    │   ├── ntsim-ng-o-du
 164    │   └── ntsim-ng-o-ru
 165    └── smo
 166       ├── common
 167       │   ├── .env
 168       │   ├── docker-compose.yaml
 169       │   │
 170       │   ├── dmaap
 171       │   ├── docker
 172       │   ├── identity
 173       │   ├── kafka
 174       │   └── zookeeper
 175       └── oam
 176          ├── .env
 177          ├── docker-compose.yaml
 178          │
 179          ├── web
 180          ├── controller
 181          └── ves-collector
 182
 183 Usage
 184 -----
 185
 186 Bring Up Solution
 187 ^^^^^^^^^^^^^^^^^
 188
 189 Please check and adjust, if required the environment variables::
 190
 191    nano smo/common/.env
 192    nano smo/oam/.env
 193    nano network/.env
 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 Please note that it is necessary to configure first the identity service,
 202 before starting further docker images.
 203
 204 The several docker-compose yaml files must be started in the right order as listed below:
 205
 206 First the SMO common services must be started::
 207
 208    docker-compose -f smo/common/docker-compose.yaml up -d
 209    python smo/common/identity/config.py
 210
 211 The python script configure the users within the identity service (keycloak).
 212 A system user (%USER) is also created with administration rights. The initial password (Default4SDN!).
 213 The identity service implemented by Keycloak is configured in a way that the user must change its initial password after the first successful login.
 214
 215 In a second step the OAM specific service can be started: ::
 216
 217    docker-compose -f smo/oam/docker-compose.yaml up -d
 218
 219 Looking into the ONAP SDN-R logs will give you the startup procedure.::
 220
 221    docker logs -f sdnr
 222
 223 The startup was successful when you see the following line: ::
 224
 225    Everything OK in Certificate Installation
 226
 227
 228 If you see the login page (https://sdnc-web:8453) you are good to go and can start the (simulated) network.::
 229
 230    docker-compose -f network/docker-compose.yaml up -d
 231
 232
 233 Usually the first ves:event gets lost. Please restart the O-DU docker container(s) to send a second ves:pnfRegistration.::
 234
 235    docker-compose -f network/docker-compose.yaml restart ntsim-ng-o-du-1122
 236    python network/config.py
 237
 238
 239 The python script configures the simulated O-DU and O-RU according to O-RAN hybrid architecture.
 240
 241 O-DU - NETCONF Call HOME and NETCONF notifications
 242 O-RU - ves:pnfRegistration and ves:fault, ves:heartbeat
 243
 244 'True' indicated that the settings through SDN-R to the NETCONF server were
 245 successful.
 246
 247 SDN-R reads the fault events from DMaaP and processes them.
 248 Finally the fault events are visible in ODLUX.
 249
 250
 251 Log files and karaf console
 252 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 253
 254 OpenDaylight/Apache Karaf logs::
 255
 256    docker exec -it sdnr tail -f /opt/opendaylight/data/log/karaf.log
 257
 258 VES-collector logs::
 259
 260    docker logs -f ves-collector
 261
 262
 263 Verification of Solution
 264 ^^^^^^^^^^^^^^^^^^^^^^^^
 265
 266 On the web user interface https://sdnc-web:8453 you can login with the system user ($USER) and the default password mentioned above.
 267 You should see 4 network function connected via IPv6 and also alarm notification via NETCONF and VES.
 268
 269
 270 Terminate solution
 271 ^^^^^^^^^^^^^^^^^^
 272
 273 To stop all container please respect the following order::
 274
 275    docker-compose -f network/docker-compose.yaml down
 276    docker-compose -f smo/oam/docker-compose.yaml down
 277    docker-compose -f smo/common/docker-compose.yaml down
 278
 279 Cleanup
 280 ^^^^^^^
 281
 282 Please be very careful with the following command, if other stopped containers are on the same system::
 283
 284    docker system prune -a -f