mrw (Mini Railway)

A minimal provisioning control plane that provisions “services” onto a compute substrate. This MVP uses Kubernetes as the substrate (Deployment + Service). The public API stays intentionally substrate-neutral so the same contract could later be backed by another scheduler/runtime.

Goals

• Expose a small control-plane API to provision a service: image + port → running workload
  • Endpoint reachable via kubectl port-forward svc/<deployment_name> 8080:<service_port>
• Keep the workflow developer-friendly (Tilt, docs UI, quick iteration)
• Demonstrate core control-plane concerns: resource creation order, cleanup, logs, and basic ergonomics

Local Setup

Prereqs:

• Docker Desktop with Kubernetes enabled
• kubectl configured (uses your local kubeconfig)
• Tilt

Install Tilt (pick one):

brew install tilt

curl -fsSL https://raw.githubusercontent.com/tilt-dev/tilt/master/scripts/install.sh | bash

Start the project:

tilt up

This uses docker-compose.yml via Tilt. The FastAPI control plane runs as a Docker container and talks to the local Kubernetes cluster using your mounted kubeconfig.

Usage

Preferred: FastAPI docs UI

1. Open http://localhost:8001/docs
2. Use the /deployments endpoints from the interactive UI (request body validation, live responses)

Deploy nginx:

curl -X POST "http://localhost:8001/deployments" \
  -H "Content-Type: application/json" \
  -d '{"image_name":"nginx:latest","deployment_name":"test","port":80}'

Get logs:

curl "http://localhost:8001/deployments/test/logs"

Delete:

curl -X DELETE "http://localhost:8001/deployments/test"

Architecture

Control plane (FastAPI) → Kubernetes API → Deployments/Services/Pods

• FastAPI runs in a Docker container (via docker-compose + Tilt), not inside the Kubernetes cluster for this MVP.
• The API container mounts your local kubeconfig and uses the Kubernetes Python client to talk to the cluster.
• API responsibilities:
  • POST /deployments creates a Deployment and a matching Service
  • GET /deployments/{deployment_name}/logs fetches logs from the first matching Pod
  • DELETE /deployments/{deployment_name} deletes the Service then the Deployment
• Diagram:

What I'd Build Next

This MVP focuses on the core provisioning loop (deploy → logs → delete). Up next, I'd add:

• Polling for deployment readiness - Right now, /logs can fail if the pod isn't ready yet. I'd add a status endpoint that polls until healthy.
• Health checks (readiness/liveness probes) - Kubernetes won't route traffic until the app is healthy. Critical for zero-downtime deployments.
• Horizontal scaling - A system like this needs autoscaling. This would be the primitive (PATCH /deployments/{name}/scale).

These are stubbed in k8s_utils.py