Skip to content
pking-hecsPublic

About

No description, website, or topics provided.

Resources

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

Β 

History

40 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation


β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•—  β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•— β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•— β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•—β–ˆβ–ˆβ•—      β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•— β–ˆβ–ˆβ•—    β–ˆβ–ˆβ•—
β–ˆβ–ˆβ•”β•β•β–ˆβ–ˆβ•—β–ˆβ–ˆβ•”β•β•β•β–ˆβ–ˆβ•—β–ˆβ–ˆβ•”β•β•β–ˆβ–ˆβ•—β–ˆβ–ˆβ•”β•β•β•β•β•β–ˆβ–ˆβ•‘     β–ˆβ–ˆβ•”β•β•β•β–ˆβ–ˆβ•—β–ˆβ–ˆβ•‘    β–ˆβ–ˆβ•‘
β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•”β•β–ˆβ–ˆβ•‘   β–ˆβ–ˆβ•‘β–ˆβ–ˆβ•‘  β–ˆβ–ˆβ•‘β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•—  β–ˆβ–ˆβ•‘     β–ˆβ–ˆβ•‘   β–ˆβ–ˆβ•‘β–ˆβ–ˆβ•‘ β–ˆβ•— β–ˆβ–ˆβ•‘
β–ˆβ–ˆβ•”β•β•β•β• β–ˆβ–ˆβ•‘   β–ˆβ–ˆβ•‘β–ˆβ–ˆβ•‘  β–ˆβ–ˆβ•‘β–ˆβ–ˆβ•”β•β•β•  β–ˆβ–ˆβ•‘     β–ˆβ–ˆβ•‘   β–ˆβ–ˆβ•‘β–ˆβ–ˆβ•‘β–ˆβ–ˆβ–ˆβ•—β–ˆβ–ˆβ•‘
β–ˆβ–ˆβ•‘     β•šβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•”β•β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•”β•β–ˆβ–ˆβ•‘     β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•—β•šβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•”β•β•šβ–ˆβ–ˆβ–ˆβ•”β–ˆβ–ˆβ–ˆβ•”β•
β•šβ•β•      β•šβ•β•β•β•β•β• β•šβ•β•β•β•β•β• β•šβ•β•     β•šβ•β•β•β•β•β•β• β•šβ•β•β•β•β•β•  β•šβ•β•β•β•šβ•β•β•

Production-Grade Containerized Microservices Platform

Zero-Trust Security Β· Auto-Healing Β· Auto-Scaling Β· Full Observability


Podman Node.js Python Prometheus Grafana Flask

Status PRs Welcome


πŸ“– Overview

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.


πŸ—οΈ Architecture

                          β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                          β”‚                  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 Topology

Network Purpose Members
public_net External-facing traffic API Gateway
service_net Internal service mesh Gateway, User-Service, Backend, Prometheus, Grafana, Honeypot

🧩 Microservices

🌐 API Gateway

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

πŸ‘€ User Service

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

πŸ—„οΈ Backend Service

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


πŸ“ Data Service

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.


🍯 Honeypot Service

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 access

πŸ“Š Monitoring & Observability

PodFlow ships with a full observability stack out of the box.

Prometheus

monitoring/prometheus/ Β· Port 9090

Scrapes metrics from all services:

  • gateway_http_requests_total β€” API Gateway request volume
  • http_requests_total β€” User Service request volume
  • honeypot_intrusion_attempts_total β€” Security events
  • process_cpu_seconds_total β€” CPU usage per service
  • process_resident_memory_bytes β€” Memory usage per service

Grafana

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)


πŸ” Zero-Trust Network Security

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)

βš™οΈ Auto-Healing & Auto-Scaling (scripts/orchestrator.py)

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 exceeds 70%, it dynamically scales up a new replica (max 3) and adds it to the internal network load-balancing. If CPU usage drops below 30%, it scales down.

πŸš€ Getting Started

Prerequisites

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

πŸ“₯ Clone the Repository

git clone https://github.com/your-username/Podflow.git
cd Podflow

πŸ”§ Build & Start All Services

# Build all container images and start every service
podman-compose up --build

This single command will:

  1. Build Docker/Podman images for all microservices
  2. Create the public_net and service_net bridge networks
  3. Start all 6 services: API Gateway, User Service, Backend, Data Service, Prometheus, Grafana, and Honeypot
  4. Attach health checks and restart policies

βœ… Verify Services Are Running

# Check all running containers
podman ps

# Check compose service status
podman-compose ps

Expected 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

🌍 Access the Platform

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)

πŸ” Running the Orchestration Script

Open a separate terminal while services are running:

# Start the unified orchestrator (handles auto-healing and auto-scaling)
python3 scripts/orchestrator.py

πŸ›‘ Stopping Services

# 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 all

πŸ—‚οΈ Project Structure

Podflow/
β”œβ”€β”€ πŸ“„ 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

πŸ”Œ API Reference

API Gateway β€” localhost:8080

GET /health

Returns the gateway health status.

curl http://localhost:8080/health
{ "status": "UP", "service": "api-gateway" }

GET /api/users

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" }
  ]
}

GET /metrics

Prometheus-compatible metrics endpoint (for scraping).

curl http://localhost:8080/metrics

πŸ› οΈ Tech Stack

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

🀝 Contributing

Contributions are welcome! Here's how to get started:

  1. Fork the repository
  2. Clone your fork: git clone https://github.com/your-username/Podflow.git
  3. Create a branch: git checkout -b feature/your-feature-name
  4. Make your changes and commit with a clear message: git commit -m "feat: add XYZ feature"
  5. Push to your fork: git push origin feature/your-feature-name
  6. Open a Pull Request with a detailed description of your changes

Commit Convention

This project follows Conventional Commits:

feat:     New feature
fix:      Bug fix
docs:     Documentation changes
refactor: Code refactoring
chore:    Maintenance tasks

πŸ—ΊοΈ Roadmap

  • 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

πŸ™ Acknowledgements

  • 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!

About

No description, website, or topics provided.

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages