Skip to Content
DeploymentKubernetes

Kubernetes Deployment

Deploy the NAICS MCP Server to Kubernetes for production workloads.

Prerequisites

  • Kubernetes 1.19+
  • kubectl configured
  • Helm 3 (optional)

Quick Start

Apply the manifests:

kubectl apply -f https://raw.githubusercontent.com/mfbaig35r/naics-mcp-server/main/k8s/namespace.yaml
kubectl apply -f https://raw.githubusercontent.com/mfbaig35r/naics-mcp-server/main/k8s/

Manifests

Namespace

# namespace.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: naics-mcp
  labels:
    app.kubernetes.io/name: naics-mcp

Deployment

# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: naics-mcp-server
  namespace: naics-mcp
  labels:
    app: naics-mcp-server
spec:
  replicas: 2
  selector:
    matchLabels:
      app: naics-mcp-server
  template:
    metadata:
      labels:
        app: naics-mcp-server
    spec:
      containers:
        - name: naics-mcp-server
          image: ghcr.io/mfbaig35r/naics-mcp-server:latest
          ports:
            - containerPort: 9090
              name: http
          env:
            - name: NAICS_HOST
              value: "0.0.0.0"
            - name: NAICS_PORT
              value: "9090"
            - name: NAICS_LOG_LEVEL
              value: "INFO"
          resources:
            requests:
              memory: "512Mi"
              cpu: "250m"
            limits:
              memory: "1Gi"
              cpu: "1000m"
          livenessProbe:
            httpGet:
              path: /health
              port: 9090
            initialDelaySeconds: 10
            periodSeconds: 10
            timeoutSeconds: 5
            failureThreshold: 3
          readinessProbe:
            httpGet:
              path: /ready
              port: 9090
            initialDelaySeconds: 30
            periodSeconds: 5
            timeoutSeconds: 5
            failureThreshold: 3
          startupProbe:
            httpGet:
              path: /ready
              port: 9090
            initialDelaySeconds: 10
            periodSeconds: 5
            failureThreshold: 30

Service

# service.yaml
apiVersion: v1
kind: Service
metadata:
  name: naics-mcp-server
  namespace: naics-mcp
  labels:
    app: naics-mcp-server
spec:
  type: ClusterIP
  ports:
    - port: 9090
      targetPort: 9090
      protocol: TCP
      name: http
  selector:
    app: naics-mcp-server

Ingress

# ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: naics-mcp-server
  namespace: naics-mcp
  annotations:
    kubernetes.io/ingress.class: nginx
spec:
  rules:
    - host: naics.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: naics-mcp-server
                port:
                  number: 9090

ConfigMap

# configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: naics-mcp-config
  namespace: naics-mcp
data:
  NAICS_LOG_LEVEL: "INFO"
  NAICS_HOST: "0.0.0.0"
  NAICS_PORT: "9090"

PersistentVolumeClaim

For workbook persistence:

# pvc.yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: naics-mcp-data
  namespace: naics-mcp
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi

Update deployment to use PVC:

volumes:
  - name: data
    persistentVolumeClaim:
      claimName: naics-mcp-data
containers:
  - name: naics-mcp-server
    volumeMounts:
      - name: data
        mountPath: /app/data

Horizontal Pod Autoscaler

# hpa.yaml
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: naics-mcp-server
  namespace: naics-mcp
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: naics-mcp-server
  minReplicas: 2
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70
    - type: Resource
      resource:
        name: memory
        target:
          type: Utilization
          averageUtilization: 80

Prometheus ServiceMonitor

For metrics collection:

# servicemonitor.yaml
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: naics-mcp-server
  namespace: naics-mcp
spec:
  selector:
    matchLabels:
      app: naics-mcp-server
  endpoints:
    - port: http
      path: /metrics
      interval: 30s

Network Policy

Restrict network access:

# networkpolicy.yaml
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: naics-mcp-server
  namespace: naics-mcp
spec:
  podSelector:
    matchLabels:
      app: naics-mcp-server
  policyTypes:
    - Ingress
  ingress:
    - from:
        - namespaceSelector:
            matchLabels:
              name: ingress-nginx
      ports:
        - protocol: TCP
          port: 9090

Operations

Check Status

# Pod status
kubectl get pods -n naics-mcp
 
# Logs
kubectl logs -f deployment/naics-mcp-server -n naics-mcp
 
# Describe deployment
kubectl describe deployment naics-mcp-server -n naics-mcp

Rolling Update

# Update image
kubectl set image deployment/naics-mcp-server \
  naics-mcp-server=ghcr.io/mfbaig35r/naics-mcp-server:v1.1.0 \
  -n naics-mcp
 
# Check rollout status
kubectl rollout status deployment/naics-mcp-server -n naics-mcp
 
# Rollback if needed
kubectl rollout undo deployment/naics-mcp-server -n naics-mcp

Scaling

# Manual scale
kubectl scale deployment naics-mcp-server --replicas=5 -n naics-mcp

Health Check

# Port forward for testing
kubectl port-forward svc/naics-mcp-server 9090:9090 -n naics-mcp
 
# Test endpoints
curl http://localhost:9090/health
curl http://localhost:9090/ready
curl http://localhost:9090/status

Troubleshooting

Pods Not Starting

# Check events
kubectl get events -n naics-mcp --sort-by='.lastTimestamp'
 
# Check pod details
kubectl describe pod <pod-name> -n naics-mcp

Readiness Probe Failures

# Check logs
kubectl logs <pod-name> -n naics-mcp
 
# Exec into pod
kubectl exec -it <pod-name> -n naics-mcp -- /bin/sh

Resource Issues

# Check resource usage
kubectl top pods -n naics-mcp
DockerConfiguration