Kubernetes Deployment Guide
Relevant source files
The following files were used as context for generating this wiki page:
The Memory Context Browser (MCB) is designed to run in a Kubernetes environment to provide a high-performance, scalable MCP server for AI coding agents. This guide details the infrastructure, configuration, and operational procedures for deploying MCB into a cluster, including its auto-scaling capabilities and dependency management.
Sources: README.md:1-12, k8s/README.md:1-5
Infrastructure Architecture
The MCB Kubernetes deployment follows a standard microservices pattern, utilizing Ingress for external access, Services for internal load balancing, and Deployments for managing the application life cycle. The system is designed for high availability with a minimum of 2 replicas and horizontal auto-scaling (HPA).
The diagram shows the traffic flow from the internet through the ingress and internal service to the horizontally scaled application pods, which connect to various data backends.
Sources: k8s/README.md:17-25, k8s/deployment.yaml:12-23
Deployment Components
The deployment utilizes several Kubernetes primitives to ensure security, observability, and reliability.
| Component | Description |
|---|---|
| Deployment | Manages mcb pods with rolling update strategy (maxSurge: 1, maxUnavailable: 0). |
| HPA | Auto-scaling based on CPU (70%), Memory (80%), and custom request metrics. |
| Ingress | Exposes the API and metrics endpoints externally via NGINX. |
| RBAC | Provides a ServiceAccount with minimal permissions for pod execution. |
| NetworkPolicy | Controls ingress/egress traffic for network security. |
| ServiceMonitor | Integrates with Prometheus Operator for automated metric scraping. |
Sources: k8s/README.md:27-38, k8s/README.md:73-81, k8s/deployment.yaml:13-21, k8s/deploy.sh:31-64
Configuration and Secrets
Configuration is managed through environment variables injected from ConfigMaps and Secrets. The application requires several sensitive credentials to interact with external providers and databases.
Key Environment Variables
| Variable | Source | Description |
|---|---|---|
MCP__SERVER__NETWORK__PORT | Literal | Internal container port (default 3000). |
MCP_DATABASE_URL | Secret | Connection string for PostgreSQL metadata storage. |
MCP__SYSTEM__INFRASTRUCTURE__CACHE__REDIS_URL | Secret | URL for Redis distributed caching. |
MCP_VECTOR_STORE_TYPE | Literal | Set to encrypted with milvus as inner type. |
MCP_OPENAI_API_KEY | Secret | API key for OpenAI embedding provider. |
Sources: k8s/deployment.yaml:50-100, k8s/kustomization.yaml:38-65
Resource Management
The deployment defines specific resource requests and limits to ensure stability and allow the HPA to function correctly.
- Requests: 500m CPU, 1Gi Memory
- Limits: 2000m CPU, 4Gi Memory
Sources: k8s/deployment.yaml:113-118, k8s/README.md:83-87
Deployment Procedure
Deploying MCB requires preparing the environment, installing dependencies, and applying the application manifests.
Step-by-Step Flow
The sequence illustrates the manual or scripted deployment steps starting from namespace creation to dependency installation and final verification.
Sources: k8s/deploy.sh:10-75, k8s/README.md:46-67
Manual Deployment Script
The project includes a deploy.sh script that automates the application of all necessary manifests in the correct order:
- Namespace creation
- RBAC (rbac.yaml)
- ConfigMaps and Secrets
- Services and Deployment
- HorizontalPodAutoscaler (hpa.yaml)
- Security and Monitoring (networkpolicy.yaml, poddisruptionbudget.yaml, servicemonitor.yaml)
Sources: k8s/deploy.sh:13-58
Health and Monitoring
MCB exposes health checks and Prometheus metrics to ensure high availability and visibility into system performance.
- Liveness/Readiness/Startup Probes: All use the
/api/aliveendpoint on port 3000. - Metrics Endpoint: Scraped by Prometheus via
/api/context/metricsor/metrics. - Security Context: Pods run as non-root (UID 10001) with a read-only root filesystem for enhanced security.
Sources: k8s/deployment.yaml:119-152, k8s/README.md:89-94, k8s/deployment.yaml:33-47
Summary
The Kubernetes deployment for MCB provides a robust, production-ready environment. By utilizing HPA, strict resource limits, and extensive dependency integration (Redis, PostgreSQL, Milvus), the system can scale dynamically based on workload. Security is enforced through non-root execution and NetworkPolicies, while observability is handled via native Prometheus integration.
Sources: k8s/README.md:1-125, k8s/deployment.yaml:1-170