[subtask] [Subtask 4/4] Create deployment manifests and documentation for Kubernetes operator

[github-actions]

Parent Issue: #20

Objective

Provide complete Kubernetes deployment manifests, Helm charts, and documentation for deploying and operating the Wassette Kubernetes operator in production clusters.

Context

With the operator implementation complete (Subtasks 1-3), we need production-ready deployment artifacts that allow users to:

• Deploy the operator to their Kubernetes clusters
• Configure RBAC permissions correctly
• Manage component lifecycle via CRDs
• Monitor operator health and performance

This subtask can be developed in parallel with Subtask 3 as it primarily involves configuration and documentation.

Implementation Details

1. Kubernetes Manifests

Create deployment manifests in deploy/kubernetes/:

a. CRD Definitions (crds/)

• wassettecomponent-crd.yaml - Component CRD (from Subtask 1 design)
• wassettepolicy-crd.yaml - Policy CRD (if applicable)

b. RBAC (rbac/)

• serviceaccount.yaml - Service account for operator
• clusterrole.yaml - Permissions to watch/update CRDs
• clusterrolebinding.yaml - Bind role to service account

Example permissions needed:

rules:
  - apiGroups: ["wassette.microsoft.io"]
    resources: ["wassettecomponents", "wassettepolicies"]
    verbs: ["get", "list", "watch", "update", "patch"]
  - apiGroups: [""]
    resources: ["events"]
    verbs: ["create", "patch"]

c. Operator Deployment (operator/)

• deployment.yaml - Operator deployment
• service.yaml - MCP API service
• configmap.yaml - Operator configuration

2. Helm Chart

Create Helm chart in deploy/helm/wassette-operator/:

wassette-operator/
├── Chart.yaml
├── values.yaml
├── templates/
│   ├── crds/
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── rbac.yaml
│   └── servicemonitor.yaml  # For Prometheus monitoring
└── README.md

values.yaml should include:

• Image repository and tag
• Resource limits (CPU/memory)
• Replica count
• Namespace configuration
• Monitoring/logging settings

3. Example Component Manifests

Create examples in examples/kubernetes/:

• time-server-component.yaml - Simple component example
• fetch-component.yaml - Component with network permissions
• filesystem-component.yaml - Component with storage permissions

Example:

apiVersion: wassette.microsoft.io/v1
kind: WassetteComponent
metadata:
  name: time-server
spec:
  ociRef: "(redacted)"
  policy:
    network:
      allow: []
    storage:
      deny: ["*"]

4. Documentation

Create/update documentation files:

a. docs/deployment/kubernetes.md

Complete guide covering:

• Prerequisites (kubectl, cluster access)
• Installation steps (kubectl apply vs Helm)
• Configuration options
• Upgrading the operator
• Troubleshooting common issues
• Security best practices

b. docs/reference/kubernetes-api.md

API reference for CRDs:

• Field descriptions for WassetteComponent spec/status
• Example manifests for common scenarios
• Policy specification reference

c. Update README.md

Add Kubernetes deployment option:

## Kubernetes Deployment

Deploy Wassette as a Kubernetes operator to manage WebAssembly components cluster-wide:

```bash
# Install CRDs
kubectl apply -f deploy/kubernetes/crds/

# Deploy operator
kubectl apply -f deploy/kubernetes/operator/

# Load a component
kubectl apply -f examples/kubernetes/time-server-component.yaml

See Kubernetes deployment guide for complete instructions.

### 5. CI/CD Integration
Add operator build/test to CI:
- **Modify**: `.github/workflows/ci.yml`
  - Add operator build step
  - Add Kubernetes integration tests (using kind)
  
- **New**: `.github/workflows/operator-release.yml`
  - Build and push operator container image
  - Package Helm chart
  - Publish to GitHub Container Registry

### 6. Container Image
Update Dockerfile or create new one:
- **New**: `Dockerfile.operator` - Multi-stage build for operator
- Build both `wassette` binary and `wassette-operator` binary
- Minimize image size (use distroless or alpine base)

## Acceptance Criteria
- [ ] CRD manifests can be applied to Kubernetes cluster
- [ ] Operator deploys successfully via kubectl apply
- [ ] Helm chart installs and configures operator correctly
- [ ] RBAC permissions are minimal and follow least-privilege principle
- [ ] Example component manifests work end-to-end
- [ ] Documentation includes complete installation walkthrough
- [ ] CI builds and tests operator in Kubernetes environment
- [ ] Container image is published to GHCR with proper tagging

## Testing Strategy

### Manual Testing
1. Deploy to local Kubernetes cluster (kind/minikube):
   ```bash
   kind create cluster
   kubectl apply -f deploy/kubernetes/crds/
   kubectl apply -f deploy/kubernetes/operator/
   kubectl wait --for=condition=Ready pod -l app=wassette-operator

2. Test component lifecycle:

   kubectl apply -f examples/kubernetes/time-server-component.yaml
   kubectl get wassettecomponents
   kubectl describe wassettecomponent time-server

3. Test MCP API access:

   kubectl port-forward svc/wassette-mcp 9001:9001
   npx `@modelcontextprotocol/inspector` --cli (redacted) --method tools/list

Automated Testing

• CI pipeline deploys to kind cluster
• Runs smoke tests against deployed operator
• Verifies component loading and tool execution
• Tests upgrade scenarios

Documentation Testing

• Follow installation guide step-by-step on fresh cluster
• Verify all examples work as documented
• Test both kubectl and Helm installation paths

Dependencies

• Requires: Subtasks 1, 2, 3 must be functionally complete
• Can be developed in parallel with: Subtask 3 (manifests and docs can be prepared while API is being implemented)

References

• Existing Docker deployment: docs/deployment/docker.md
• Kubernetes operator best practices: (redacted)
• Helm chart best practices: (redacted)
• RBAC documentation: (redacted)
  Related to Kubernetes Operator for mcp-wasmtime #20

AI generated by Plan for #20

[asw101]

Closing [subtask]s of parent issues.