> ## Documentation Index
> Fetch the complete documentation index at: https://docs.weavemcp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Kubernetes

> Deploy WeaveMCP agents on Kubernetes for production scalability

# Deploy with Kubernetes

Deploy WeaveMCP agents on Kubernetes for production-grade scalability, reliability, and management.

## Prerequisites

* Kubernetes cluster (1.19+)
* kubectl configured to access your cluster
* WeaveMCP account with virtual server created
* Agent token generated from the web console

## Quick Deployment

### 1. Create Namespace

```bash theme={null}
kubectl create namespace weavemcp
```

### 2. Create Secret

Store your agent token securely:

```bash theme={null}
kubectl create secret generic weavemcp-agent-secret \
  --from-literal=agent-token="your-agent-token-here" \
  --namespace=weavemcp
```

### 3. Create ConfigMap

Create `mcp-servers-config.yaml`:

```yaml theme={null}
apiVersion: v1
kind: ConfigMap
metadata:
  name: weavemcp-mcp-servers
  namespace: weavemcp
data:
  mcp-servers.json: |
    {
      "mcpServers": {
        "filesystem-server": {
          "command": "npx",
          "args": ["@modelcontextprotocol/server-filesystem", "/data"],
          "env": {
            "NODE_ENV": "production"
          }
        },
        "git-server": {
          "command": "npx",
          "args": ["@modelcontextprotocol/server-git", "/repos"],
          "env": {
            "GIT_AUTHOR_NAME": "WeaveMCP Agent",
            "GIT_AUTHOR_EMAIL": "agent@weavemcp.com"
          }
        }
      }
    }
```

Apply the ConfigMap:

```bash theme={null}
kubectl apply -f mcp-servers-config.yaml
```

### 4. Create Deployment

Create `agent-deployment.yaml`:

```yaml theme={null}
apiVersion: apps/v1
kind: Deployment
metadata:
  name: weavemcp-agent
  namespace: weavemcp
  labels:
    app: weavemcp-agent
spec:
  replicas: 2
  selector:
    matchLabels:
      app: weavemcp-agent
  template:
    metadata:
      labels:
        app: weavemcp-agent
    spec:
      containers:
      - name: weavemcp-agent
        image: weavemcp/agent:v1.0.0
        ports:
        - containerPort: 8080
          name: health
        - containerPort: 9090
          name: metrics
        env:
        - name: WEAVEMCP_AGENT_TOKEN
          valueFrom:
            secretKeyRef:
              name: weavemcp-agent-secret
              key: agent-token
        - name: WEAVEMCP_SERVER_URL
          value: "https://your-virtual-server.weavemcp.dev"
        - name: WEAVEMCP_LOG_LEVEL
          value: "info"
        - name: WEAVEMCP_HEALTH_CHECK_PORT
          value: "8080"
        - name: WEAVEMCP_METRICS_PORT
          value: "9090"
        volumeMounts:
        - name: mcp-config
          mountPath: /app/config
          readOnly: true
        - name: data-volume
          mountPath: /data
        - name: repos-volume
          mountPath: /repos
        resources:
          limits:
            cpu: 500m
            memory: 512Mi
          requests:
            cpu: 250m
            memory: 256Mi
        livenessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 30
          periodSeconds: 30
        readinessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 10
        securityContext:
          allowPrivilegeEscalation: false
          readOnlyRootFilesystem: true
          runAsNonRoot: true
          runAsUser: 1000
      volumes:
      - name: mcp-config
        configMap:
          name: weavemcp-mcp-servers
      - name: data-volume
        persistentVolumeClaim:
          claimName: weavemcp-data-pvc
      - name: repos-volume
        persistentVolumeClaim:
          claimName: weavemcp-repos-pvc
      securityContext:
        fsGroup: 1000
```

### 5. Create Persistent Volumes

Create `persistent-volumes.yaml`:

