βββββββ βββββββ βββββββ βββββββββββ βββββββ βββ βββ
ββββββββββββββββββββββββββββββββββββ ββββββββββββ βββ
βββββββββββ ββββββ βββββββββ βββ βββ ββββββ ββ βββ
βββββββ βββ ββββββ βββββββββ βββ βββ βββββββββββββ
βββ ββββββββββββββββββββ βββββββββββββββββββββββββββ
βββ βββββββ βββββββ βββ ββββββββ βββββββ ββββββββ
Zero-Trust Security Β· Auto-Healing Β· Auto-Scaling Β· Full Observability
PodFlow is a production-style microservices platform built with Podman and podman-compose, designed to demonstrate real-world container orchestration patterns. It showcases:
- π Zero-Trust Network Segmentation via Calico network policies
- π Auto-Healing that automatically restarts failed containers
- π Auto-Scaling based on real-time CPU metrics
- π― Security Honeypot to trap and log intrusion attempts
- π Full Observability Stack with Prometheus & Grafana
- π API Gateway pattern for unified, controlled service access
This project is ideal for anyone learning cloud-native DevOps, container security, or microservice architecture at a production quality level.
βββββββββββββββββββββββββββββββββββββββββββββββββββ
β PUBLIC INTERNET β
ββββββββββββββββββββββββββ¬βββββββββββββββββββββββββ
β :8080
ββββββββββββββββββββββββββΌβββββββββββββββββββββββββ
public_net β π API GATEWAY β
β Node.js Β· Express Β· Port 8080 β
β Rate Limiting Β· Prometheus Metrics β
βββββββββββββββββ¬ββββββββββββββββββββββββββββββββββ
β service_net
βββββββββββββββββββββββΌββββββββββββββββββββββββ
β β β
ββββββββββββββΌβββββββββββ βββββββββΌβββββββββββ ββββββββββΌβββββββββββ
β π€ User Service β β ποΈ Backend Svc β β π Monitoring β
β Node.js Β· Port 5000 β β Node.js Β· :5000 β β Prometheus :9090 β
β /users Β· /health β β Internal only β β Grafana :3000 β
β Prometheus metrics β β Prometheus mtrs β β β
βββββββββββββββββββββββββ ββββββββββββββββββββ βββββββββββββββββββββ
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β π― Honeypot Service (Isolated) β
β Python Β· Flask Β· Port 8888 (HTTP) + 2222 (SSH) β
β Logs all intrusion attempts β Prometheus metrics β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β π§ Automation Script β
β orchestrator.py ββ Auto-Heal & Auto-Scale Daemon β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
| Network | Purpose | Members |
|---|---|---|
public_net |
External-facing traffic | API Gateway |
service_net |
Internal service mesh | Gateway, User-Service, Backend, Prometheus, Grafana, Honeypot |
services/api-gateway/Β· Node.js + Express Β· Port 8080
The single public entry point for all external traffic. Proxies requests to internal services, enforces routing rules, and exposes Prometheus metrics.
| Endpoint | Method | Description |
|---|---|---|
/health |
GET | Gateway health status |
/api/users |
GET/POST | Proxied to User Service |
/metrics |
GET | Prometheus scrape endpoint |
services/user-service/Β· Node.js + Express Β· Port 5000 (internal)
Handles user management logic. Accessible only through the API Gateway β never directly exposed to the internet.
| Endpoint | Method | Description |
|---|---|---|
/health |
GET | Service health check |
/users |
GET | Returns user list |
/metrics |
GET | Prometheus metrics |
services/backend/Β· Node.js Β· Port 5000 (internal only)
Core backend logic layer. Isolated from the public internet. Only the API Gateway and Prometheus can communicate with it, enforced by Calico network policy (app-data-protection).
services/data-service/Β· Python Β· (internal)
Lightweight Python-based data layer for internal data operations. Designed to be consumed only by other services within the service_net network.
services/honeypot/Β· Python + Flask Β· Port 8888 (HTTP) + Port 2222 (SSH)
A deception-layer security component that mimics vulnerable endpoints (/admin, /phpmyadmin, /.env) and a fake SSH server to detect and log intrusion attempts.
How it works:
- Exposes fake admin panels to lure attackers
- Runs a simulated SSH server on port 2222
- Every intrusion attempt is logged with timestamp + IP
- All events are exported as Prometheus metrics for Grafana dashboards
# Metrics exposed by the honeypot
honeypot_intrusion_attempts_total # SSH + HTTP attempts by source IP
honeypot_suspicious_requests_total # Suspicious HTTP endpoint accessPodFlow ships with a full observability stack out of the box.
monitoring/prometheus/Β· Port 9090
Scrapes metrics from all services:
gateway_http_requests_totalβ API Gateway request volumehttp_requests_totalβ User Service request volumehoneypot_intrusion_attempts_totalβ Security eventsprocess_cpu_seconds_totalβ CPU usage per serviceprocess_resident_memory_bytesβ Memory usage per service
monitoring/grafana/Β· Port 3000
Pre-configured dashboards and datasources for visualizing:
- Request rates per service
- CPU & memory consumption trends
- Security threat heatmaps (from honeypot metrics)
Default credentials: admin / admin (change on first login)
PodFlow implements Zero-Trust segmentation via Calico NetworkPolicy resources (network/Policies.yaml).
| Policy | Target | Effect |
|---|---|---|
gateway-shield |
API Gateway | Allows public :8080 + Prometheus scraping; egress only to Backend |
app-data-protection |
Backend | Allows ingress only from Gateway + Prometheus; egress blocked |
intrusion-trap-isolation |
Honeypot | Allows all on :2222/:8888 + Prometheus; fully isolated egress |
default-security-lockout |
Global | Deny-all fallback for unmatched traffic |
Internet βββΊ Gateway βββΊ Backend (all other paths DENIED)
β
ββββΊ Prometheus βββ all services /metrics
Internet βββΊ Honeypot (isolated, logs everything)
PodFlow runs a unified Orchestrator daemon that handles both auto-healing and auto-scaling:
- π Auto-Healing: Monitors the running containers (
api-gateway,backend,user-service,honeypot). If any container crashes or fails HTTP health checks 3 times consecutively, the orchestrator automatically restarts it. - π Auto-Scaling: Monitors the average CPU usage of all running replicas of the
backend. If CPU usage exceeds70%, it dynamically scales up a new replica (max 3) and adds it to the internal network load-balancing. If CPU usage drops below30%, it scales down.
Ensure the following are installed on your system:
# Check versions
podman --version # >= 4.0
podman-compose --version # >= 1.0
python3 --version # >= 3.9
node --version # >= 18.x| Tool | Install Guide |
|---|---|
| Podman | podman.io/docs/installation |
| podman-compose | pip3 install podman-compose |
| Python 3 | python.org/downloads |
| Node.js 18+ | nodejs.org/en/download |
git clone https://github.com/your-username/Podflow.git
cd Podflow# Build all container images and start every service
podman-compose up --buildThis single command will:
- Build Docker/Podman images for all microservices
- Create the
public_netandservice_netbridge networks - Start all 6 services: API Gateway, User Service, Backend, Data Service, Prometheus, Grafana, and Honeypot
- Attach health checks and restart policies
# Check all running containers
podman ps
# Check compose service status
podman-compose psExpected output:
CONTAINER ID IMAGE COMMAND STATUS PORTS
xxxxxxxxxxxx localhost/podflow_api-gateway ... Up 2 min 0.0.0.0:8080->8080/tcp
xxxxxxxxxxxx localhost/podflow_user-service ... Up 2 min
xxxxxxxxxxxx localhost/podflow_backend ... Up 2 min 0.0.0.0:5000->5000/tcp
xxxxxxxxxxxx docker.io/prom/prometheus ... Up 2 min 0.0.0.0:9090->9090/tcp
xxxxxxxxxxxx docker.io/grafana/grafana ... Up 2 min 0.0.0.0:3000->3000/tcp
xxxxxxxxxxxx localhost/podflow_honeypot ... Up 2 min 0.0.0.0:8888->8888/tcp
| Service | URL | Credentials |
|---|---|---|
| API Gateway | http://localhost:8080 | β |
| API Gateway Health | http://localhost:8080/health | β |
| User API | http://localhost:8080/api/users | β |
| Prometheus | http://localhost:9090 | β |
| Grafana | http://localhost:3000 | admin / admin |
| Honeypot | http://localhost:8888 | (intentionally fake) |
Open a separate terminal while services are running:
# Start the unified orchestrator (handles auto-healing and auto-scaling)
python3 scripts/orchestrator.py# Stop and remove containers (keeps images)
podman-compose down
# Stop, remove containers AND clean volumes
podman-compose down -v
# Remove all built images too
podman-compose down --rmi allPodflow/
βββ π podman-compose.yml # Orchestration definition for all services
βββ π setup.sh # One-shot environment bootstrap script
β
βββ π services/
β βββ π api-gateway/ # Node.js API Gateway (public entry point)
β β βββ app.js # Express routes + Prometheus metrics
β β βββ index.js # Server entrypoint
β β βββ metrics.js # Custom metric definitions
β β βββ Dockerfile
β β
β βββ π user-service/ # Node.js User Management Service
β β βββ app.js # User routes + metrics
β β βββ index.js
β β βββ Dockerfile
β β
β βββ π backend/ # Node.js Core Backend Service
β β βββ index.js
β β βββ Dockerfile
β β
β βββ π data-service/ # Python Data Layer
β β βββ app.py
β β
β βββ π honeypot/ # Python Security Honeypot
β βββ honeypot.py # Fake SSH + HTTP trap server
β βββ Dockerfile
β βββ Deployment.yaml # K8s-style deployment spec
β
βββ π monitoring/
β βββ π prometheus/
β β βββ prometheus.yml # Scrape configs for all services
β βββ π grafana/
β βββ datasource.yml # Prometheus datasource provisioning
β βββ dashboards.yaml # Dashboard auto-provisioning
β βββ π dashboards/ # Pre-built Grafana dashboard JSONs
β
βββ π network/
β βββ Policies.yaml # Calico Zero-Trust network policies
β
βββ π scripts/
βββ orchestrator.py # Unified Auto-Heal & Auto-Scale Daemon
Returns the gateway health status.
curl http://localhost:8080/health{ "status": "UP", "service": "api-gateway" }Fetches the user list from the User Service (proxied through gateway).
curl http://localhost:8080/api/users{
"users": [
{ "id": 1, "name": "Alice" },
{ "id": 2, "name": "Bob" }
]
}Prometheus-compatible metrics endpoint (for scraping).
curl http://localhost:8080/metrics| Layer | Technology | Purpose |
|---|---|---|
| Container Runtime | Podman + podman-compose | Rootless container orchestration |
| API Gateway | Node.js, Express | Request routing & proxying |
| User Service | Node.js, Express | User management API |
| Backend | Node.js | Core business logic |
| Data Service | Python (Flask) | Data layer |
| Security | Python (Flask, Sockets) | Honeypot & intrusion detection |
| Metrics | Prometheus Client (Node + Python) | Metrics exposition |
| Monitoring | Prometheus | Metrics collection & alerting |
| Dashboards | Grafana | Visualization |
| Network Security | Calico CNI Policies | Zero-Trust segmentation |
| Automation | Python | Auto-Heal & Auto-Scale |
Contributions are welcome! Here's how to get started:
- Fork the repository
- Clone your fork:
git clone https://github.com/your-username/Podflow.git - Create a branch:
git checkout -b feature/your-feature-name - Make your changes and commit with a clear message:
git commit -m "feat: add XYZ feature" - Push to your fork:
git push origin feature/your-feature-name - Open a Pull Request with a detailed description of your changes
This project follows Conventional Commits:
feat: New feature
fix: Bug fix
docs: Documentation changes
refactor: Code refactoring
chore: Maintenance tasks
- API Gateway with Prometheus metrics
- User Service with request counters
- Honeypot with SSH + HTTP traps
- Prometheus + Grafana monitoring stack
- Calico Zero-Trust network policies
- Auto-Heal and Auto-Scale scripts
- Alertmanager integration for critical alerts
- Distributed tracing with Jaeger/Tempo
- JWT authentication at the API Gateway
- Kubernetes deployment manifests (Helm chart)
- CI/CD pipeline with GitHub Actions
- HTTPS/TLS termination at the gateway
- Rate limiting and DDoS protection layer
- Podman β Daemonless, rootless containers
- Prometheus β Open-source monitoring & alerting
- Grafana β The open observability platform
- Calico β Zero-Trust networking for containers
- Express.js β Fast, minimalist Node.js web framework
- Flask β Lightweight Python web framework
Built with β€οΈ β PodFlow
If you found this useful, please β star the repo!