Skip to content

Enhanced documentation, make API public, fix output endpoints #5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Feb 19, 2025
Merged

Enhanced documentation, make API public, fix output endpoints #5

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
03ff2f7
Enhanced documentation, make API public, fix output endpoints
MirkoZETA Feb 19, 2025
ad7c325
Merge branch 'master' into develop
MirkoZETA Feb 19, 2025
5587d35
Fix requirements
MirkoZETA Feb 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
113 changes: 113 additions & 0 deletions .github/workflows/README_DEV.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,113 @@
# Flex Net Sim Backend API - Development and Deployment Instructions

This document is for developers who want to set up, develop, and deploy the Flex Net Sim Backend API.

## Prerequisites

* Python 3.9 or higher
* g++ (GNU C++ Compiler)
* Docker (for containerization)
* Google Cloud SDK (for deployment to Google Cloud Run)
* A Google Cloud Project with Cloud Run API enabled.

## Getting Started (Local Development)

1. **Clone the repository:**
```bash
git clone [https://github.com/MirkoZETA/FlexNetSim-API.git](https://github.com/MirkoZETA/FlexNetSim-API.git)
cd flask-simulation-backend
```

2. **Create a Python virtual environment (recommended):**
```bash
python3 -m venv .venv
```

On Linux/macOS:
```bash
source .venv/bin/activate
```

On Windows
```bash
.venv\Scripts\activate
```
3. **Install Python dependencies:**
```bash
pip install -r requirements.txt
```

4. **Run the Flask backend:**
```bash
flask --app backend run
```
The backend will be accessible at `http://127.0.0.1:5000`.

5. **Test**:
```bash
curl http://127.0.0.1:5000/help
```
or
```bash
curl -X POST -H "Content-Type: application/json" -d '{}' http://127.0.0.1:5000/run_simulation
```

### Dockerization

To build the Docker image:

```bash
docker build -t fns-api .
```

## GCloud Deployment Configuration

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:

