Skip to content

Commit f00847d

Browse files
MirkoZETAMirkoZETA
committed
First commit
0 parents  commit f00847d

23 files changed

+86520
-0
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.

‎.github/workflows/gke-cd.yml‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
name: Deploy FNS API to Cloud Run (Separated Jobs)
2+
3+
on:
4+
push:
5+
branches:
6+
- master
7+
pull_request:
8+
branches:
9+
- master
10+
11+
jobs:
12+
build-and-push-image:
13+
name: Build and Push Docker Image
14+
runs-on: ubuntu-latest
15+
steps:
16+
- name: Checkout code
17+
uses: actions/checkout@v2
18+
19+
- name: Google Cloud Auth # Authenticate gcloud CLI
20+
uses: google-github-actions/auth@v2
21+
with:
22+
credentials_json: ${{ secrets.GOOGLE_APPLICATION_CREDENTIALS }}
23+
24+
- name: Set up Google Cloud CLI # Set up gcloud CLI and Docker
25+
uses: google-github-actions/setup-gcloud@v2
26+
with:
27+
version: latest
28+
project_id: ${{ secrets.GOOGLE_PROJECT }}
29+
30+
- name: Configure Docker to push to Artifact Registry # Configure docker auth
31+
run: |
32+
gcloud auth configure-docker us-central1-docker.pkg.dev
33+
34+
- name: Build and Push Docker image to Artifact Registry # Build and push image
35+
env:
36+
GOOGLE_PROJECT: ${{ secrets.GOOGLE_PROJECT }}
37+
IMAGE_NAME: us-central1-docker.pkg.dev/${{ secrets.GOOGLE_PROJECT }}/flex-net-sim-repo/fns-api
38+
IMAGE_TAG: latest
39+
run: |
40+
docker build -t $IMAGE_NAME:$IMAGE_TAG .
41+
docker push $IMAGE_NAME:$IMAGE_TAG
42+
43+
deploy-to-cloud-run:
44+
name: Deploy to Cloud Run
45+
runs-on: ubuntu-latest
46+
needs: build-and-push-image # Ensure this job runs after build-and-push-image
47+
steps:
48+
- name: Checkout code (again, if needed for deploy steps - optional)
49+
uses: actions/checkout@v2
50+
51+
- name: Google Cloud Auth # Authenticate gcloud CLI
52+
uses: google-github-actions/auth@v2
53+
with:
54+
credentials_json: ${{ secrets.GOOGLE_APPLICATION_CREDENTIALS }}
55+
56+
- name: Deploy to Cloud Run
57+
uses: google-github-actions/deploy-cloudrun@v1
58+
with:
59+
image: us-central1-docker.pkg.dev/${{ secrets.GOOGLE_PROJECT }}/flex-net-sim-repo/fns-api:latest # Use the same image as built
60+
service: fns-api-cloud-run
61+
region: us-central1
62+
project_id: ${{ secrets.GOOGLE_PROJECT }}

‎.gitignore‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
__pycache__
2+
simulation.out
3+
4+
# Exclude local IDE settings
5+
.vscode/
6+
7+
# macOS
8+
**/.DS_Store

‎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

‎Dockerfile‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
FROM python:3.12-slim-bookworm
2+
WORKDIR /app
3+
4+
COPY requirements.txt ./
5+
RUN pip install --no-cache-dir -r requirements.txt
6+
RUN pip install --no-cache-dir --upgrade pip setuptools
7+
8+
RUN apt-get update && apt-get upgrade -y && apt-get install -y --no-install-recommends build-essential # Update OS packages and keep build-essential
9+
10+
COPY backend.py ./
11+
COPY src ./src
12+
COPY networks ./networks
13+
COPY bitrates ./bitrates
14+
15+
# CMD ["g++ -O3 -o simulation.out ./src/main.cpp"] # Commented out as per original Dockerfile
16+
17+
CMD ["gunicorn", "backend:app", "--bind", "0.0.0.0:8080", "--workers", "3"]

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 Mirko Zitkovich
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Flex Net Sim Backend API
2+
3+
Welcome to the Flex Net Sim Backend API repository.
4+
5+
This is the **publicly accessible backend API** for the [Flex Net Sim](https://gitlab.com/DaniloBorquez/flex-net-sim) project.
6+
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.
8+
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.
10+
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**.
12+
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.
14+
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/).
16+
17+
For **Development and Deployment Instructions** of this API (the playground itself), please refer to [README_DEV.md](README_DEV.md).
18+
19+
## API Endpoints
20+
21+
### `/run_simulation` (POST)
22+
23+
This endpoint runs a Flex Net Sim simulation based on the parameters provided in the JSON request body.
24+
25+
**Request Body Parameters:**
26+
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` | |
38+
39+
**Example `curl` request with no parameters (defaults applied):**
40+
41+
```bash
42+
curl -X POST -H "Content-Type: application/json" -d '{}' https://fns-api-cloud-run-787143541358.us-central1.run.app/run_simulation
43+
```
44+
45+
**Example `curl`request with all parameters specified:**
46+
47+
```bash
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+
```
60+
61+
**Response**:
62+
- `200` OK: Simulation executed successfully. The response body will be a JSON object with the following structure:
63+
```JSON
64+
{
65+
"output": "string",
66+
"error": "string"
67+
}
68+
```
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.
71+
72+
### `/help` (GET)
73+
74+
This endpoint provides detailed information about the `/run_simulation` endpoint, including the expected request structure, parameters, and response formats.
75+
76+
**Request**:
77+
```bash
78+
curl https://fns-api-cloud-run-787143541358.us-central1.run.app/help
79+
```

0 commit comments

Comments
 (0)