Skip to content

Commit c399f3b

Browse files
MirkoZETAMirkoZETA
authored
Merge pull request #5 from MirkoZETA/develop
Enhanced documentation, make API public, fix output endpoints
2 parents c7cf5dc + 5587d35 commit c399f3b

File tree

6 files changed

+349
-325
lines changed

6 files changed

+349
-325
lines changed

‎.github/workflows/README_DEV.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# Flex Net Sim Backend API - Development and Deployment Instructions
2+
3+
This document is for developers who want to set up, develop, and deploy the Flex Net Sim Backend API.
4+
5+
## Prerequisites
6+
7+
* Python 3.9 or higher
8+
* g++ (GNU C++ Compiler)
9+
* Docker (for containerization)
10+
* Google Cloud SDK (for deployment to Google Cloud Run)
11+
* A Google Cloud Project with Cloud Run API enabled.
12+
13+
## Getting Started (Local Development)
14+
15+
1. **Clone the repository:**
16+
```bash
17+
git clone [https://github.com/MirkoZETA/FlexNetSim-API.git](https://github.com/MirkoZETA/FlexNetSim-API.git)
18+
cd flask-simulation-backend
19+
```
20+
21+
2. **Create a Python virtual environment (recommended):**
22+
```bash
23+
python3 -m venv .venv
24+
```
25+
26+
On Linux/macOS:
27+
```bash
28+
source .venv/bin/activate
29+
```
30+
31+
On Windows
32+
```bash
33+
.venv\Scripts\activate
34+
```
35+
3. **Install Python dependencies:**
36+
```bash
37+
pip install -r requirements.txt
38+
```
39+
40+
4. **Run the Flask backend:**
41+
```bash
42+
flask --app backend run
43+
```
44+
The backend will be accessible at `http://127.0.0.1:5000`.
45+
46+
5. **Test**:
47+
```bash
48+
curl http://127.0.0.1:5000/help
49+
```
50+
or
51+
```bash
52+
curl -X POST -H "Content-Type: application/json" -d '{}' http://127.0.0.1:5000/run_simulation
53+
```
54+
55+
### Dockerization
56+
57+
To build the Docker image:
58+
59+
```bash
60+
docker build -t fns-api .
61+
```
62+
63+
## GCloud Deployment Configuration
64+
65+
As a prerequisite is mandatory to apply the following steps to the GCloud project for the docker image build and upload to artifacts, and also service account creation and IAM policy binding:
66+
67+
[GCloud Configuration Video Tutorial](https://www.youtube.com/watch?v=KQUKDiBz3IA)
68+
69+
This video will guide you through the necessary configurations in the Google Cloud Console to prepare your project for Cloud Run deployments using GitHub Actions.
70+
71+
**Key Reminders from the Video & for Successful Deployment:**
72+
73+
* **Keep Track of Docker Image Name, Project ID:** Note these down during the video configuration, as you will need them in subsequent steps and for your GitHub Actions workflow.
74+
* **Service Account Email:** Ensure you create a Service Account as shown in the video and securely download and store the JSON key file. You'll also need to note the Service Account's email address.
75+
76+
**Post-Configuration Steps (using `gcloud` and `cloud-run`):**
77+
78+
1. Activate necessary apis:
79+
80+
* `gcloud services enable run.googleapis.com`
81+
82+
2. Create cloud run service:
83+
* Navigate to the Cloud Run section in your Google Cloud Console.
84+
* Create a **Service**.
85+
* Select *Use an inline editor to create a function*.
86+
* Set a name, in this case *fns-api-cloud-run* will be used.
87+
* Note down the Endpoint URL, because it will the defaul url for the API.
88+
* Select the authetification preferences.
89+
* Create.
90+
91+
3. Update access of service accounts to cloud run resources:
92+
93+
```bash
94+
gcloud projects add-iam-policy-binding "<YOUR-GOOGLE-PROJECT-ID>" --member="serviceAccount:<SERVICE_ACCOUNT_EMAIL>" --role="roles/run.admin"
95+
```
96+
97+
and
98+
99+
```bash
100+
gcloud iam service-accounts add-iam-policy-binding "<YOUR_PROJECT_NUMBER>-compute@developer.gserviceaccount.com" --member="serviceAccount:<SERVICE_ACCOUNT_EMAIL>" --role="roles/iam.serviceAccountActor"
101+
```
102+
103+
4. **Test the Deployed API (using `curl`):**
104+
105+
Use the `curl` command with the `ENDPOINT-URL` you obtained from the previous steps to test your deployed API. Replace `YOUR-ENDPOINT-URL` with the actual `ENDPOINT-URL`.
106+
107+
```bash
108+
curl -X POST -H "Content-Type: application/json" -d '{"algorithm": "FirstFit", "networkType": 1, "bitrate": "fixed-rate"}' <YOUR-ENDPOINT-URL>/run_simulation
109+
```
110+
111+
Remember that depending on the authetification preferences you might need to authetificate to send request to the Endpoint just created.
112+
113+
**Remember**: These GCloud configurations, along with the repository's `gke-cd.yml` GitHub Actions workflow and correctly configured GitHub secrets, are essential for successful automated deployment of your FlexNetSim-API application to Google Cloud Run.

‎CHANGELOG.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [Unreleased]
9+
10+
### Added
11+
- Switch to Flex Net Sim v0.8.2.
12+
- Enchanced previous algorithms.
13+
- New algorithm BestFit.
14+
- Point README docs to oficial documentation.
15+
- New domain.
16+
17+
## [0.2.0] - 2025-02-19
18+
19+
### Added
20+
21+
- This API hopefully serves as playground to all new users of Flex Net Sim C++ simulation library.
22+
- The current version utilizes Flex Net Sim v0.8.1.
23+
- `/run_simulation` endpoint for simulation includes parameters such as:
24+
- `algorithm`: FirstFit, ExactFit.
25+
- `networkType`: Only 1 (EON) available for now.
26+
- `goalConnections`: 1 to 10,000,000.
27+
- `confidence`: significance level (alpha) greater than zero.
28+
- `lambdaParam`: Arrival rate (lambda) of connection requests.
29+
- `mu`: departure rate of connection requests.
30+
- `network`: name of the netowrk to simulate, `Cost239`, `EuroCore`, `GermanNet`, `UKNet`, `NSFNet`.
31+
- `bitrate`: fixed-rate or flex-rate.
32+
- `K`: Number of paths to consider during allocation, max 6.
33+
- `/help` endpoint provides detailed information about the `/run_simulation` endpoint.
34+
- API allocated in cloud run.
35+
- Documentation README for the process of develop/deployment located in [workflows](https://github.com/MirkoZETA/FlexNetSim-API/tree/master/.github/workflows/README_DEV.md).
36+
37+
## [0.1.0] - 2025-02-18
38+
39+
### Added
40+
41+
- It was a mess!
42+
43+
[0.2.0]: https://github.com/MirkoZETA/FlexNetSim-API/releases/tag/v0.0.2
44+
[0.1.0]: https://github.com/MirkoZETA/FlexNetSim-API/releases/tag/v0.0.1

‎README.md‎

Lines changed: 43 additions & 131 deletions
Original file line numberDiff line numberDiff line change
@@ -1,167 +1,79 @@
11
# Flex Net Sim Backend API
22

3-
Flask-based backend API for integrating the FlexNetSim C++ library, powering the web application.
3+
Welcome to the Flex Net Sim Backend API repository.
44

5-
## Prerequisites
5+
This is the **publicly accessible backend API** for the [Flex Net Sim](https://gitlab.com/DaniloBorquez/flex-net-sim) project.
66

7-
* Python 3.9 or higher
8-
* g++ (GNU C++ Compiler)
9-
* Docker (for containerization)
10-
* Google Cloud SDK (for deployment to Cloud Run)
11-
* A Google Cloud Project with Cloud Run API enabled.
7+
This API provides a **hands-on demonstration**, enabling users to quickly execute pre-configured network simulations and gain an initial understanding of Flex Net Sim's capabilities.
128

13-
## Getting Started (Local Development)
9+
Through simple POST requests, initiated via command-line tools or the [playground page](www.in-progress.com), users can experiment with a defined set of parameters and algorithms. This allows for exploration of fundamental network simulation concepts using Flex Net Sim.
1410

15-
1. **Clone the repository:**
16-
```bash
17-
git clone https://github.com/MirkoZETA/FlexNetSim-API.git
18-
cd flask-simulation-backend
19-
```
11+
It is important to note that **this API is intentionally designed as a limited demonstration platform**. It serves as a **simplified method of accessing** and showcasing the **basic functionalities** of Flex Net Sim. **It is not intended for complex simulations or for algorithm customization.** Algorithm customization is a core strength of Flex Net Sim, and this advanced capability is exclusively unlocked when working directly with **the library**.
2012

21-
2. **Create a Python virtual environment (recommended):**
22-
```bash
23-
python3 -m venv .venv
24-
source .venv/bin/activate # On Linux/macOS
25-
.venv\Scripts\activate # On Windows
26-
```
13+
The purpose of this API is to introduce users to Flex Net Sim and encourage exploration of **the full library** for advanced simulation tasks. **The full library** offers significantly greater power, flexibility, and customization potential.
2714

28-
3. **Install Python dependencies:**
29-
```bash
30-
pip install -r requirements.txt
31-
```
15+
For users interested in progressing beyond this introductory API, comprehensive resources and documentation are available at the official [Flex Net Sim documentation](https://flex-net-sim-fork.readthedocs.io/stable/).
3216

33-
4. **Run the Flask backend:**
34-
```bash
35-
flask --app backend run
36-
```
37-
The backend will be accessible at `http://127.0.0.1:5000`.
17+
For **Development and Deployment Instructions** of this API (the playground itself), please refer to [README_DEV.md](README_DEV.md).
3818

3919
## API Endpoints
4020

4121
### `/run_simulation` (POST)
4222

43-
This endpoint runs a FlexNetSim simulation based on the parameters provided in the JSON request body.
23+
This endpoint runs a Flex Net Sim simulation based on the parameters provided in the JSON request body.
4424

4525
**Request Body Parameters:**
4626

47-
| Parameter | Type | Description | Allowed Values | Default Value | Constraints |
48-
| :---------------- | :--------------- | :----------------------------------------------------------------------------- | :---------------------------- | :------------ | :-------------------- |
49-
| `algorithm` | `string` | Routing and spectrum assignment algorithm to use. | `FirstFit`, `ExactFit` | `FirstFit` | |
50-
| `networkType` | `integer` | Type of optical network. | `1` | `1` | Only `1` (EON) available |
51-
| `goal_connections`| `integer` | Target number of connection requests for the simulation. | | `100000` | Must be integer > 0 |
52-
| `confidence` | `number (float)` | Confidence level for the simulation results. | | `0.05` | Must be > 0 |
53-
| `lambda_param` | `number (float)` | Arrival rate (lambda) of connection requests. | | `1.0` | Must be > 0 |
54-
| `mu` | `number (float)` | Service rate (mu) of connection requests. | | `10.0` | Must be > 0 |
55-
| `network` | `string` | Network topology to simulate. | `NSFNet`, `Cost239`, `EuroCore`, `GermanNet`, `UKNet` | `NSFNet` | |
56-
| `bitrate` | `string` | Type of bitrate allocation. | `fixed-rate`, `flex-rate` | `bitrate` | |
57-
| `K` | `integer` | Number of paths to compute. | | `3` | |
27+
| Parameter | Type | Description | Allowed Values | Default Value | Constraints |
28+
| :---------------- | :-------------- | :----------------------------------------------------- | :---------------------------- | :------------ | :-------------------- |
29+
| `algorithm` | `string` | Routing and spectrum assignment algorithm to use. | `FirstFit`, `ExactFit` | `FirstFit` | |
30+
| `networkType` | `integer` | Type of optical network. | `1` | `1` | Only `1` (EON) available |
31+
| `goalConnections`| `integer` | Target number of connection requests for the simulation.| | `100000` | Must be integer > 0 |
32+
| `confidence` | `number (float)`| Confidence level for the simulation results. | | `0.05` | Must be > 0 |
33+
| `lambdaParam` | `number (float)` | Arrival rate (lambda) of connection requests. | | `1.0` | Must be > 0 |
34+
| `mu` | `number (float)`| Service rate (mu) of connection requests. | | `10.0` | Must be > 0 |
35+
| `network` | `string` | Network topology to simulate. | `NSFNet`, `Cost239`, `EuroCore`, `GermanNet`, `UKNet` | `NSFNet` | |
36+
| `bitrate` | `string` | Type of bitrate allocation. | `fixed-rate`, `flex-rate` | `bitrate` | |
37+
| `K` | `integer` | Number of paths to consider. | | `3` | |
5838

59-
**Example `curl` request with minimal parameters (defaults applied):**
39+
**Example `curl` request with no parameters (defaults applied):**
6040

6141
```bash
62-
curl -X POST -H "Content-Type: application/json" -d '{"algorithm": "FirstFit", "networkType": 1, "bitrate": "bitrate"}' http://127.0.0.1:5000/run_simulation
42+
curl -X POST -H "Content-Type: application/json" -d '{}' https://fns-api-cloud-run-787143541358.us-central1.run.app/run_simulation
6343
```
6444

6545
**Example `curl`request with all parameters specified:**
46+
6647
```bash
67-
curl -X POST -H "Content-Type: application/json" \
68-
-d '{
69-
"algorithm": "FirstFit",
70-
"networkType": 1, -> (Only EONs available for the moment)
71-
"goal_connections": 10000000,
72-
"confidence": 0.05,
73-
"lambda": 120,
74-
"mu": 1,
75-
"network": "NSFNet",
76-
"bitrate": "bitrate" -> (filename in the ./bitrates folder)
77-
}' \
78-
http://127.0.0.1:5000/run_simulation
79-
```
48+
curl -X POST -H "Content-Type: application/json" \
49+
-d '{ "algorithm": "FirstFit",
50+
"networkType": 1,
51+
"goalConnections": 1000000,
52+
"confidence": 0.05,
53+
"lambdaParam": 120,
54+
"mu": 1,
55+
"network": "NSFNet",
56+
"bitrate": "fixed-rate"
57+
}' \
58+
https://fns-api-cloud-run-787143541358.us-central1.run.app/run_simulation
59+
```
8060

8161
**Response**:
82-
- 200 OK: Simulation executed successfully. The response body will be a JSON object with the following structure:
62+
- `200` OK: Simulation executed successfully. The response body will be a JSON object with the following structure:
8363
```JSON
8464
{
85-
"output": "string", // Simulation output results
86-
"error": "string" // Empty string if no errors
65+
"output": "string",
66+
"error": "string"
8767
}
8868
```
89-
- 400 Bad Request: Indicates an error in the request, such as missing or invalid parameters. The response body will be a JSON object with an `"error"` field describing the issue.
90-
- 500 Internal Server Error: Indicates a server-side error, either during compilation or simulation execution. The response body will be a JSON object with `"error"` and "details" fields providing more information about the error.
69+
- `400` Bad Request: Indicates an error in the request, such as missing or invalid parameters. The response body will be a JSON object with an `error` field describing the issue.
70+
- `500` Internal Server Error: Indicates a server-side error, either during compilation or simulation execution. The response body will be a JSON object with `error` and "details" fields providing more information about the error.
9171

9272
### `/help` (GET)
9373

94-
This endpoint provides detailed information about the `/run_simulation` endpoint, including the expected request structure, parameters, allowed values, and response formats.
74+
This endpoint provides detailed information about the `/run_simulation` endpoint, including the expected request structure, parameters, and response formats.
9575

9676
**Request**:
9777
```bash
98-
curl http://127.0.0.1:5000/help
99-
```
100-
101-
## Dockerization
102-
103-
To build the Docker image:
104-
105-
```bash
106-
docker build -t fns-api .
107-
```
108-
To run:
109-
```bash
110-
docker run -p 8080:8080 fns-api
111-
```
112-
To stop:
113-
```bash
114-
docker stop fns-api
115-
```
116-
117-
## GCloud Deployment Configuration
118-
119-
As a prerequisite is mandatory to apply the following steps to the GCloud project for the docker image build and upload to artifacts, and also service account creation and IAM policy binding:
120-
121-
[GCloud Configuration Video Tutorial](https://www.youtube.com/watch?v=KQUKDiBz3IA)
122-
123-
This video will guide you through the necessary configurations in the Google Cloud Console to prepare your project for Cloud Run deployments using GitHub Actions.
124-
125-
**Key Reminders from the Video & for Successful Deployment:**
126-
127-
* **Keep Track of Docker Image Name, Project ID:** Note these down during the video configuration, as you will need them in subsequent steps and for your GitHub Actions workflow.
128-
* **Service Account Email:** Ensure you create a Service Account as shown in the video and securely download and store the JSON key file. You'll also need to note the Service Account's email address.
129-
130-
**Post-Configuration Steps (using `gcloud` and `cloud-run`):**
131-
132-
1. Activate necessary apis:
133-
134-
* `gcloud services enable run.googleapis.com`
135-
136-
2. Create cloud run service:
137-
* Navigate to the Cloud Run section in your Google Cloud Console.
138-
* Create a **Service**.
139-
* Select *Use an inline editor to create a function*.
140-
* Set a name, in this case *fns-api-cloud-run* will be used.
141-
* Note down the Endpoint URL, because it will the defaul url for the API.
142-
* Select the authetification preferences.
143-
* Create.
144-
145-
3. Update access of service accounts to cloud run resources:
146-
147-
```bash
148-
gcloud projects add-iam-policy-binding "<YOUR-GOOGLE-PROJECT-ID>" --member="serviceAccount:<SERVICE_ACCOUNT_EMAIL>" --role="roles/run.admin"
149-
```
150-
151-
and
152-
153-
```bash
154-
gcloud iam service-accounts add-iam-policy-binding "<YOUR_PROJECT_NUMBER>-compute@developer.gserviceaccount.com" --member="serviceAccount:<SERVICE_ACCOUNT_EMAIL>" --role="roles/iam.serviceAccountActor"
155-
```
156-
157-
4. **Test the Deployed API (using `curl`):**
158-
159-
Use the `curl` command with the `ENDPOINT-URL` you obtained from the previous steps to test your deployed API. Replace `YOUR-ENDPOINT-URL` with the actual `ENDPOINT-URL`.
160-
161-
```bash
162-
curl -X POST -H "Content-Type: application/json" -d '{"algorithm": "FirstFit", "networkType": 1, "bitrate": "bitrate"}' <YOUR-ENDPOINT-URL>/run_simulation
163-
```
164-
165-
Remember that depending on the authetification preferences you might need to authetificate to send request to the Endpoint just created.
166-
167-
**Remember**: These GCloud configurations, along with the repository's `gke-cd.yml` GitHub Actions workflow and correctly configured GitHub secrets, are essential for successful automated deployment of your FlexNetSim-API application to Google Cloud Run.
78+
curl https://fns-api-cloud-run-787143541358.us-central1.run.app/help
79+
```

0 commit comments

Comments
 (0)