Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/hardmax71/integr8scode

Integr8sCode lets you run Python scripts online by executing them in isolated K8s pods with resource limits. Just input your code!
https://github.com/hardmax71/integr8scode

fastapi grafana js k8s locust mongodb prometheus pydantic-v2 python svelte svelte3 tailwind

Last synced: 15 days ago
JSON representation

Integr8sCode lets you run Python scripts online by executing them in isolated K8s pods with resource limits. Just input your code!

Host: GitHub
URL: https://github.com/hardmax71/integr8scode
Owner: HardMax71
License: mit
Created: 2024-10-10T20:37:48.000Z (4 months ago)
Default Branch: main
Last Pushed: 2024-10-23T20:57:10.000Z (4 months ago)
Last Synced: 2024-10-24T08:47:15.009Z (4 months ago)
Topics: fastapi, grafana, js, k8s, locust, mongodb, prometheus, pydantic-v2, python, svelte, svelte3, tailwind
Language: Python
Homepage:
Size: 318 KB
Stars: 1
Watchers: 1
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

Integr8sCode

---

Welcome to **Integr8sCode**! This is a platform where you can run Python scripts online with ease. Just paste your
script, and the platform run it in an isolated environment within its own Kubernetes pod, complete with resource limits
to keep
things safe and efficient. You'll get the results back in no time.

Full demo

https://github.com/user-attachments/assets/5501579f-1478-4374-a7d8-0d65c14a6c33

How to deploy

**Backend:**

1. Change directory to `backend`

```bash
cd backend
```

2. Create a certs folder

```bash
mkdir certs
```

3. Enable Kubernetes in Docker Desktop

- In Docker Desktop => Settings => Kubernetes, check `Enable Kubernetes`.
- Let Docker Desktop spin up the single-node cluster. Confirm it’s running:
```bash
kubectl cluster-info
```

Should show something like:
```
Kubernetes control plane is running at https://kubernetes.docker.internal:6443
```

4. Create a Service Account and Token

```bash
kubectl create serviceaccount integr8scode-sa -n default
kubectl create clusterrolebinding integr8scode-sa-admin-binding --clusterrole=cluster-admin --serviceaccount=default:integr8scode-sa
kubectl create token integr8scode-sa -n default --duration=24h
```

After 3rd command, you’ll get back a JWT token string. That’s what you’ll paste into your `kubeconfig.yaml` as the `token:` property.

5. Extract Docker Desktop’s CA Certificate

Docker Desktop’s Kubernetes cluster uses a root CA that’s separate from your self-signed one.
The certificate-authority-data or certificate-authority in your local `~/.kube/config` (or `%USERPROFILE%\.kube\config`
on Windows) is the Docker Desktop CA you want to trust inside the container.

```bash
kubectl config view --raw -o jsonpath="{.clusters[?(@.name=='docker-desktop')].cluster.certificate-authority-data}" \
| base64 --decode \
> ./certs/docker-desktop-ca.crt
```

On Windows: it's complicated. Do following:

```bash
kubectl config view --raw -o jsonpath="{.clusters[?(@.name=='docker-desktop')].cluster.certificate-authority-data}"
```