[GCloud Configuration Video Tutorial](https://www.youtube.com/watch?v=KQUKDiBz3IA)

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.

**Key Reminders from the Video & for Successful Deployment:**

* **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.
* **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.

**Post-Configuration Steps (using `gcloud` and `cloud-run`):**

1. Activate necessary apis:

* `gcloud services enable run.googleapis.com`

2. Create cloud run service:
* Navigate to the Cloud Run section in your Google Cloud Console.
* Create a **Service**.
* Select *Use an inline editor to create a function*.
* Set a name, in this case *fns-api-cloud-run* will be used.
* Note down the Endpoint URL, because it will the defaul url for the API.
* Select the authetification preferences.
* Create.

3. Update access of service accounts to cloud run resources:

```bash
gcloud projects add-iam-policy-binding "<YOUR-GOOGLE-PROJECT-ID>" --member="serviceAccount:<SERVICE_ACCOUNT_EMAIL>" --role="roles/run.admin"
```

and

```bash
gcloud iam service-accounts add-iam-policy-binding "<YOUR_PROJECT_NUMBER>-compute@developer.gserviceaccount.com" --member="serviceAccount:<SERVICE_ACCOUNT_EMAIL>" --role="roles/iam.serviceAccountActor"
```

4. **Test the Deployed API (using `curl`):**

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`.

```bash
curl -X POST -H "Content-Type: application/json" -d '{"algorithm": "FirstFit", "networkType": 1, "bitrate": "fixed-rate"}' <YOUR-ENDPOINT-URL>/run_simulation
```

Remember that depending on the authetification preferences you might need to authetificate to send request to the Endpoint just created.

**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.
44 changes: 44 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- Switch to Flex Net Sim v0.8.2.
- Enchanced previous algorithms.
- New algorithm BestFit.
- Point README docs to oficial documentation.
- New domain.

## [0.2.0] - 2025-02-19

### Added

- This API hopefully serves as playground to all new users of Flex Net Sim C++ simulation library.
- The current version utilizes Flex Net Sim v0.8.1.
- `/run_simulation` endpoint for simulation includes parameters such as:
- `algorithm`: FirstFit, ExactFit.
- `networkType`: Only 1 (EON) available for now.
- `goalConnections`: 1 to 10,000,000.
- `confidence`: significance level (alpha) greater than zero.
- `lambdaParam`: Arrival rate (lambda) of connection requests.
- `mu`: departure rate of connection requests.
- `network`: name of the netowrk to simulate, `Cost239`, `EuroCore`, `GermanNet`, `UKNet`, `NSFNet`.
- `bitrate`: fixed-rate or flex-rate.
- `K`: Number of paths to consider during allocation, max 6.
- `/help` endpoint provides detailed information about the `/run_simulation` endpoint.
- API allocated in cloud run.
- Documentation README for the process of develop/deployment located in [workflows](https://github.com/MirkoZETA/FlexNetSim-API/tree/master/.github/workflows/README_DEV.md).

## [0.1.0] - 2025-02-18

### Added

- It was a mess!

[0.2.0]: https://github.com/MirkoZETA/FlexNetSim-API/releases/tag/v0.0.2
[0.1.0]: https://github.com/MirkoZETA/FlexNetSim-API/releases/tag/v0.0.1
174 changes: 43 additions & 131 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,167 +1,79 @@
# Flex Net Sim Backend API

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

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

* Python 3.9 or higher
* g++ (GNU C++ Compiler)
* Docker (for containerization)
* Google Cloud SDK (for deployment to Cloud Run)
* A Google Cloud Project with Cloud Run API enabled.
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.

## Getting Started (Local Development)
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.

1. **Clone the repository:**
```bash
git clone https://github.com/MirkoZETA/FlexNetSim-API.git
cd flask-simulation-backend
```
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**.

2. **Create a Python virtual environment (recommended):**
```bash
python3 -m venv .venv
source .venv/bin/activate # On Linux/macOS
.venv\Scripts\activate # On Windows
```
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.

3. **Install Python dependencies:**
```bash
pip install -r requirements.txt
```
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/).

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

## API Endpoints

### `/run_simulation` (POST)

This endpoint runs a FlexNetSim simulation based on the parameters provided in the JSON request body.
This endpoint runs a Flex Net Sim simulation based on the parameters provided in the JSON request body.

**Request Body Parameters:**

| Parameter | Type | Description | Allowed Values | Default Value | Constraints |
| :---------------- | :--------------- | :----------------------------------------------------------------------------- | :---------------------------- | :------------ | :-------------------- |
| `algorithm` | `string` | Routing and spectrum assignment algorithm to use. | `FirstFit`, `ExactFit` | `FirstFit` | |
| `networkType` | `integer` | Type of optical network. | `1` | `1` | Only `1` (EON) available |
| `goal_connections`| `integer` | Target number of connection requests for the simulation. | | `100000` | Must be integer > 0 |
| `confidence` | `number (float)` | Confidence level for the simulation results. | | `0.05` | Must be > 0 |
| `lambda_param` | `number (float)` | Arrival rate (lambda) of connection requests. | | `1.0` | Must be > 0 |
| `mu` | `number (float)` | Service rate (mu) of connection requests. | | `10.0` | Must be > 0 |
| `network` | `string` | Network topology to simulate. | `NSFNet`, `Cost239`, `EuroCore`, `GermanNet`, `UKNet` | `NSFNet` | |
| `bitrate` | `string` | Type of bitrate allocation. | `fixed-rate`, `flex-rate` | `bitrate` | |
| `K` | `integer` | Number of paths to compute. | | `3` | |
| Parameter | Type | Description | Allowed Values | Default Value | Constraints |
| :---------------- | :-------------- | :----------------------------------------------------- | :---------------------------- | :------------ | :-------------------- |
| `algorithm` | `string` | Routing and spectrum assignment algorithm to use. | `FirstFit`, `ExactFit` | `FirstFit` | |
| `networkType` | `integer` | Type of optical network. | `1` | `1` | Only `1` (EON) available |
| `goalConnections`| `integer` | Target number of connection requests for the simulation.| | `100000` | Must be integer > 0 |
| `confidence` | `number (float)`| Confidence level for the simulation results. | | `0.05` | Must be > 0 |
| `lambdaParam` | `number (float)` | Arrival rate (lambda) of connection requests. | | `1.0` | Must be > 0 |
| `mu` | `number (float)`| Service rate (mu) of connection requests. | | `10.0` | Must be > 0 |
| `network` | `string` | Network topology to simulate. | `NSFNet`, `Cost239`, `EuroCore`, `GermanNet`, `UKNet` | `NSFNet` | |
| `bitrate` | `string` | Type of bitrate allocation. | `fixed-rate`, `flex-rate` | `bitrate` | |
| `K` | `integer` | Number of paths to consider. | | `3` | |

**Example `curl` request with minimal parameters (defaults applied):**
**Example `curl` request with no parameters (defaults applied):**

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

**Example `curl`request with all parameters specified:**

```bash
curl -X POST -H "Content-Type: application/json" \
-d '{
"algorithm": "FirstFit",
"networkType": 1, -> (Only EONs available for the moment)
"goal_connections": 10000000,
"confidence": 0.05,
"lambda": 120,
"mu": 1,
"network": "NSFNet",
"bitrate": "bitrate" -> (filename in the ./bitrates folder)
}' \
http://127.0.0.1:5000/run_simulation
```
curl -X POST -H "Content-Type: application/json" \
-d '{ "algorithm": "FirstFit",
"networkType": 1,
"goalConnections": 1000000,
"confidence": 0.05,
"lambdaParam": 120,
"mu": 1,
"network": "NSFNet",
"bitrate": "fixed-rate"
}' \
https://fns-api-cloud-run-787143541358.us-central1.run.app/run_simulation
```

