Skip to content

Commit d7a5211

Browse files
CarlosAndreoCarlosAndreo
authored
add: tnlcm docs (#1)
1 parent c264474 commit d7a5211

22 files changed

+283
-47
lines changed

‎docs/intro.md

-47
This file was deleted.

‎docs/tnlcm/_category_.json

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{
2+
"position": 2.5,
3+
"label": "TNLCM",
4+
"collapsible": true,
5+
"collapsed": false,
6+
"className": "red",
7+
"link": {
8+
"type": "generated-index",
9+
"title": "TNLCM overview"
10+
},
11+
"customProps": {
12+
"description": ""
13+
}
14+
}

‎docs/tnlcm/database-schema.md

+70
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
---
2+
sidebar_position: 2
3+
title: "Database Schema"
4+
sidebar_label: "Database Schema"
5+
draft: false
6+
---
7+
8+
TNLCM database, created with MongoDB, consists of several collections that store important information about `resource manager`, `trial network`, `user`, and `verification token`. Below is a description of each collection, along with a graphical representation using SQL syntax created with [dbdiagram.io](https://dbdiagram.io/).
9+
10+
## Collections
11+
12+
### Collection `resource_manager`
13+
14+
| Field | Type | Description |
15+
| ----------- | ------- | ------------------------------------------------- |
16+
| `component` | string | Component over which resources are controlled |
17+
| `tn_id` | string | ID of the trial network |
18+
| `quantity` | integer | Amount of component available |
19+
| `ttl` | float | Time the component can be used in a trial network |
20+
21+
### Collection `trial_network`
22+
23+
| Field | Type | Description |
24+
| ----------------------------------- | -------- | ------------------------------------------ |
25+
| `user_created` | string | User that created the trial network |
26+
| `tn_id` | string | ID of the trial network (primary key) |
27+
| `state` | string | State of the trial network |
28+
| `date_created_utc` | date | Creation date and time in UTC |
29+
| `raw_descriptor` | dict | Raw descriptor of the trial network |
30+
| `sorted_descriptor` | dict | Sorted descriptor |
31+
| `deployed_descriptor` | dict | Current status of descriptor |
32+
| `report` | markdown | Report related to the trial network |
33+
| `directory_path` | string | Directory where trial network is saved |
34+
| `jenkins_deploy_pipeline` | string | Pipeline for descriptor deployment |
35+
| `jenkins_destroy_pipeline` | string | Pipeline for destroying trial network |
36+
| `deployment_site` | string | Deployment site of trial network |
37+
| `input` | dict | YAML files per entity-name sent to Jenkins |
38+
| `output` | dict | JSON received by Jenkins per entity-name |
39+
| `library_https_url` | string | Library github https url |
40+
| `library_commit_id` | string | Library commit ID |
41+
| `sites_https_url` | string | Sites github https url |
42+
| `sites_commit_id` | string | Sites commit ID |
43+
44+
### Collection `user`
45+
46+
| Field | Type | Description |
47+
| ---------- | ------ | ----------------------------- |
48+
| `email` | string | User's email address |
49+
| `username` | string | User's username (primary key) |
50+
| `password` | string | User's hashed password |
51+
| `role` | string | User's role |
52+
| `org` | string | User's organization |
53+
54+
### Collection `verification_token`
55+
56+
| Field | Type | Description |
57+
| -------------------- | ------ | --------------------------------------- |
58+
| `new_account_email` | string | Email for the new account (primary key) |
59+
| `verification_token` | string | Verification token for the account |
60+
| `creation_date` | date | Creation date of the verification token |
61+
62+
## Relationships
63+
64+
- `resource_manager.tn_id > trial_network.tn_id` // resource_manager references trial_network
65+
- `trial_network.user_created > user.username` // A user can have multiple trial_networks (one-to-many)
66+
- `verification_token.new_account_email - user.email` // One-to-one relationship between verification_token and user
67+
68+
## Model
69+
70+
![TNLCM_DATABASE_MODEL](https://github.com/user-attachments/assets/8e17cedd-4a4f-4bcd-941d-9cfa076cbb07)

‎docs/tnlcm/descriptor-schema.md

+26
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
sidebar_position: 4
3+
title: "Descriptor Schema"
4+
sidebar_label: "Descriptor Schema"
5+
draft: false
6+
---
7+
8+
Trial Network Descriptors are yaml files with a set of expected fields and with the following structure:
9+
10+
```yaml
11+
trial_network: # Mandatory, contains the description of all entities in the Trial Network
12+
type-name: # Mandatory, entity name. Unique identifier for each entity in the Trial Network
13+
type: # Mandatory, 6G-Library component type
14+
name: # Mandatory, custom name. Not use character \- or \. Exclude components tn_init, tn_bastion and tn_vxlan
15+
debug: # Optional, param to debug component in Jenkins. Possible values true or false
16+
dependencies: # Mandatory, list of dependencies of the component with other components
17+
- type-name
18+
- ...
19+
input: # Mandatory, dictionary with the variables collected from the input part of the 6G-Library
20+
key: value
21+
```
22+
23+
This repository contains a variety of [descriptors](https://github.com/6G-SANDBOX/TNLCM/tree/main/tn_template_lib). Access the [documentation](https://github.com/6G-SANDBOX/TNLCM/blob/main/tn_template_lib/README.md) to see what is defined in each of them.
24+
25+
- [`ueransim_split.yaml`](https://github.com/6G-SANDBOX/TNLCM/blob/main/tn_template_lib/ueransim_split.yaml) - **should work on all platforms**. First end-to-end trial network.
26+
- [`loadcore_open5gs_vm.yaml`](https://github.com/6G-SANDBOX/TNLCM/blob/main/tn_template_lib/loadcore_open5gs_vm.yaml) - **should work on all platforms**. Reference trial network defined in WP5.

‎docs/tnlcm/mongo-express.md

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
sidebar_position: 6
3+
title: "Mongo Express"
4+
sidebar_label: "Mongo Express"
5+
draft: false
6+
---
7+
8+
A MongoDB dashboard will be available at the url http://mongo-express-ip:8081 where the database can be managed.
9+
10+
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`](https://github.com/6G-SANDBOX/TNLCM/blob/main/.env.template) file are used.
11+
12+
![mongoExpress](../../static/img/tnlcm/mongoExpress.png)

‎docs/tnlcm/project-structure.md

+38
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
sidebar_position: 1
3+
title: "Project Structure"
4+
sidebar_label: "Project Structure"
5+
draft: false
6+
---
7+
8+
Trial Network Lifecycle Manager (TNLCM) is a tool designed to manage the lifecycle of trial networks. Developed in Python, it automates the creation, deployment and management of temporary or test networks, streamlining the process of experimentation and validation in network development projects.
9+
10+
```
11+
TNLCM/ // main folder.
12+
├─ .github/ // folder contains files and templates for GitHub workflow automation.
13+
├─ conf/ // folder that handler the configuration files.
14+
├─ core/ // folder that the developed code is stored.
15+
│ ├─ auth/ // folder that handler the authentication of users who have access.
16+
│ ├─ callback/ // folder that handler the callback received by Jenkins.
17+
│ ├─ cli/ // folder that handler the cli for run commands.
18+
│ ├─ database/ // folder that handler the connection with MongoDB database using mongoengine.
19+
│ ├─ exceptions/ // folder that handler the creation of custom exceptions.
20+
│ ├─ jenkins/ // folder that handler the connection with Jenkins for tn deployment.
21+
│ ├─ logs/ // folder that handler the logs configuration.
22+
│ ├─ mail/ // folder that handler the configuration to use flask mail library.
23+
│ ├─ models/ // folder that contains the database models.
24+
│ ├─ repository/ // folder that handler the connection to any repository.
25+
│ ├─ routes/ // folder that handler the API that is exposed.
26+
│ ├─ library/ // folder that handler the connection to the Library repository.
27+
│ ├─ sites/ // folder that handler the connection to the Sites repository.
28+
│ └─ utils/ // folder that handler data conversions and storage in YAML, Markdown and JSON formats.
29+
├─ docs/ // folder where all documentation is stored.
30+
├─ scripts/ // folder contains scripts for automated deployments.
31+
├─ tn_template_lib/ // folder that trial network descriptors templates are stored.
32+
├─ .env.template // file that contains placeholder environment variables for configuring the application.
33+
├─ .gitignore // file specifying intentionally untracked files to ignore.
34+
├─ app.py // main file that starts TNLCM.
35+
├─ CHANGELOG.md // file containing the changes made in each release.
36+
├─ pyproyect.toml // file containing the libraries and their versions.
37+
└─ uv.lock
38+
```

‎docs/tnlcm/swagger-ui.md

+84
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
---
2+
sidebar_position: 3
3+
title: "Swagger UI"
4+
sidebar_label: "Swagger UI"
5+
draft: false
6+
---
7+
8+
## Login
9+
10+
The API set forth in the TNLCM is as follows:
11+
12+
![api](../../static/img/tnlcm/api.png)
13+
14+
If it is the first time using the API it is necessary to create a user:
15+
16+
![register](../../static/img/tnlcm/register.png)
17+
18+
Once the user has been created or if it has been previously created, add the user and its password in the Basic Authorization section of the **Authorize** box:
19+
20+
![basicAuthorizarion](../../static/img/tnlcm/basicAuthorizarion.png)
21+
22+
Once the user has been added, an access token and its refresh token can be generated. This access token has a duration of one day (can be modified):
23+
24+
![obtainTokens](../../static/img/tnlcm/obtainTokens.png)
25+
26+
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:
27+
28+
![accessToken](../../static/img/tnlcm/accessToken.png)
29+
30+
Now, requests that involve having an access token can be made.
31+
32+
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:
33+
34+
![refreshToken](../../static/img/tnlcm/refreshToken.png)
35+
36+
When the request is made, it will return another access token that will need to be put back into the green **Authorize** box.
37+
38+
## Create Trial Network
39+
40+
Once logged into TNLCM, execute the POST request of the `trial-network` namespace:
41+
42+
![createTN](../../static/img/tnlcm/createTN.png)
43+
44+
Fill in the following fields:
45+
46+
- `tn_id`: must start with a character and be at least 4 characters long. This field can be left blank, in which case a random value will be generated.
47+
- `deployment_site`: must be one of the sites available in the [6G-Sandbox-Sites](https://github.com/6G-SANDBOX/6G-Sandbox-Sites) repository.
48+
- `library_reference_type`: you can specify a branch, tag, or commit of the 6G-Library repository.
49+
- `library_reference_value`: value corresponding to the type specified in the `library_reference_type` field.
50+
- `sites_reference_type`: you can specify a branch, tag, or commit of the 6G-Sandbox-Sites repository.
51+
- `sites_reference_value`: value corresponding to the type specified in the `sites_reference_type` field.
52+
- `descriptor`: descriptor file containing the definition of the trial network. To create a descriptor file, refer to the [Trial Network Descriptor Guide](https://github.com/6G-SANDBOX/TNLCM/wiki/Trial-Network-Descriptor-Guide) section.
53+
54+
## Deploy Trial Network
55+
56+
Once logged into TNLCM and the trial network has been created, execute the PUT request of the `trial-network` namespace:
57+
58+
![deployTN](../../static/img/tnlcm/deployTN.png)
59+
60+
Fill in the following fields:
61+
62+
- `jenkins_deploy_pipeline`: if nothing is specified, a pipeline will be created inside the TNLCM folder in Jenkins with the name `TN_DEPLOY_<tn_id>`. If specified, it will be checked if it exists in Jenkins and that there is nothing queued to execute.
63+
- `tn_id`: the identifier of the trial network received in the [POST request](#create-trial-network).
64+
65+
## Destroy trial network
66+
67+
Once logged into TNLCM, the trial network has been created and the trial network has been deployed, execute the DELETE request to destroy a trial network:
68+
69+
![destroyTN](../../static/img/tnlcm/destroyTN.png)
70+
71+
Fill in the following fields:
72+
73+
- `jenkins_destroy_pipeline`: if nothing is specified, a pipeline will be created inside TNLCM folder in Jenkins with the name `TN_DESTROY_<tn_id>`. If specified, it will be checked if it exists in Jenkins and that there is nothing queued to execute.
74+
- `tn_id`: the identifier of the trial network received in the [POST request](#create-trial-network).
75+
76+
## Purge trial network
77+
78+
Once logged into TNLCM, the trial network has been created, deployed and destroyed, execute the DELETE request to purge a trial network:
79+
80+
![purgeTN](../../static/img/tnlcm/purgeTN.png)
81+
82+
Fill in the following fields:
83+
84+
- `tn_id`: the identifier of the trial network received in the [POST request](#create-trial-network).

‎docs/tnlcm/workflow.md

+38
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
sidebar_position: 5
3+
title: "Workflow"
4+
sidebar_label: "Workflow"
5+
draft: false
6+
---
7+
8+
## Overview of TNLCM and 6G-Library implementation
9+
10+
![overview](../../static/img/tnlcm/overview.png)
11+
12+
## State Machine
13+
14+
TNLCM is a **state machine** that allows the automation of component deployment. Green indicates what is implemented and red indicates what is in the process of implementation.
15+
16+
### States
17+
18+
- **Validated**: trial network descriptor created is checked to see if it can be deployed. 6G-Library is used to validate it
19+
- **Activated**: trial network has been deployed in OpenNebula
20+
- **Suspended**: trial network has been suspended. It remains deployed, but turned off
21+
- **Failed**: there was an error during the trial network deployment
22+
- **Destroyed**: trial network deployment in OpenNebula is removed, but its content is kept in the database and locally
23+
- **Purge**: the trial network and the callbacks are removed from the database as well as its local content
24+
25+
### Transitions
26+
27+
- Initial state &rarr; Validated: trial network descriptor validated and ready for deploy
28+
- Validated &rarr; Activated: trial network deployed and ready for use
29+
- Validated &rarr; Failed: trial network deployment failed
30+
- Validated &rarr; Purge: trial network invalid
31+
- Failed &rarr; Failed: again, trial network deployment failed
32+
- Activated &rarr; Destroyed: trial network destroyed and ready for deploy again
33+
- Activated &rarr; Suspended: TODO
34+
- Suspended &rarr; Activated: TODO
35+
- Destroyed &rarr; Activated: trial network deployed and ready for use
36+
- Destroyed &rarr; Purge: trial network removed
37+
38+
![stateMachine](../../static/img/tnlcm/stateMachine.png)

‎package.json

+1
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
"scripts": {
66
"docusaurus": "docusaurus",
77
"start": "docusaurus start",
8+
"dev": "docusaurus start --host 0.0.0.0",
89
"build": "docusaurus build",
910
"swizzle": "docusaurus swizzle",
1011
"deploy": "docusaurus deploy",

‎static/img/tnlcm/accessToken.png

16.3 KB
Loading

‎static/img/tnlcm/api.png

36.1 KB
Loading

‎static/img/tnlcm/basicAuthorizarion.png

7.08 KB
Loading

‎static/img/tnlcm/createTN.png

57.4 KB
Loading

‎static/img/tnlcm/deployTN.png

29.1 KB
Loading

‎static/img/tnlcm/destroyTN.png

29.6 KB
Loading

‎static/img/tnlcm/mongoExpress.png

21.4 KB
Loading

‎static/img/tnlcm/obtainTokens.png

17.2 KB
Loading

‎static/img/tnlcm/overview.png

216 KB
Loading

‎static/img/tnlcm/purgeTN.png

16.9 KB
Loading

‎static/img/tnlcm/refreshToken.png

12.9 KB
Loading

‎static/img/tnlcm/register.png

30.2 KB
Loading

‎static/img/tnlcm/stateMachine.png

94.8 KB
Loading

0 commit comments

Comments
 (0)