https://github.com/varunramagiri/python-microservices-framework
Async FastAPI template with JWT/RBAC, Redis rate limiting, circuit breakers, Prometheus, OpenTelemetry, Kubernetes HPA and Terraform IaC
https://github.com/varunramagiri/python-microservices-framework
async docker fastapi jwt kubernetes microservices observability opentelemetry prometheus python rest-api terraform
Last synced: 13 days ago
JSON representation
Async FastAPI template with JWT/RBAC, Redis rate limiting, circuit breakers, Prometheus, OpenTelemetry, Kubernetes HPA and Terraform IaC
- Host: GitHub
- URL: https://github.com/varunramagiri/python-microservices-framework
- Owner: varunramagiri
- License: mit
- Created: 2026-05-23T14:40:08.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-05-23T14:42:50.000Z (about 1 month ago)
- Last Synced: 2026-05-23T16:24:54.021Z (about 1 month ago)
- Topics: async, docker, fastapi, jwt, kubernetes, microservices, observability, opentelemetry, prometheus, python, rest-api, terraform
- Size: 10.7 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ⚡ Python Microservices Framework
> **Production-grade async FastAPI microservices template** — JWT Auth · Rate Limiting · Circuit Breakers · Redis Caching · Kubernetes · Terraform · Observability — zero-boilerplate for new services
[](https://python.org)
[](https://fastapi.tiangolo.com)
[](https://docker.com)
[](https://kubernetes.io)
[](LICENSE)
---
## 🎯 Overview
A battle-tested FastAPI microservices starter — built from backend patterns deployed at **Nationwide Mutual Insurance**, **CVS Health**, and **Gap Inc.** — that gives every new service authentication, observability, resilience patterns, and cloud deployment on day one.
**What you get out of the box:**
- Async FastAPI with proper lifespan management and dependency injection
- JWT + OAuth2 authentication with role-based access control (RBAC)
- Redis-backed rate limiting and distributed caching
- Circuit breaker pattern for downstream service calls
- Structured logging (structlog) + Prometheus metrics + distributed tracing (OpenTelemetry)
- Health checks, readiness/liveness probes
- Kubernetes manifests with HPA and Terraform infrastructure
- Full CI/CD pipeline via GitHub Actions
---
## 📁 Folder Structure
```
python-microservices-framework/
├── app/
│ ├── main.py # FastAPI lifespan, middleware, router mount
│ ├── api/
│ │ ├── v1/
│ │ │ ├── router.py # API v1 route aggregator
│ │ │ ├── health.py # /health, /readiness, /liveness
│ │ │ ├── auth.py # /auth/token, /auth/refresh, /auth/logout
│ │ │ └── resources.py # Your domain endpoints go here
│ │ └── deps.py # Shared FastAPI dependencies (auth, db, cache)
│ ├── core/
│ │ ├── config.py # Pydantic settings (env-driven)
│ │ ├── security.py # JWT creation, validation, password hashing
│ │ ├── database.py # SQLAlchemy async engine + session factory
│ │ └── redis.py # Async Redis client factory
│ ├── middleware/
│ │ ├── auth_middleware.py # JWT extraction + RBAC enforcement
│ │ ├── rate_limiter.py # Token bucket rate limiting (Redis)
│ │ ├── circuit_breaker.py # Circuit breaker (pybreaker)
│ │ ├── request_id.py # X-Request-ID propagation
│ │ └── cors.py # CORS configuration
│ ├── models/
│ │ ├── base.py # SQLAlchemy base with UUID PK, timestamps
│ │ ├── user.py
│ │ └── audit_log.py
│ ├── schemas/
│ │ ├── base.py # Shared Pydantic response schemas
│ │ ├── auth.py # Token request/response schemas
│ │ └── pagination.py # Cursor-based pagination schema
│ ├── services/
│ │ ├── auth_service.py # Business logic: auth, token management
│ │ └── cache_service.py # Cache-aside pattern with TTL management
│ └── observability/
│ ├── metrics.py # Prometheus: request count, latency, errors
│ ├── logging.py # structlog JSON config
│ └── tracing.py # OpenTelemetry auto-instrumentation
├── tests/
│ ├── conftest.py # pytest fixtures: test app, async client, db
│ ├── unit/
│ │ ├── test_auth.py
│ │ ├── test_rate_limiter.py
│ │ └── test_circuit_breaker.py
│ └── integration/
│ ├── test_auth_flow.py
│ └── test_api_endpoints.py
├── infra/
│ ├── terraform/
│ │ ├── main.tf # EKS cluster + RDS + ElastiCache
│ │ ├── variables.tf
│ │ └── outputs.tf
│ └── k8s/
│ ├── namespace.yaml
│ ├── deployment.yaml
│ ├── service.yaml
│ ├── ingress.yaml
│ ├── hpa.yaml # HorizontalPodAutoscaler
│ ├── configmap.yaml
│ └── secrets-external.yaml # AWS Secrets Manager external secrets
├── scripts/
│ ├── generate_service.py # Scaffold a new microservice from template
│ └── load_test.py # Locust load test scenarios
├── .github/
│ └── workflows/
│ ├── ci.yml # Lint + test + coverage + security scan
│ └── cd.yml # Build + push + deploy to EKS
├── Dockerfile
├── docker-compose.yml # Full local stack: app + postgres + redis
├── alembic.ini
├── pyproject.toml
├── requirements.txt
└── README.md
```
---
## ⚡ Quick Start
```bash
# Clone
git clone https://github.com/varunramagiri/python-microservices-framework.git
cd python-microservices-framework
# Scaffold a new service from this template
python scripts/generate_service.py --name my-new-service --output ../my-new-service
# Start full local stack
docker compose up --build
# Run tests with coverage
pytest tests/ -v --cov=app --cov-report=html
# Access API docs
open http://localhost:8000/docs
```
---
## 🔑 Key Patterns
### Async endpoint with auth, caching, and circuit breaker
```python
from fastapi import APIRouter, Depends
from app.api.deps import require_role, get_cache
from app.middleware.circuit_breaker import breaker
router = APIRouter()
@router.get("/claims/{claim_id}")
@breaker # Trips after 5 failures in 60s; half-open after 30s
async def get_claim(
claim_id: str,
current_user = Depends(require_role("claims:read")),
cache = Depends(get_cache),
):
# Check cache first (cache-aside pattern)
cached = await cache.get(f"claim:{claim_id}")
if cached:
return cached
# Fetch from downstream (circuit breaker protects this)
claim = await claims_service.get(claim_id)
await cache.set(f"claim:{claim_id}", claim, ttl=300)
return claim
```
### Rate limiter middleware
```python
# config/settings.yml
rate_limiting:
default: "100/minute"
auth_endpoints: "10/minute"
ai_inference: "20/minute"
```
---
## 📊 Observability
Every request auto-emits:
- `http_requests_total{method, endpoint, status}` — Prometheus counter
- `http_request_duration_seconds{method, endpoint}` — Prometheus histogram
- Structured JSON log: `{"request_id": "...", "user_id": "...", "latency_ms": 42, ...}`
- OpenTelemetry trace span (Jaeger / AWS X-Ray)
```bash
# View Grafana dashboard (local)
open http://localhost:3000
```
---
## 🚀 Deploy to Kubernetes
```bash
# Provision EKS + RDS + ElastiCache
cd infra/terraform && terraform apply
# Deploy application
kubectl apply -f infra/k8s/
# Check rollout
kubectl rollout status deployment/api -n production
```
---
## 📄 License
MIT — see [LICENSE](LICENSE)
*Backend patterns from 10+ years of production Python services across fintech, healthcare, insurance, and retail.*