will return some string starting with `LS0..`. You need to decode it to get the certificate itself, simplest way is to
use online base64 decoder, like [this one](https://www.base64decode.org/). Copy the string and paste it into the decoder,
then copy the decoded string and save it to `./certs/docker-desktop-ca.crt` file (last line should be empty!).

6. Generate Self-Signed Certificates for FastAPI

While in `/backend`:

> Idea about using OpenSSL from Git in Win came from [here](https://stackoverflow.com/a/51757939), if needed - change commands below accordingly.

```bash
openssl req -x509 -newkey rsa:4096 -nodes -keyout ./certs/server.key -out ./certs/server.crt -days 365 -subj "/C=US/ST=Test/L=Test/O=Test Org/CN=localhost"
```
Win:
```bash
` & "C:\Program Files\Git\usr\bin\openssl.exe" req -x509 -newkey rsa:4096 -nodes -keyout ./certs/server.key -out ./certs/server.crt -days 365 -subj "/C=US/ST=Test/L=Test/O=Test Org/CN=localhost"`
```

You’ll now have:
```
backend/
certs/
docker-desktop-ca.crt # Step 5
server.key # Step 6
server.crt # Step 6
```

7. Change `kubeconfig.yaml`

```
apiVersion: v1
kind: Config
clusters:
- name: docker-desktop
cluster:
server: https://kubernetes.docker.internal:6443
certificate-authority: /app/certs/docker-desktop-ca.crt
users:
- name: integr8scode-sa
user:
token:
contexts:
- name: integr8scode
context:
cluster: docker-desktop
user: integr8scode-sa
current-context: integr8scode
```

8. Now call `docker-compose up --build` - that will download all required stuff and start the backend part.
Backend will be available at `https://0.0.0.0:443`.

**Frontend:**

1. Change directory to `frontend`

```bash
cd frontend
```

2. Install dependencies: `npm install`

```bash
npm install
```

3. Generate self-signed private key for SSL/TLS encryption:

- Windows 10:
```bash
& "C:\Program Files\Git\usr\bin\openssl.exe" req -x509 -newkey rsa:4096 -nodes -keyout ./server.key -out ./server.crt -days 365 -subj "/C=US/ST=Test/L=Test/O=Test Org/CN=localhost" -addext "subjectAltName=DNS:localhost,IP:127.0.0.1"`
```
- Mac:
```bash
openssl req -x509 -newkey rsa:4096 -nodes -keyout ./server.key -out ./server.crt -days 365 -subj "/C=US/ST=Test/L=Test/O=Test Org/CN=localhost" -addext "subjectAltName=DNS:localhost,IP:127.0.0.1"
```

4. Build the app: `npm run dev`

```bash
npm run dev
```
5. The frontend will be available at `https://localhost:5001/`.

If the browser shows a security warning, it's because the certificate is self-signed. You have to proceed by accepting
the risk and continuing to the site.

Except that, you may find out following (at least, in Chrome):

> Failed to load resource: net::ERR_FAILED - for `/api/v1/k8s-limits:1`

This error effectively means that K8s cluster isn't started: thus, go to Docker Desktop => Settings => Kubernetes => Enable Kubernetes
and check if K8s is enabled - it should be. If not - enable it, wait till it will be, then:

```bash
docker-compose down -v
docker-compose up --build
```

Effectively, you will need to rebuild images and restart containers. Also, check output of:
```bash
curl -k https://localhost/api/v1/k8s-limits
```

if the output is:

> {"cpu_limit":"100m","memory_limit":"128Mi","cpu_request":"100m","memory_request":"128Mi","execution_timeout":5,
> "supported_python_versions":["3.7","3.8","3.9","3.10","3.11","3.12"]}%

then the problem is only in frontend.

Sample test

You can check correctness of start by running a sample test script:
1. Open website at `https://localhost:5001/`, go to Editor
2. In code window, paste following code:
```python
from typing import TypeGuard

def is_string(value: object) -> TypeGuard[str]:
return isinstance(value, str)

def example_function(data: object):
match data: # Match statement introduced in Python 3.10
case int() if data > 10:
print("An integer greater than 10")
case str() if is_string(data):
print(f"A string: {data}")
case _:
print("Something else")

example_function(15)
example_function("hello")
example_function([1, 2, 3])
```

First, select `>= Python 3.10` and run script, will output:
```
Status: completed
Execution ID:
Output:
An integer greater than 10
A string: hello
Something else
```

Then, select `< Python 3.10` and do the same:
```
Status: completed
Execution ID:
Output:
File "/scripts/script.py", line 7
match data: # Match statement introduced in Python 3.10
^
SyntaxError: invalid syntax
```
This shows that pods with specified python versions are creating and working as expected. Btw, the latter throws error
cause `match-case` was introduced first in `Python 3.10`.

## Architecture Overview

The platform is built on three main pillars:

- **Frontend**: A sleek Svelte app that users interact with.
- **Backend**: Powered by FastAPI, Python, and MongoDB to handle all the heavy lifting.
- **Kubernetes Cluster**: Each script runs in its own pod, ensuring isolation and resource control.

Components diagram

Backend Details

### Script Execution Workflow

Here's how your script gets executed:

1. **Receive Script**: You send your code via the `/execute` endpoint.
2. **Spin Up Pod**: K8s creates a new pod for your script.
3. **Run Script**: Your code is executed in the pod.
4. **Capture Output**: Any output or errors are recorded.
5. **Store Results**: Everything gets saved in MongoDB.
6. **Update Status**: Execution status is updated for you.

### Database Design

MongoDB setup includes an `executions` collection:

- **Fields**:
- `execution_id`: Unique ID for each execution.
- `script`: The code provided.
- `output`: What the script printed out.
- `errors`: Any errors that occurred.
- `status`: Whether your script is in the process (`queued`, `running`, `completed`, `failed`).
- `created_at` and `updated_at`: Timestamps for tracking.

Frontend Details

### User Interface Components

Svelte app includes:

- **Code Editor**: A place to write or paste Python code.
- **Run Button**: Kick off the execution.
- **Output Area**: See the results or errors from the script.
- **Status Display**: Know if your script is queued, running, or done.

### State Management

- **Stores**: Svelte's built-in stores are used to keep track of your script and its execution status.
- **API Calls**: Functions that talk to backend endpoints and handle responses smoothly.

## Kubernetes Integration

### Pod Setup

- **Docker Image**:Lightweight Python image with just what we need is used.
- **Isolation**: Every script gets its own pod for security and reliability.
- **Cleanup**: Once your script is done, the pod goes away to keep things tidy.

### Resource Management

> [!TIP]
> By limiting resources, we ensure fair usage and prevent any single script from hogging the system.

- **CPU & Memory Limits**: Each pod has caps to prevent overuse (128 Mi for RAM and 100m for CPU).
- **Timeouts**: Scripts can't run forever—they'll stop after a set time (default: 5s).
- **Disk Space**: Limited to prevent excessive storage use.

> You can find actual limits in dropdown above execution output.

### Security Considerations

> [!CAUTION]
> Running user-provided code is risky. We take security seriously to protect both our system and other users.

- **Network Restrictions**: Pods can't make external network calls.
- **No Privileged Access**: Pods run without elevated permissions.

## User Authentication

- **Accounts**: Optional—users can sign up to save scripts.
- **Security**: We use JWT tokens to secure API endpoints.

## Logging and Monitoring

- **Logs**: Centralized logging helps us track what's happening across pods.
- **Monitoring Tools**: Using Prometheus and Grafana to keep an eye on system health.
- **Alerts**: Set up notifications for when things go wrong.

To access:

- Prometheus: http://localhost:9090
- Grafana: http://localhost:3000 (login with admin/admin123)

## Testing Strategy

Unit Tests

**Repository Tests**: Testing individual database operations

- Located in `tests/unit/test_repositories/`
- Testing CRUD operations for each model
- Using real MongoDB test instance
- Ensuring data integrity and constraints
- Running with pytest-asyncio for async operations

**Service Tests**: Testing business logic and service layer

- Located in `tests/unit/test_services/`
- Testing service methods independently
- Using actual repositories with test database
- Ensuring proper error handling
- Verifying state changes and data transformations

Integration Tests

**API Endpoint Tests**: Testing complete HTTP workflows

- Located in `tests/integration/test_api_endpoints.py`
- Testing all REST endpoints
- Using FastAPI TestClient
- Verifying response codes and payloads
- Testing authentication and authorization
- Ensuring proper error responses

**Kubernetes Integration Tests**: Testing pod execution

- Located in `tests/integration/test_k8s_integration.py`
- Testing script execution in pods
- Verifying resource limits and constraints
- Testing cleanup and error scenarios
- Using test Kubernetes cluster

Load Testing

**Performance Scenarios**: Using Locust for load testing

- Located in `tests/load/`
- Different load profiles:
- Smoke Test: 1 user, basic functionality
- Light Load: 10 users, 5 minutes
- Medium Load: 50 users, 10 minutes
- Heavy Load: 100 users, 15 minutes
- Stress Test: 200 users, 30 minutes
- Measuring:
- Response times
- Error rates
- System resource usage
- Database performance
- Kubernetes scaling

Main results:

Test Configuration

**Environment Setup**:

- `.env.test` for test environment variables
- `pytest.ini` for pytest configuration
- `conftest.py` for shared fixtures
- Docker compose for test dependencies

**Test Database**:

- Separate MongoDB instance for testing
- Fresh database for each test run
- Automated cleanup after tests

**Test Coverage**:

- `pytest-cov` for coverage reporting
- 92% coverage of core functionality
- Coverage reports in HTML and XML