Skip to content

TUTORIAL.md

Latest commit

 

History

History
311 lines (222 loc) · 9.36 KB

TUTORIAL.md

File metadata and controls

311 lines (222 loc) · 9.36 KB
Raw
OpenAirInterface implementation of the 5G Network Data Analytics Function

NWDAF contains:

  • NWDAF Analytics Info Service API [NBI Analytics]
  • NWDAF Events Subscription Service API [NBI Events]
  • NWDAF ML Model Provision Service API [NBI Ml]
  • NWDAF Engine [Engine]
  • NWDAF Engine ADS [Engine ADS]
  • NWDAF Southbound Interface [SBI]

Its primary objective is to offer comprehensive documentation and tutorials guiding users through the process of deploying NWDAF using container-based technology.

1. Building NWDAF images

Clone the repository

git clone https://gitlab.eurecom.fr/oai/cn5g/oai-cn5g-nwdaf.git
cd oai-cn5g-nwdaf
# to use the latest release
git checkout master
# to use the latest development sprint result
git checkout develop

Note: use the --no-cache flag only when you need a clean rebuild. If nothing changed, reusing Docker cache is faster.

All images but oai-nwdaf-engine-ads have a target base with alpine. They can be run on any operating system.

As for oai-nwdaf-engine-ads, it has a python:3.6.9-slim target base (which is Debian:10-based). It should be able to run on any operating system as well.

1.1. oai-nwdaf-nbi-analytics

docker build \
            --target oai-nwdaf-nbi-analytics  --tag oai-nwdaf-nbi-analytics:latest \
            --file components/oai-nwdaf-nbi-analytics/docker/Dockerfile.nbi-analytics \
            components/oai-nwdaf-nbi-analytics

1.2. oai-nwdaf-nbi-events

docker build \
            --target oai-nwdaf-nbi-events  --tag oai-nwdaf-nbi-events:latest \
            --file components/oai-nwdaf-nbi-events/docker/Dockerfile.nbi-events \
            components/oai-nwdaf-nbi-events

1.3. oai-nwdaf-nbi-ml

docker build  \
            --target oai-nwdaf-nbi-ml  --tag oai-nwdaf-nbi-ml:latest \
            --file components/oai-nwdaf-nbi-ml/docker/Dockerfile.nbi-ml \
            components/oai-nwdaf-nbi-ml

1.4. oai-nwdaf-engine

docker build  \
            --target oai-nwdaf-engine  --tag oai-nwdaf-engine:latest \
            --file components/oai-nwdaf-engine/docker/Dockerfile.engine \
            components/oai-nwdaf-engine

1.5. oai-nwdaf-engine-ads

docker build \
            --target oai-nwdaf-engine-ads  --tag oai-nwdaf-engine-ads:latest \
            --file components/oai-nwdaf-engine-ads/docker/Dockerfile.engine-ads \
            components/oai-nwdaf-engine-ads

1.6. oai-nwdaf-sbi

docker build \
            --target oai-nwdaf-sbi  --tag oai-nwdaf-sbi:latest \
            --file components/oai-nwdaf-sbi/docker/Dockerfile.sbi \
            components/oai-nwdaf-sbi

1.7. Pull required images

docker pull mongo
docker pull kong

Remove dangling images

docker image prune --force

Later versions of docker are using the BUILD_TOOLKIT:

docker buildx prune -f

2. Network configuration

Ensure a secure and functional network setup using the following steps:

sudo sysctl net.ipv4.conf.all.forwarding=1
sudo iptables -P FORWARD ACCEPT
echo "127.1.0.1   oai-nwdaf-nbi-gateway" | sudo tee -a /etc/hosts

3. NWDAF deployment

3.1. Starting 5G CN

For this deployment, we used the OAI CN develop branch.

# Navigate out of the oai-nwdaf project repository
cd ..

# Clone the OAI CN repository
git clone --branch develop https://gitlab.eurecom.fr/oai/cn5g/oai-cn5g-fed.git

To deploy the OAI 5G Core Network, execute the following commands:

# Make sure you are in the oai-cn5g-fed/docker-compose project repository
cd oai-cn5g-fed/docker-compose

