Kubernetes Deployment Guide

Framework M is optimized for Kubernetes deployment using its built-in liveness and readiness probes. This guide provides reference patterns for standard and custom deployments.

1. Core Manifests

Deployment

The primary way to deploy the Framework M modular monolith.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: framework-m-backend
spec:
  replicas: 3
  selector:
    matchLabels:
      app: framework-m
  template:
    metadata:
      labels:
        app: framework-m
    spec:
      containers:
      - name: backend
        image: registry.example.com/framework-m:latest
        ports:
        - containerPort: 8888
        envFrom:
        - configMapRef:
            name: framework-m-config
        - secretRef:
            name: framework-m-secrets
        
        # Probes
        livenessProbe:
          httpGet:
            path: /health
            port: 8888
          initialDelaySeconds: 5
          periodSeconds: 30
        
        readinessProbe:
          httpGet:
            path: /ready
            port: 8888
          initialDelaySeconds: 10
          periodSeconds: 15
        
        resources:
          requests:
            cpu: "500m"
            memory: "512Mi"
          limits:
            cpu: "1000m"
            memory: "1Gi"

Probes Explained

• /health (Liveness): Checks basic connectivity (DB, Cache). If this fails, K8s restarts the container.

• /ready (Readiness): Checks if the application is fully ready to serve traffic. By default, it verifies database and Redis connectivity (if configured). This ensures basic service health without introducing database migration status race conditions during rolling deployments.

  Custom Readiness Checks

  If you need to verify database migrations or check other application-specific dependencies (such as external APIs or system state), you can extend the readiness check using the standard entry point system.

  Register your custom readiness check under the framework_m.readiness entry-point group in your pyproject.toml:

  [project.entry-points."framework_m.readiness"]
  check_migrations = "my_app.probes:check_migrations_ready"

  The plugin function can be synchronous or asynchronous, takes request (the litestar.Request object) as its parameter, and should return True (or None) if healthy, or False (or raise an exception) if not ready.

2. Configuration & Secrets

ConfigMap

Store non-sensitive environment variables.

apiVersion: v1
kind: ConfigMap
metadata:
  name: framework-m-config
data:
  FRAMEWORK_MODE: "MACROSERVICE"
  FRAMEWORK_API_VERSION: "v1"
  INSTALLED_APPS: "app1,app2,plugin_wms"
  DATABASE_URL: "postgresql+asyncpg://user@postgres-service:5432/dbname"

Secret

Store sensitive information like JWT secrets or passwords.

apiVersion: v1
kind: Secret
metadata:
  name: framework-m-secrets
type: Opaque
data:
  FRAMEWORK_M_JWT_SECRET: <base64-encoded-secret>

3. Scaling Strategy

Horizontal Pod Autoscaler (HPA)

Framework M is stateless, making it easy to scale based on resource consumption.

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: framework-m-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: framework-m-backend
  minReplicas: 3
  maxReplicas: 10
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70

4. Custom App Combinations

In Kubernetes, you can deploy different combinations of apps as separate Deployments if you need isolated scaling (e.g., a "Sales" deployment vs a "WMS" deployment), even if they share the same Docker image. Simply vary the INSTALLED_APPS and PORT in each Deployment manifest.