3264f9fe66
Define kubeclaw as a Kubernetes operator that runs Scobleclaw AI agents as first-class K8s workloads with CRDs, controller loops, and security-hardened operator patterns. Key deliverables in this commit: - README.md — Project spec with CRD reference, architecture diagram, security model, threat model, and quick-start guide - docs/architecture.md — Deep architecture doc covering operator pattern, sidecar design, API design, security architecture, and operations - docs/development.md — Dev setup guide with prerequisites, commands, testing, and local dev tips Integrates with: - scobleclaw#7 (Agent-Judge authorization layer) - OpenClaw gateway for LLM provider management - Standard Kubernetes operator patterns Closes scobleclaw#8
151 lines
3.3 KiB
Markdown
151 lines
3.3 KiB
Markdown
# Development Setup
|
|
|
|
> **Status:** Draft v0.1
|
|
> **Author:** @agent-cos
|
|
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
- **Go 1.22+** — `go version` should show go1.22 or later
|
|
- **kubectl** — configured with a cluster context (kind/minikube for local dev)
|
|
- **helm** — v3.x for chart deployment
|
|
- **controller-gen** — from `sigs.k8s.io/controller-tools`
|
|
- **kustomize** — built into `kubectl kustomize` or standalone v4+
|
|
- **Docker** — for building controller images
|
|
- **kind** or **minikube** — for local Kubernetes clusters
|
|
- **OpenClaw gateway** or compatible LLM API endpoint
|
|
|
|
## Quick Start
|
|
|
|
### 1. Clone the Repository
|
|
|
|
```bash
|
|
git clone https://os.scoble.me/forgejo/marcus/scobleclaw.git
|
|
cd scobleclaw/kubeclaw
|
|
```
|
|
|
|
### 2. Create a Local Cluster
|
|
|
|
```bash
|
|
kind create cluster --name kubeclaw-dev
|
|
```
|
|
|
|
Or use an existing cluster:
|
|
|
|
```bash
|
|
kubectl config get-contexts
|
|
```
|
|
|
|
### 3. Install CRDs
|
|
|
|
```bash
|
|
make install
|
|
```
|
|
|
|
This applies all CRD YAML manifests to the cluster.
|
|
|
|
### 4. Run the Controller Locally
|
|
|
|
```bash
|
|
# In one terminal:
|
|
make run
|
|
|
|
# The controller connects to the current kubecontext
|
|
# Logs show reconciliation of CRD events
|
|
```
|
|
|
|
### 5. Deploy an Agent
|
|
|
|
```bash
|
|
# Apply a Provider first (no real credentials in dev)
|
|
kubectl apply -f config/samples/sample-provider.yaml
|
|
|
|
# Apply an Agent
|
|
kubectl apply -f config/samples/sample-agent.yaml
|
|
|
|
# Watch the agent pod come up
|
|
kubectl get pods -n agents -w
|
|
```
|
|
|
|
## Project Commands
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `make generate` | Generate CRD deep copy and client code |
|
|
| `make manifests` | Generate CRD YAML manifests from Go types |
|
|
| `make install` | Apply CRDs to cluster |
|
|
| `make uninstall` | Remove CRDs from cluster |
|
|
| `make run` | Run controller locally |
|
|
| `make test` | Run unit and integration tests |
|
|
| `make docker-build` | Build controller Docker image |
|
|
| `make docker-push` | Push controller image to registry |
|
|
| `make helm-package` | Package Helm chart |
|
|
| `make deploy` | Deploy controller via Helm |
|
|
|
|
## Testing
|
|
|
|
### Unit Tests
|
|
|
|
```bash
|
|
make test
|
|
```
|
|
|
|
Tests cover:
|
|
- Reconciler logic (mock K8s client)
|
|
- Judge verifier (mock LLM responses)
|
|
- Webhook validation
|
|
- CRD schema validation
|
|
|
|
### Integration Tests
|
|
|
|
```bash
|
|
# Requires a running cluster and controller
|
|
make test-integration
|
|
```
|
|
|
|
Uses envtest (controller-runtime's test environment) for in-process API server testing.
|
|
|
|
### End-to-End Tests
|
|
|
|
```bash
|
|
# Requires a full cluster with all components
|
|
make test-e2e
|
|
```
|
|
|
|
## Local Development Tips
|
|
|
|
### Watch Controller Logs
|
|
|
|
```bash
|
|
kubectl logs -n kubeclaw-system deployment/kubeclaw-controller -f
|
|
```
|
|
|
|
### Debug Agent Pods
|
|
|
|
```bash
|
|
# Check pod status
|
|
kubectl describe pod -n agents <agent-name>
|
|
|
|
# Check judge sidecar logs
|
|
kubectl logs -n agents <agent-pod> -c judge
|
|
|
|
# Check workflow executor logs
|
|
kubectl logs -n agents <agent-pod> -c workflow-executor
|
|
```
|
|
|
|
### Hot Reload
|
|
|
|
For rapid iteration on CRD handler logic without rebuilding Docker images:
|
|
|
|
```bash
|
|
make run # Restart on ctrl+c and re-run after code changes
|
|
```
|
|
|
|
## Architecture Notes
|
|
|
|
- The controller uses `controller-runtime`'s builder pattern: `NewControllerManagedBy(mgr).For(&Agent{}).Owns(&corev1.Pod{})`
|
|
- CRD types are in `api/v1alpha1/`
|
|
- Reconcilers are in `internal/controller/`
|
|
- The judge is implemented as a gRPC or HTTP sidecar
|
|
- Workflow templates are validated server-side before agent creation
|