# You can deploy 5G CN only with NRF (scenario 1) and HTTP.
python3 ./core-network.py --type start-basic-vpp --scenario 1

Warning - If you stop the 5G CN, specifically AMF and SMF, while NWDAF is still running, the subscriptions to the network functions will be lost. Ensure to restart NWDAF every time you restart 5G CN to maintain correct behavior.

3.2. Starting NWDAF

To initiate NWDAF components, execute the following commands:

# Navigate back to the oai-nwdaf project repository
cd ../../oai-cn5g-nwdaf
# Deploying NWDAF if AMF/SMF HTTP version is 2
docker-compose -f docker-compose/docker-compose-nwdaf-cn-http2.yaml up -d --force-recreate

4. Testing

After ensuring both the 5G CN and NWDAF are up and running, you can conduct various tests to validate NWDAF features. Here's how you can perform the tests:

4.1. Attaching gnbsim

Ensure you have the gnbsim image by pulling a prebuilt Docker image

docker pull rohankharade/gnbsim
docker image tag rohankharade/gnbsim:latest gnbsim:latest

Attach a UE using the gnbsim-vpp:

# Navigate to the oai-cn5g-fed project repository
cd ../oai-cn5g-fed

# Attach a UE using the gnbsim-vpp scenario
docker-compose -f docker-compose/docker-compose-gnbsim-vpp.yaml up -d --force-recreate

4.2. Testing NWDAF features

We have implemented the following features for both the Events Subscription API and the Analytics Info API:

  • Event: NETWORK_PERFORMANCE
    • Type: Number of connected users (NwPerType: NUM_OF_UE)
    • Type: Session success ratio (NwPerType: SESS_SUCC_RATIO)
  • Event: UE_COMMUNICATION
  • Event: UE_MOBILITY

In addition to these features, we have also implemented an ML-based feature exclusively for the Events Subscription API:

  • Event: ABNORMAL_BEHAVIOUR
    • Exception ID: UNEXPECTED_LARGE_RATE_FLOW

4.2.1 Test Analytics Info API

Run the CLI to test the Analytics Info API:

# Navigate to cli directory
cd ../cli

# Create and activate a virtual environment
python3 -m venv env
source env/bin/activate

# Install dependencies
python -m pip install --upgrade pip
pip install -r requirements.txt

# If you are not using the /etc/hosts entry above, point the CLI to the published Kong port explicitly.
# export NWDAF_NBI_GATEWAY_URL=http://127.0.0.1

# Run the nwdaf CLI to test Analytics Info API
python nwdaf.py analytics examples/analytics/<json_file_name>

4.2.2 Test Event Subscription API

Run the CLI to test the Events Subscription API:

# Run the nwdaf CLI to test Events Subscription API
python nwdaf.py subscribe examples/subscriptions/<json-file-name>

4.2.3 3GPP APIs

For more in-depth information about 3GPP APIs, refer to the following specifications:

4.3. Inspecting oai-nwdaf-database

To examine the data stored in the oai-nwdaf-database:

# Open MongoDB console in the container
docker exec -it oai-nwdaf-database mongosh

# Switch to testing database
use testing

# View data in amf or smf collections
db.amf.find()
db.smf.find()

This inspection must be done while the NWDAF containers are still running. After docker-compose ... down, the oai-nwdaf-database container is removed and docker exec will fail.

5. Stopping NWDAF deployment

To stop NWDAF, run:

# Make sure you are in the oai-nwdaf project repository
cd ../../oai-cn5g-nwdaf
# Stop NWDAF if AMF/SMF 
docker-compose -f docker-compose/docker-compose-nwdaf-cn-http2.yaml down

To stop the gnbsim-vpp, run:

# Make sure you are in the oai-cn5g-fed project repository
cd ../oai-cn5g-fed

# Stop UE
docker-compose -f docker-compose/docker-compose-gnbsim-vpp.yaml down

To stop the OAI CN, run:

# Make sure you are in the oai-cn5g-fed/docker-compose project repository
cd docker-compose

# Stop CN
python3 ./core-network.py --type stop-basic-vpp --scenario 1

6. Support/further resources