```yaml theme={null}
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: weavemcp-data-pvc
  namespace: weavemcp
spec:
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: 10Gi
  storageClassName: standard
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: weavemcp-repos-pvc
  namespace: weavemcp
spec:
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: 50Gi
  storageClassName: standard
```

### 6. Create Service

Create `agent-service.yaml`:

```yaml theme={null}
apiVersion: v1
kind: Service
metadata:
  name: weavemcp-agent-service
  namespace: weavemcp
  labels:
    app: weavemcp-agent
spec:
  selector:
    app: weavemcp-agent
  ports:
  - name: health
    port: 8080
    targetPort: 8080
  - name: metrics
    port: 9090
    targetPort: 9090
  type: ClusterIP
```

### 7. Deploy Everything

```bash theme={null}
kubectl apply -f persistent-volumes.yaml
kubectl apply -f agent-deployment.yaml
kubectl apply -f agent-service.yaml
```

## Production Configuration

### Horizontal Pod Autoscaler

Create `hpa.yaml`:

```yaml theme={null}
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: weavemcp-agent-hpa
  namespace: weavemcp
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: weavemcp-agent
  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
```

### Pod Disruption Budget

Create `pdb.yaml`:

```yaml theme={null}
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: weavemcp-agent-pdb
  namespace: weavemcp
spec:
  minAvailable: 1
  selector:
    matchLabels:
      app: weavemcp-agent
```

### Network Policy

Create `network-policy.yaml`:

```yaml theme={null}
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: weavemcp-agent-network-policy
  namespace: weavemcp
spec:
  podSelector:
    matchLabels:
      app: weavemcp-agent
  policyTypes:
  - Ingress
  - Egress
  ingress:
  - from:
    - namespaceSelector:
        matchLabels:
          name: monitoring
    ports:
    - protocol: TCP
      port: 9090  # Metrics
  - from:
    - namespaceSelector:
        matchLabels:
          name: kube-system
    ports:
    - protocol: TCP
      port: 8080  # Health checks
  egress:
  - to: []  # Allow all egress for WeaveMCP communication
    ports:
    - protocol: TCP
      port: 443
  - to:
    - namespaceSelector:
        matchLabels:
          name: kube-system
    ports:
    - protocol: TCP
      port: 53
    - protocol: UDP
      port: 53
```

## Monitoring Integration

### ServiceMonitor for Prometheus

Create `service-monitor.yaml`:

```yaml theme={null}
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: weavemcp-agent-metrics
  namespace: weavemcp
  labels:
    app: weavemcp-agent
spec:
  selector:
    matchLabels:
      app: weavemcp-agent
  endpoints:
  - port: metrics
    path: /metrics
    interval: 30s
```

### Grafana Dashboard

Use our pre-built Grafana dashboard:

```bash theme={null}
kubectl create configmap weavemcp-dashboard \
  --from-file=dashboard.json \
  --namespace=monitoring
```

## Advanced Features

### Multi-Region Deployment

Deploy across multiple regions for high availability:

```yaml theme={null}
apiVersion: apps/v1
kind: Deployment
metadata:
  name: weavemcp-agent
  namespace: weavemcp
spec:
  replicas: 6
  template:
    spec:
      affinity:
        podAntiAffinity:
          preferredDuringSchedulingIgnoredDuringExecution:
          - weight: 100
            podAffinityTerm:
              labelSelector:
                matchExpressions:
                - key: app
                  operator: In
                  values:
                  - weavemcp-agent
              topologyKey: topology.kubernetes.io/zone
      # ... rest of spec
```

### Custom Resource Definitions

Define custom MCP server configurations:

```yaml theme={null}
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: mcpservers.weavemcp.com
spec:
  group: weavemcp.com
  versions:
  - name: v1
    served: true
    storage: true
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
            properties:
              name:
                type: string
              command:
                type: string
              args:
                type: array
                items:
                  type: string
              env:
                type: object
                additionalProperties:
                  type: string
  scope: Namespaced
  names:
    plural: mcpservers
    singular: mcpserver
    kind: MCPServer
```

