Kubernetes Deployment
Relevant source files
The following files were used as context for generating this wiki page:
The Kubernetes (K8s) deployment for ClassMate provides a production-grade orchestration environment designed for high availability and scalability. It serves as the primary production infrastructure, transitioning the application from local Docker Compose environments to a managed cluster capable of supporting over 100,000 users through a hybrid scalable architecture.
The deployment focuses on containerizing the FastAPI backend, managing stateful services like PostgreSQL and Redis, and handling traffic via an Ingress controller. It integrates with the broader project infrastructure, which includes Terraform for cloud provisioning and shell scripts for deployment verification.
Sources: infra/README.md:38-42, README.md:5-9, PROJECT_STRUCTURE.md:154-159
Core Components and Architecture
The Kubernetes infrastructure is organized within a dedicated classmate namespace to ensure resource isolation. The architecture separates the application logic from data persistence and caching layers.
Infrastructure Overview
The deployment consists of three primary service layers:
- Application Layer: Contains the
classmate-api, which runs the FastAPI backend. - Data Layer: Includes a PostgreSQL deployment for persistent data storage.
- Caching/Messaging Layer: Utilizes Redis to support Celery background workers.
This diagram illustrates the traffic flow from the external user through the Ingress controller to the API pods and their subsequent connections to the data layer.
Sources: infra/k8s/api.yaml:1-71, infra/README.md:44-55
API Deployment Configuration
The classmate-api is the central component of the Kubernetes cluster. It is configured as a Deployment with multiple replicas to ensure redundancy and availability.
Resource Management and Probes
To maintain stability, the API containers are restricted by CPU and memory limits. Additionally, Kubernetes uses liveness and readiness probes to monitor the health of the FastAPI application.
| Configuration Item | Value | Description |
|---|---|---|
| Replicas | 2 | Number of concurrent pods running the API |
| Image | classmate/api:latest | The container image used for the backend |
| Memory Request | 256Mi | Initial memory allocated to each pod |
| Memory Limit | 512Mi | Maximum memory a pod can consume |
| CPU Request | 250m | 0.25 vCPU allocated initially |
| CPU Limit | 500m | Maximum 0.5 vCPU limit |
| Liveness Path | /health | Endpoint checked to see if container is alive |
| Readiness Path | /health | Endpoint checked to see if container is ready for traffic |
Sources: infra/k8s/api.yaml:1-45
Networking and Ingress
The API is exposed internally via a ClusterIP service and externally through an Nginx Ingress controller.
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: classmate-ingress
namespace: classmate
annotations:
nginx.ingress.kubernetes.io/rewrite-target: /
spec:
rules:
- host: classmate.local
http:
paths:
- path: /api
pathType: Prefix
backend:
service:
name: classmate-api
port:
number: 8000
Sources: infra/k8s/api.yaml:61-89
Deployment Workflow and Management
Deploying the ClassMate stack to Kubernetes involves a sequential application of manifests. Users must have kubectl configured and Helm 3 installed as prerequisites.
Deployment Sequence
- Namespace Creation: Establish the
classmatenamespace for isolation. - Infrastructure Services: Deploy the
postgres.yamlandredis.yamlmanifests first to ensure the data layer is available. - Application Services: Deploy
api.yamlto launch the backend logic. - Verification: Use
kubectl get pods -n classmateor theverify_deployment.shscript to confirm status.
Sources: infra/README.md:44-55, scripts/verify_deployment.sh:1-25
Scaling and Maintenance
Kubernetes allows for both horizontal and vertical scaling of the API.
- Horizontal Scaling: Increased by modifying replicas:
kubectl scale deployment classmate-api --replicas=5 -n classmate. - Monitoring: Resource usage is tracked via
kubectl top pods -n classmate. - Cleanup: The entire environment can be removed by deleting the namespace:
kubectl delete namespace classmate.
Sources: infra/README.md:105-107, infra/README.md:139-141
Connectivity and Secrets
The API deployment relies on environment variables to connect to other services within the cluster. Currently, these are defined directly in the manifest, though security guidelines suggest using Kubernetes Secrets for production environments.
- DATABASE_URL:
postgresql://classmate:classmate123@postgres:5432/classmate - REDIS_URL:
redis://redis:6379/0
Sources: infra/k8s/api.yaml:23-26, infra/README.md:92-95
Conclusion
The Kubernetes deployment for ClassMate provides a robust framework for hosting the AI-powered meeting assistant in a production environment. By utilizing deployments for the API and dedicated services for the database and cache, the system achieves the "Hybrid Scalable Architecture" required for large-scale user adoption. The inclusion of liveness probes and resource limits ensures the backend remains resilient under heavy AI processing workloads.