**Response**:
- 200 OK: Simulation executed successfully. The response body will be a JSON object with the following structure:
- `200` OK: Simulation executed successfully. The response body will be a JSON object with the following structure:
```JSON
{
"output": "string", // Simulation output results
"error": "string" // Empty string if no errors
"output": "string",
"error": "string"
}
```
- 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.
- 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.
- `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.
- `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.

### `/help` (GET)

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

**Request**:
```bash
curl http://127.0.0.1:5000/help
```

## Dockerization

To build the Docker image:

```bash
docker build -t fns-api .
```
To run:
```bash
docker run -p 8080:8080 fns-api
```
To stop:
```bash
docker stop fns-api
```

## GCloud Deployment Configuration

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:

[GCloud Configuration Video Tutorial](https://www.youtube.com/watch?v=KQUKDiBz3IA)

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.

**Key Reminders from the Video & for Successful Deployment:**

* **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.
* **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.

**Post-Configuration Steps (using `gcloud` and `cloud-run`):**

1. Activate necessary apis:

* `gcloud services enable run.googleapis.com`

2. Create cloud run service:
* Navigate to the Cloud Run section in your Google Cloud Console.
* Create a **Service**.
* Select *Use an inline editor to create a function*.
* Set a name, in this case *fns-api-cloud-run* will be used.
* Note down the Endpoint URL, because it will the defaul url for the API.
* Select the authetification preferences.
* Create.

3. Update access of service accounts to cloud run resources:

```bash
gcloud projects add-iam-policy-binding "<YOUR-GOOGLE-PROJECT-ID>" --member="serviceAccount:<SERVICE_ACCOUNT_EMAIL>" --role="roles/run.admin"
```

and

```bash
gcloud iam service-accounts add-iam-policy-binding "<YOUR_PROJECT_NUMBER>-compute@developer.gserviceaccount.com" --member="serviceAccount:<SERVICE_ACCOUNT_EMAIL>" --role="roles/iam.serviceAccountActor"
```

4. **Test the Deployed API (using `curl`):**

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`.

```bash
curl -X POST -H "Content-Type: application/json" -d '{"algorithm": "FirstFit", "networkType": 1, "bitrate": "bitrate"}' <YOUR-ENDPOINT-URL>/run_simulation
```

Remember that depending on the authetification preferences you might need to authetificate to send request to the Endpoint just created.

**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.
curl https://fns-api-cloud-run-787143541358.us-central1.run.app/help
```
Loading