Report error · Feature request

TNLCM has been designed as a modular application, with the intention of making certain components easily replaceable or extended, while minimizing the effect of changes in other parts of the application. At the same time, there is an emphasis on re-usability, where several data structures and generic logic can be shared between the different components of the application.

Note

TNLCM is under development and is subject to continuous changes.

Table of Contents

• 🛠️ Stack
• 📂 Project Structure
• 🔍 Overview of TNLCM and 6G-Library implementation
• 🔄 State Machine
• ⏳ Current Status
• 🚀 Getting Started Locally
  • 📥 Download or clone repository
  • 🔧 Configure environment variables
  • 💾 Create database
  • 🐍 Create environment
• 📄 Trial Network Descriptor Schema
• Appendices
  • Appendix A: How to use Swagger UI
  • Appendix B: Database Schema
  • Appendix C: TNLCM OpenNebula Appliance

🛠️ Stack

• - Programming language.
• - Python framework for web applications to expose the API.
• - NoSQL database designed to store Trial Networks.
• - Platform for running database applications.

📂 Project Structure

TNLCM/                       // main folder.
├─ .github/                  // folder contains files and templates for GitHub workflow automation.
│  ├─ CHANGELOG_TEMPLATE/    // folder with template for changelog.
│  └─ ISSUE_TEMPLATE/        // folder with template for issue reporting.
├─ .gitignore                // file specifying intentionally untracked files to ignore.
├─ app.py                    // main file that starts TNLCM.
├─ CHANGELOG.md              // file containing the changes made in each release.
├─ tn_template_lib/          // folder in which trial network descriptors templates are stored.
├─ docker-compose.yaml       // file for create database.
├─ docs/                     // folder in which all documentation is stored.
├─ requirements.txt          // file containing the libraries and their versions.
├─ conf/                     // folder that handler the configuration files.
└─ core/                     // folder in which the developed code is stored.
   ├─ auth/                  // folder that handler the authentication of users who have access.
   ├─ callback/              // folder that handler the results received by Jenkins.
   ├─ database/              // folder that handler the connection with MongoDB database using mongoengine.
   ├─ exceptions/            // folder that handler the creation of custom exceptions.
   ├─ jenkins/               // folder that handler the connection with Jenkins for tn deployment.
   ├─ logs/                  // folder that handler the logs configuration.
   ├─ mail/                  // folder that handler the configuration to use flask mail library.
   ├─ models/                // folder that contains the database models.
   ├─ repository/            // folder that handler the connection to any repository.
   ├─ resource_manager/      // folder that handler the resource manager.
   ├─ routes/                // folder that handler the API that is exposed.
   ├─ sixg_library/          // folder that handler the connection to the 6G-Library repository.
   ├─ sixg_sandbox_sites/    // folder that handler the connection to the 6G-Sandbox-Sites repository.
   └─ temp/                  // folder that handler the creation of temporary files.

🔍 Overview of TNLCM and 6G-Library implementation

Back to top🔼

🔄 State Machine

Back to top🔼

⏳ Current Status

TNLCM is currently able to deploy the following types of components corresponding with the 6G-Library: tn_vxlan, tn_bastion, tn_init, vnet, tsn, vm_kvm, oneKE, open5gs, UERANSIM-gNB and UERANSIM-UE.

Back to top🔼

🚀 Getting Started Locally

Note

TNLCM is being developed and tested on Ubuntu in version 22.04.3 LTS.

Tip

TNLCM uses the following repository releases:

Repository	Branch	Release
6G-Library	develop	-
6G-Sandbox-Sites	platform	-

📥 Download or clone repository

Download the main branch from the TNLCM repository.

Clone repository:

git clone https://github.com/6G-SANDBOX/TNLCM

🔧 Configure environment variables

Create a .env file at the root level, using the structure and content provided in the .env.template file.

Mandatory update the values of the following variables according to the platform:

• TNLCM_HOST
• JENKINS_HOST
• JENKINS_USERNAME
• JENKINS_PASSWORD
• JENKINS_TOKEN
• ANSIBLE_VAULT

💾 Create database

Important

This step requires Docker to be installed on the machine.

Once Docker is installed, open a terminal where the docker-compose.yaml file is stored (usually inside the TNLCM project) and execute the command:

docker compose up -d

Flag -d can be added to raise the containers in background.

A MongoDB dashboard will be available at the url http://mongodb-frontend-ip:8081 where the database can be managed.

Note

User and password to access to the MongoDB dashboard are the values indicated in the variables ME_CONFIG_BASICAUTH_USERNAME and ME_CONFIG_BASICAUTH_PASSWORD of the .env file. By default, the values indicated in the .env.template file are used.

🐍 Create environment

Important

