Kubernetes Deployment

Kubernetes support for Magic Runtime — current status and roadmap.

Current Status

In Development

Kubernetes Support

Current deployment model: Docker Compose is the officially supported, production-ready deployment method. See the Deploy Center for packages and guides.

Kubernetes: A Helm chart is planned for the v2.4 Platform release (Q4 2026), per the Enterprise Standards roadmap. Container images are already compatible with any OCI-compliant orchestrator.

What's Ready Today

While the official Helm chart is in development, several components are already Kubernetes-compatible.

Docker Compose Production Deploy

Complete, tested stack with Nginx, PostgreSQL, and Redis. Download now.

OCI-Compatible Container Images

All images follow OCI standards and run on any container orchestrator, including Kubernetes.

Health Endpoints for Probes

/api/health for liveness and /api/readyz for readiness, ready for k8s probe configuration.

Prometheus Metrics

Metrics exposed at /metrics in Prometheus format for monitoring and alerting.

Stateless Runtime Architecture

Horizontally scalable with external PostgreSQL and Redis. No local state to manage.

Structured JSON Logging

All logs are structured JSON with correlation IDs, compatible with any log aggregation pipeline.

Kubernetes Roadmap

v2.0
Now
Docker Compose Production Deploy
  • Complete production stack with Nginx, PostgreSQL, Redis
  • OCI-compatible container images work on any orchestrator
  • Health and readiness endpoints for k8s probes
  • Stateless runtime architecture supports horizontal scaling
v2.4
Q4 2026
Official Helm Chart
  • Helm chart with configurable values.yaml
  • NetworkPolicies matching the Magic egress control model
  • Resource limits derived from controller contract declarations
  • PodDisruptionBudgets and anti-affinity rules
  • Ingress resource with TLS termination
  • Official container images on GitHub Container Registry (ghcr.io)
v2.4+
2027
Kubernetes Operator
  • Custom Resource Definitions (CRDs) for Magic controllers
  • Auto-scaling based on controller execution load
  • Rolling deployments with contract validation gates
  • High-availability deployment guidance document
Future
2027+
Advanced Orchestration
  • Service mesh integration (Istio, Linkerd) for mTLS between services
  • Multi-cluster support for geo-distributed deployments
  • GitOps-native deployment workflows (ArgoCD, Flux)

Running Magic on Kubernetes Today

You can deploy the Magic Runtime on Kubernetes today using manual manifests or by converting the Docker Compose file with kompose. This approach is community/self-supported until the official Helm chart ships in v2.4.

Community-Supported

The manifests below are provided as a starting point. They are not yet covered by official support. For production Kubernetes deployments, consider waiting for the v2.4 Helm chart or contact enterprise support (enterprise@threadsync.io) for guided assistance.

magic-api Deployment + Service

# magic-api-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: magic-api
  labels:
    app: magic-api
spec:
  replicas: 2
  selector:
    matchLabels:
      app: magic-api
  template:
    metadata:
      labels:
        app: magic-api
    spec:
      containers:
        - name: magic-api
          image: ghcr.io/threadsync/magic-api:2.0.0
          ports:
            - containerPort: 8000
          env:
            - name: DATABASE_URL
              valueFrom:
                secretKeyRef:
                  name: magic-secrets
                  key: database-url
            - name: REDIS_URL
              value: "redis://magic-redis:6379"
          livenessProbe:
            httpGet:
              path: /api/health
              port: 8000
            initialDelaySeconds: 10
            periodSeconds: 15
            failureThreshold: 3
          readinessProbe:
            httpGet:
              path: /api/readyz
              port: 8000
            initialDelaySeconds: 5
            periodSeconds: 10
            failureThreshold: 3
          resources:
            requests:
              cpu: "250m"
              memory: "512Mi"
            limits:
              cpu: "1000m"
              memory: "2Gi"
---
apiVersion: v1
kind: Service
metadata:
  name: magic-api
spec:
  selector:
    app: magic-api
  ports:
    - port: 8000
      targetPort: 8000
  type: ClusterIP

magic-web Deployment + Service

# magic-web-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: magic-web
  labels:
    app: magic-web
spec:
  replicas: 2
  selector:
    matchLabels:
      app: magic-web
  template:
    metadata:
      labels:
        app: magic-web
    spec:
      containers:
        - name: magic-web
          image: ghcr.io/threadsync/magic-web:2.0.0
          ports:
            - containerPort: 80
          livenessProbe:
            httpGet:
              path: /
              port: 80
            periodSeconds: 30
          resources:
            requests:
              cpu: "100m"
              memory: "128Mi"
            limits:
              cpu: "500m"
              memory: "256Mi"
---
apiVersion: v1
kind: Service
metadata:
  name: magic-web
spec:
  selector:
    app: magic-web
  ports:
    - port: 80
      targetPort: 80
  type: ClusterIP

magic-redis Deployment + Service

# magic-redis-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: magic-redis
  labels:
    app: magic-redis
spec:
  replicas: 1
  selector:
    matchLabels:
      app: magic-redis
  template:
    metadata:
      labels:
        app: magic-redis
    spec:
      containers:
        - name: redis
          image: redis:7-alpine
          ports:
            - containerPort: 6379
          resources:
            requests:
              cpu: "100m"
              memory: "128Mi"
            limits:
              cpu: "500m"
              memory: "512Mi"
---
apiVersion: v1
kind: Service
metadata:
  name: magic-redis
spec:
  selector:
    app: magic-redis
  ports:
    - port: 6379
      targetPort: 6379
  type: ClusterIP

Probe Configuration Details

The Magic API exposes two health endpoints designed for Kubernetes probes:

EndpointPurposeProbe TypeBehavior
/api/health Process health Liveness Returns 200 if the API process is running. Does not check dependencies.
/api/readyz Ready to serve Readiness Returns 200 only when database and Redis connections are established.
/metrics Prometheus metrics Scrape target Exposes request counts, latencies, controller execution stats, and queue depth.

Using kompose

You can also convert the official docker-compose.yml directly to Kubernetes manifests using kompose. Run kompose convert -f docker-compose.yml in the extracted Production Stack directory. Review and adjust the generated manifests before applying to your cluster.

Get Notified When Kubernetes Support Ships

Want to be the first to know when the official Helm chart and Kubernetes operator are released? Reach out and we will keep you in the loop.

enterprise@threadsync.io