scobleclaw/kubeclaw/docs/development.md

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

git clone https://os.scoble.me/forgejo/marcus/scobleclaw.git
cd scobleclaw/kubeclaw

2. Create a Local Cluster

kind create cluster --name kubeclaw-dev

Or use an existing cluster:

kubectl config get-contexts

3. Install CRDs

make install

This applies all CRD YAML manifests to the cluster.

4. Run the Controller Locally

# In one terminal:
make run

# The controller connects to the current kubecontext
# Logs show reconciliation of CRD events

5. Deploy an Agent

# 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

make test

Tests cover:

• Reconciler logic (mock K8s client)
• Judge verifier (mock LLM responses)
• Webhook validation
• CRD schema validation

Integration Tests

# 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

# Requires a full cluster with all components
make test-e2e

Local Development Tips

Watch Controller Logs

kubectl logs -n kubeclaw-system deployment/kubeclaw-controller -f

Debug Agent Pods

# 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:

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