This step requires Python to be installed on the machine.

The environment must be created inside the TNLCM folder:

• Linux

  # Create environment
  python3 -m venv venv
  
  # Activate environment
  source venv/bin/activate
  
  # Install libraries
  pip install -r requirements.txt

With the environment activated, start TNLCM:

python app.py

A Swagger UI will be available at the url http://tnlcm-backend-ip:5000 where the API with the endpoints can be seen.

Back to top🔼

📄 Trial Network Descriptor Schema

Warning

The format of Trial Network Descriptors has not been finalized and is expected to change in the future.

Trial Network Descriptors are yaml files with a set of expected fields and with the following structure:

trial_network: # Mandatory, contains the description of all entities in the Trial Network
  type-name: # Mandatory, a unique identifier for each entity in the Trial Network (entity name)
    type: # Mandatory, 6G-Library component type
    name: # Mandatory, custom name. Not use character \- or \.
    debug: # Optional, param to debug component in Jenkins. Possible values true or false
    dependencies: # Mandatory, list of dependencies of the component with other components
      - type-name
      - ...
    input: # Mandatory, dictionary with the variables collected from the input part of the 6G-Library
      key: value

This repository contains a variety of descriptor templates.

The first end-to-end trial network:

• 08_descriptor.yaml - should work on all platforms

Back to top🔼

Appendices

Appendix A: How to use Swagger UI

The API set forth in the TNLCM is as follows:

If it is the first time using the API it is necessary to create a user. A verification code is required, so it is necessary to enter a valid email address that can be accessed:

Once the registration code is obtained, proceed to the user registration using the email and the code previously employed:

Once the user has been created or if it has been previously created, add the user and its password in the green Authorize box:

Once the user has been added, an access token and its refresh token can be generated. This access token has a duration of 45 minutes (can be modified):

The next step is to add the token in the green Authorize box. It is required to put the word Bearer, a space and then the token. An example is shown:

Now, requests that involve having an access token can be made.

To create a Trial Network, the following endpoint must be used:

Once created, it will return a tn_id that will be required to deploy it.

To deploy a trial network, the following endpoint must be used:

If the access token expires, it can be refreshed by using the refresh token. The token in the green Authorize box must be updated with the refresh token and the post request must be made:

When the request is made, it will return another access token that will need to be put back into the green Authorize box.

Back to top🔼

Appendix B: Database Schema

The TNLCM database consists of several collections that store important information about trial networks, users, and verification tokens. Below is the description of each collection:

Collection trial_networks

Field	Description
user_created	The user that created the trial network.
tn_id	The ID of the trial network.
tn_state	The state of the trial network.
tn_date_created_utc	The date and time when the trial network was created (UTC).
tn_raw_descriptor	The raw descriptor of the trial network.
tn_sorted_descriptor	The sorted descriptor of the trial network.
tn_deployed_descriptor	The current status of descriptor with the last entity deployed of the trial network.
tn_report	The report related to the trial network.
jenkins_deploy_pipeline	The pipeline used for the deployment of the descriptor.
jenkins_destroy_pipeline	The pipeline used for destroy a trial network.
deployment_site	The site where the trial network has been deployed.
github_6g_library_commit_id	The commit id of 6G-Library (branch, commit or tag) used to deploy trial network.
github_6g_sandbox_sites_commit_id	The commid id of 6G-Sandbox-Sites (branch, commit or tag) used to deploy trial network.

Collection trial_networks_templates

Field	Description
user_created	The user that created the trial network template.
tn_id	The ID of the trial network template.
tn_date_created_utc	The date and time when the trial network template was created (UTC).
tn_raw_descriptor	The raw descriptor of the trial network template.
tn_sorted_descriptor	The sorted descriptor of the trial network template.

Collection users

Field	Description
email	The email address of the user.
username	The username of the user.
password	The password of the user (hashed).
org	The organization to which the user belongs.

Collection verifications_tokens

Field	Description
new_account_email	The email associated with the new account.
verification_token	The verification token generated for the new account.
creation_date	The creation date of the verification token.

Collection resource_manager

Field	Description
site	The site where the trial network has been deployed.
component	The component over which the resources are controlled.
quantity	The amount of component available.
ttl	The amount of time the component can be used in a trial network.

Back to top🔼

Appendix C: TNLCM OpenNebula Appliance

In the marketplace-community repository, which is a fork of OpenNebula, detailed information about the TNLCM appliance can be found.

To deploy 6G-SANDBOX TOOLKIT in OpenNebula, the documentation can be accessed from the web site.

Back to top🔼

👷 Development Team

Photo	Name	Email	GitHub	Linkedin
	Carlos Andreo López	-
	Bruno García García	-

Back to top🔼