## Operations

### Health Monitoring

Check agent health:

```bash theme={null}
# Check pod status
kubectl get pods -n weavemcp

# Check agent health endpoint
kubectl port-forward -n weavemcp svc/weavemcp-agent-service 8080:8080
curl http://localhost:8080/health

# View agent logs
kubectl logs -n weavemcp -l app=weavemcp-agent --tail=100
```

### Scaling

Scale the deployment:

```bash theme={null}
# Manual scaling
kubectl scale deployment weavemcp-agent --replicas=5 -n weavemcp

# Check HPA status
kubectl get hpa -n weavemcp

# View scaling events
kubectl describe hpa weavemcp-agent-hpa -n weavemcp
```

### Updates

Rolling updates:

```bash theme={null}
# Update image
kubectl set image deployment/weavemcp-agent \
  weavemcp-agent=weavemcp/agent:v1.1.0 \
  -n weavemcp

# Check rollout status
kubectl rollout status deployment/weavemcp-agent -n weavemcp

# Rollback if needed
kubectl rollout undo deployment/weavemcp-agent -n weavemcp
```

### Backup and Restore

Backup persistent data:

```bash theme={null}
# Create backup job
kubectl create job weavemcp-backup \
  --from=cronjob/weavemcp-backup-cronjob \
  -n weavemcp

# Check backup status
kubectl get jobs -n weavemcp

# List backups
kubectl exec -n weavemcp deployment/weavemcp-agent -- \
  ls -la /backups
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Pods not starting">
    ```bash theme={null}
    # Check pod events
    kubectl describe pods -n weavemcp

    # Check resource constraints
    kubectl top pods -n weavemcp

    # Verify secrets and configmaps
    kubectl get secrets,configmaps -n weavemcp
    ```
  </Accordion>

  <Accordion title="Health checks failing">
    ```bash theme={null}
    # Check service endpoints
    kubectl get endpoints -n weavemcp

    # Test health endpoint directly
    kubectl exec -n weavemcp deployment/weavemcp-agent -- \
      curl http://localhost:8080/health

    # Review probe configuration
    kubectl describe deployment weavemcp-agent -n weavemcp
    ```
  </Accordion>

  <Accordion title="Network connectivity issues">
    ```bash theme={null}
    # Test external connectivity
    kubectl exec -n weavemcp deployment/weavemcp-agent -- \
      curl -I https://console.weavemcp.com

    # Check network policies
    kubectl get networkpolicies -n weavemcp

    # Verify DNS resolution
    kubectl exec -n weavemcp deployment/weavemcp-agent -- \
      nslookup console.weavemcp.com
    ```
  </Accordion>
</AccordionGroup>

## Security Best Practices

1. **Use specific image tags**: Avoid `latest` in production
2. **Run as non-root**: Set `runAsNonRoot: true`
3. **Read-only filesystem**: Use `readOnlyRootFilesystem: true`
4. **Resource limits**: Always set CPU and memory limits
5. **Network policies**: Restrict network access
6. **Secret management**: Use external secret management systems
7. **Pod security standards**: Implement Pod Security Standards
8. **Regular updates**: Keep images and Kubernetes updated

## Next Steps

<CardGroup cols={2}>
  <Card title="Monitoring Setup" icon="chart-line" href="/monitoring">
    Set up comprehensive monitoring and alerting
  </Card>

  <Card title="Multi-Cluster" icon="globe" href="/multi-cluster">
    Deploy across multiple Kubernetes clusters
  </Card>

  <Card title="GitOps Integration" icon="git-branch" href="/gitops">
    Manage deployments with GitOps workflows
  </Card>

  <Card title="Custom Operators" icon="cogs" href="/operators">
    Build custom Kubernetes operators for WeaveMCP
  </Card>
</CardGroup>