From: demx8as6 Date: Sat, 17 Sep 2022 13:09:37 +0000 (+0200) Subject: Describe the usage of this docker-compose X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=commitdiff_plain;h=812f32ca15334783893bf2654ce8e615d717f74a;p=oam.git Describe the usage of this docker-compose - add link to localhost to ignored links IssueID: OAM-284 Change-Id: If40e108c99a5e18d106c72974bb44fc0b42fbf12 Signed-off-by: demx8as6 --- diff --git a/docs/conf.py b/docs/conf.py index 771ac9b..48b0c30 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -2,5 +2,6 @@ from docs_conf.conf import * linkcheck_ignore = [ 'http://localhost.*', 'http://127.0.0.1.*', - 'https://gerrit.o-ran-sc.org.*' + 'https://gerrit.o-ran-sc.org.*', + 'https://sdnc-web:8453' ] \ No newline at end of file diff --git a/docs/deployment.rst b/docs/deployment.rst new file mode 100644 index 0000000..58043a9 --- /dev/null +++ b/docs/deployment.rst @@ -0,0 +1,284 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. Copyright (C) 2022 highstreet technologies and others + +Deployment +========== + +OAM Components are deployed in different context and for different use cases. +Please see the Kubernetes deployment within the `it/deb `__ repository and its description in `O-RAN-SC wiki `__. + +The main OAM Components are: + +- OAM-Controller from ONAP SDN-R using OpenDaylight for O1-NETCONF and OpenFronthaul-Management-NETCONF support. +- VES-Collector from ONAP DCAE for processing O1-VES messages. +- Message-router from ONAP DMaaP using Kafka +- Identity service from Keycloak for AAA support. + + +This page focus on a lightweight deployment using docker-compose on an Ubuntu system for experience with SMO OAM Components and/or development. + + +Prerequisites +------------- + +The following command are used to verify your system and it installed software package. +In general new version then display here should be fine.:: + + $ cat /etc/os-release | grep PRETTY_NAME + PRETTY_NAME="Ubuntu 20.04.2 LTS" + + $ docker --version + Docker version 20.10.7, build 20.10.7-0ubuntu1~20.04.2 + + $ docker-compose version + docker-compose version 1.29.1, build c34c88b2 + docker-py version: 5.0.0 + CPython version: 3.7.10 + OpenSSL version: OpenSSL 1.1.0l 10 Sep 2019 + + $ git --version + git version 2.25.1 + +The communication between the components bases on domain-names. For a lightweight +deployment on a single laptop or virtual-machine the /etc/hosts file should be +modified as a simple DNS. + +Please modify the /etc/hosts of your system. + +* \: is the hostname of the system, where the browser is started + +* \: is the IP address of the system where the solution will be deployed + +For development purposes and may reference the same system.:: + + $ cat /etc/hosts + 127.0.0.1 localhost + 127.0.1.1 + sdnc-web + identity + +Docker Enable IPv6 +^^^^^^^^^^^^^^^^^^ + +The O-RAN Alliance specifications target the support of IPv6. +To support IPv6 by docker the docker configuration must be modified. + +Please see: +https://docs.docker.com/config/daemon/ipv6/ + +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. + +.. code-block:: json + + { + "dns": ["1.1.1.1"], + "registry-mirrors": [ + "https://nexus3.o-ran-sc.org:10002", + "https://nexus3.onap.org:10001" + ], + "log-driver": "json-file", + "log-opts": { + "max-size": "10m", + "max-file": "3" + }, + "ipv6": true, + "fixed-cidr-v6": "2001:db8:1::/64" + } + +2. Reload the Docker configuration file. + +.. code-block:: bash + + $ systemctl reload docker + +It is beneficial (but not mandatory) adding the following line add the +end of your ~/.bashrc file. I will suppress warnings when python script +do not verify self signed certificates for HTTPS communication.:: + + export PYTHONWARNINGS="ignore:Unverified HTTPS request" + +Please ensure that you download and copy the required 3GPP OpenAPIs for VES-stndDefined +message validation into the folder './solution/operation-and-maintenance/smo/oam/ves-collector/externalRepo'. + +Please follow the instructions in ./solution/operation-and-maintenance/smo/oam/ves-collector/externalRepo/3gpp/rep/sa5/MnS/blob/Rel16/OpenAPI/README.md. + +The following tree shows the successfully tested folder structure. It combines different versions of the schemas ('Rel16' and 'SA88-Rel16') using 3GPP branch names.:: + + $ tree solution/operation-and-maintenance/smo/oam/ves-collector/externalRepo/ + solution/operation-and-maintenance/smo/oam/ves-collector/externalRepo/ + ├── 3gpp + │ └── rep + │ └── sa5 + │ └── MnS + │ └── blob + │ ├── Rel16 + │ │ └── OpenAPI + │ │ ├── README.md + │ │ ├── TS28532_FaultMnS.yaml + │ │ ├── TS28532_FileDataReportingMnS.yaml + │ │ ├── TS28532_HeartbeatNtf.yaml + │ │ ├── TS28532_PerfMnS.yaml + │ │ ├── TS28532_ProvMnS.yaml + │ │ ├── TS28532_StreamingDataMnS.yaml + │ │ ├── TS28536_CoslaNrm.yaml + │ │ ├── TS28541_5GcNrm.yaml + │ │ ├── TS28541_NrNrm.yaml + │ │ ├── TS28541_SliceNrm.yaml + │ │ ├── TS28550_PerfMeasJobCtrlMnS.yaml + │ │ ├── TS28623_ComDefs.yaml + │ │ ├── TS28623_GenericNrm.yaml + │ │ ├── TS29512_Npcf_SMPolicyControl.yaml + │ │ ├── TS29514_Npcf_PolicyAuthorization.yaml + │ │ └── TS29571_CommonData.yaml + │ └── SA88-Rel16 + │ └── OpenAPI + │ ├── 5gcNrm.yaml + │ ├── PerDataFileReportMnS.yaml + │ ├── PerMeasJobCtlMnS.yaml + │ ├── PerThresMonMnS.yaml + │ ├── PerfDataStreamingMnS.yaml + │ ├── README.md + │ ├── comDefs.yaml + │ ├── coslaNrm.yaml + │ ├── faultMnS.yaml + │ ├── genericNrm.yaml + │ ├── heartbeatNtf.yaml + │ ├── nrNrm.yaml + │ ├── provMnS.yaml + │ ├── sliceNrm.yaml + │ └── streamingDataMnS.yaml + +Expected Folder Structure +------------------------- + +The following figure show the expected folder structure for the different +docker-compose file and its configurations.:: + + ├── network + │ ├── .env + │ ├── config.py + │ ├── docker-compose.yml + │ │ + │ ├── ntsim-ng-o-du + │ └── ntsim-ng-o-ru + └── smo + ├── common + │ ├── .env + │ ├── docker-compose.yml + │ │ + │ ├── dmaap + │ ├── docker + │ ├── identity + │ ├── kafka + │ └── zookeeper + └── oam + ├── .env + ├── docker-compose.yml + │ + ├── web + ├── controller + └── ves-collector + +Usage +----- + +Bring Up Solution +^^^^^^^^^^^^^^^^^ + +Please check and adjust, if required the environment variables:: + + nano smo/common/.env + nano smo/oam/.env + nano network/.env + +The tested configuration uses the following external https ports: + +* 8443 for the ves-collector +* 8453 for web access to ODLUX (SDNC_WEB_PORT) +* 8463 for the keyclock web administrator user interface. + +Please note that it is necessary to configure first the identity service, +before starting further docker images. + +The several docker-compose yml files must be started in the right order as listed below: + +First the SMO common services must be started:: + + docker-compose -f smo/common/docker-compose.yml up -d + python smo/identity/config.py + +The python script configure the users within the identity service (keycloak). +A system user (%USER) is also created with administration rights. The initial password (Default4SDN!). +The identity service implemented by Keycloak is configured in a way that the user must change its initial password after the first successful login. + +In a second step the OAM specific service can be started: :: + + docker-compose -f smo/oam/docker-compose.yml up -d + +Looking into the ONAP SDN-R logs will give you the startup procedure.:: + + docker logs -f sdnr + +The startup was successful when you see the following line: :: + + Everything OK in Certificate Installation + + +If you see the login page (https://sdnc-web:8453) you are good to go and can start the (simulated) network.:: + + docker-compose -f network/docker-compose.yml up -d + + +Usually the first ves:event gets lost. Please restart the O-DU docker container(s) to send a second ves:pnfRegistration.:: + + docker-compose -f network/docker-compose.yml restart ntsim-ng-o-du-1122 + python network/config.py + + +The python script configures the simulated O-DU and O-RU according to O-RAN hybrid architecture. + +O-DU - NETCONF Call HOME and NETCONF notifications +O-RU - ves:pnfRegistration and ves:fault, ves:heartbeat + +'True' indicated that the settings through SDN-R to the NETCONF server were +successful. + +SDN-R reads the fault events from DMaaP and processes them. +Finally the fault events are visible in ODLUX. + + +Log files and karaf console +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +OpenDaylight/Apache Karaf logs:: + + docker exec -it sdnr tail -f /opt/opendaylight/data/log/karaf.log + +VES-collector logs:: + + docker logs -f ves-collector + + +Verification of Solution +^^^^^^^^^^^^^^^^^^^^^^^^ + +On the web user interface https://sdnc-web:8453 you can login with the system user ($USER) and the default password mentioned above. +You should see 4 network function connected via IPv6 and also alarm notification via NETCONF and VES. + + +Terminate solution +^^^^^^^^^^^^^^^^^^ + +To stop all container please respect the following order:: + + docker-compose -f network/docker-compose.yml down + docker-compose -f smo/oam/docker-compose.yml down + docker-compose -f smo/common/docker-compose.yml down + +Cleanup +^^^^^^^ + +Please be very careful with the following command, if other stopped containers are on the same system:: + + docker system prune -a -f diff --git a/docs/docker_enable_ipv6.rst b/docs/docker_enable_ipv6.rst deleted file mode 100644 index 34ca7be..0000000 --- a/docs/docker_enable_ipv6.rst +++ /dev/null @@ -1,42 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. Copyright (C) 2020 highstreet technologies and others - -Docker Enable IPv6 -================== - -The O-RAN Alliance specifications target the support of IPv6. -To support IPv6 by docker the docker configuration must be modified. - -Please see: -https://docs.docker.com/config/daemon/ipv6/ - -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. - -.. code-block:: json - :linenos: - :emphasize-lines: 12,13 - - { - "dns": ["1.1.1.1"], - "registry-mirrors": [ - "https://nexus3.o-ran-sc.org:10002", - "https://nexus3.onap.org:10001" - ], - "log-driver": "json-file", - "log-opts": { - "max-size": "10m", - "max-file": "3" - }, - "ipv6": true, - "fixed-cidr-v6": "2001:db8:1::/64" - } - -2. Reload the Docker configuration file. - -.. code-block:: bash - :linenos: - - $ systemctl reload docker - - diff --git a/docs/installation.rst b/docs/installation.rst deleted file mode 100644 index 94f5fab..0000000 --- a/docs/installation.rst +++ /dev/null @@ -1,19 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. Copyright (C) 2020 highstreet technologies and others - -Installation -============ - -Below is the installation procedure for SDN-R Images and Configuration parameters - - -.. toctree:: - :maxdepth: 1 - - sdnr_WT_Service_Configuration_parameters - docker_enable_ipv6 - sdnr_Docker_Image_configuration - - - diff --git a/docs/sdnr_Docker_Image_configuration.rst b/docs/sdnr_Docker_Image_configuration.rst deleted file mode 100644 index fe0479b..0000000 --- a/docs/sdnr_Docker_Image_configuration.rst +++ /dev/null @@ -1,59 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. Copyright (C) 2020 highstreet technologies and others - -.. contents:: - :depth: 3 -.. - -SDN-R Docker Image configuration -================================ - -Introduction -~~~~~~~~~~~~ - -ONAP SDN-R is running in a docker container using ONAP/SDN-C image -"onap/sdnc". - -The container is available as Alpine and Ubuntu version. The description -uses examples for the Alpine version. - -The alpine based sdnc docker images are stored in \ `ONAP Nexus sdnc -image `__. - -The docker image contains a OpenDaylight distribution in a standard -configuration and ONAP/SDN-R specific microservices. - -The Root location of ODL Karaf directory structure -is \ *ODL\_HOME=/opt/opendaylight.* - -During container provisioning the installation of the feature is done, -according to the provided configuration setting. - -The docker image configuration is done by - -- Specific Environment variables settings - -- Files that are provided - -Container startup parameters -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The SDN-R specific configurations are provided during container start.  - -Different SDN-R services are using different parameter to be installed. - -+----------------+-------------------+-----------------------------------------------------------------------------------------------------+ -| Parameter | Content | Description | -+================+===================+=====================================================================================================+ -| SDNRWT | true or **false** | Set true to activate sdnr wt feature set. Set this during container start. | -+ + +-----------------------------------------------------------------------------------------------------+ -| | | Devicemanager configuration is provided via *$ODL_HOME/etc/devicemanager.properties* | -+ + +-----------------------------------------------------------------------------------------------------+ -| | | See  :doc:`SDN-R WT Service Configuration parameters <../sdnr_WT_Service_Configuration_parameters>` | -+----------------+-------------------+-----------------------------------------------------------------------------------------------------+ -| SDNRNORTHBOUND | true or **false** | Set true to activate sdnr oofpci service. | -+----------------+-------------------+-----------------------------------------------------------------------------------------------------+ - - - diff --git a/docs/sdnr_WT_Service_Configuration_parameters.rst b/docs/sdnr_WT_Service_Configuration_parameters.rst deleted file mode 100644 index ceb5b11..0000000 --- a/docs/sdnr_WT_Service_Configuration_parameters.rst +++ /dev/null @@ -1,121 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. Copyright (C) 2020 highstreet technologies and others - -.. contents:: - :depth: 3 -.. - -SDN-R WT Service Configuration parameters -========================================= - -ODL is operated as a cluster. The configuration settings must be the -same for each cluster node. - -- `Sections <#SDN-RWTServiceConfigurationparameters-S>`__ - - - `toggleAlarmFilter <#SDN-RWTServiceConfigurationparameters-t>`__ - - `devicemonitor <#SDN-RWTServiceConfigurationparameters-d>`__ - -Backgrounds regarding the container inter structure is described -in \ `SDN-R Docker Image configuration `__. - -The configuration information of sdnr wireless transport parameters are -in a single file. - -For different devicemanager services, like DeviceMonitor there  are -individual sections in the configuration file available. - -Configuration file location:  -***$ODL\_HOME/etc/devicemanager.properties*** - -If SDN-R WT is starting - -- and the file exists, the configuration is used.  -- if it does not exist it will be created with the default parameters. - -Below an example of the content. - -- Example -- - .. code-block:: javascript - :linenos: - - [toggleAlarmFilter] - taEnabled=true - taDelay=3000 - - [es] - esCluster=sdnr - esArchiveCheckIntervalSeconds=0 - esArchiveLifetimeSeconds=2592000 - - [dcae] - dcaeUrl=off - dcaeUserCredentials=admin:admin - dcaeHeartbeatPeriodSeconds=120 - - [aai] - aaiUrl=off - aaiUserCredentials= - aaiHeaders=["X-TransactionId: 9999"] - aaiDeleteOnMountpointRemove=false - aaiTrustAllCerts=false - aaiPropertiesFile= - aaiApiVersion=aai/v13 - aaiApplicationId=SDNR - aaiClientConnectionTimeout=30000 - aaiPcks12ClientCertFile= - aaiPcks12ClientCertPassphrase= - - [pm] - pmEnabled=true - pmCluster=sdnr - - [devicemonitor] - SeverityconnectionLossOAM=Major - SeverityconnectionLossMediator=Major - SeverityconnectionLossNeOAM=Major - -Sections --------- - -toggleAlarmFilter -~~~~~~~~~~~~~~~~~ - -Configure toggle alarm filter. - -taEnabled=true taDelay=3000 - -+-----------------+---------------+---------------+----------------+------------------------------------------------------+ -| **Parameter** | **Values** | **Default** | **Unit** | **Description** | -+=================+===============+===============+================+======================================================+ -| taEnabled | true, false | false | | Enable or disable this service | -+-----------------+---------------+---------------+----------------+------------------------------------------------------+ -| taDelay | number | | milliseconds | Integration time to take over the new alarm status | -+-----------------+---------------+---------------+----------------+------------------------------------------------------+ - -devicemonitor -~~~~~~~~~~~~~ - -Configure alarm severity of related alarms, generated by Device Monitor. - -`SDNC-616 `__ - SDN-R WT app need to change alarm severity "Configurable" for ConnectionLossxxx alarm family (received from Mediator) , when it passed to DCAE VES collector. - - -Syntax: Parameter=Value - -Example: SeverityconnectionLossOAM=Major - -+----------------------------------+-----------------------------------------------+---------------+------------+--------------------------------------------------------------+ -| Alarm | **Values** | **Default** | **Unit** | **Description** | -+==================================+===============================================+===============+============+==============================================================+ -| SeverityconnectionLossOAM | NonAlarmed, Warning, Minor, Major, Critical | Major | | SDN-Controller <> Mediator | -| | | | | Mountpoint monitoring. Indicates a not connected mounpoint | -+----------------------------------+-----------------------------------------------+---------------+------------+--------------------------------------------------------------+ -| SeverityconnectionLossMediator | NonAlarmed, Warning, Minor, Major, Critical | Major | | SDN-Controller <> NetworkElement | -| | | | | Device monitoring. No LTPs provided | -+----------------------------------+-----------------------------------------------+---------------+------------+--------------------------------------------------------------+ -| SeverityconnectionLossNeOAM | NonAlarmed, Warning, Minor, Major, Critical | Major | | SDN-Controller <> NetworkElement | -| | | | | Device monitoring. SSH Connetion, Core model not answering | -+----------------------------------+-----------------------------------------------+---------------+------------+--------------------------------------------------------------+ diff --git a/docs/user-guide.rst b/docs/user-guide.rst index 717674a..05642c9 100644 --- a/docs/user-guide.rst +++ b/docs/user-guide.rst @@ -12,6 +12,6 @@ This document provides a quickstart for users of the O-RAN SC OAM web applicatio general applications - installation + deployment faq abbreviations \ No newline at end of file diff --git a/solution/operation-and-maintenance/README.md b/solution/operation-and-maintenance/README.md index 8efef8e..15a7174 100644 --- a/solution/operation-and-maintenance/README.md +++ b/solution/operation-and-maintenance/README.md @@ -191,7 +191,8 @@ python network/config.py #### Check (adjust if required) environment variables ``` -nano smo/.env +nano smo/common/.env +nano smo/oam/.env nano network/.env ```