openclaw-operator: Instructions file for Claude Code

CLAUDE.md — OpenClaw Kubernetes Operator

Project Overview

Go-based Kubernetes operator for managing OpenClaw instances, built with controller-runtime (kubebuilder). CRD API group is openclaw.rocks, version v1alpha1.

• Module: github.com/paperclipinc/openclaw-operator
• Go version: 1.25
• GitHub: paperclipinc/openclaw-operator (GHCR org: paperclipinc)

Commands

make test          # Unit + integration tests (requires envtest binaries)
make lint          # golangci-lint
make build         # Build manager binary
make manifests     # Regenerate CRD YAML + RBAC after API type changes
make generate      # Regenerate deepcopy methods after API type changes
make install       # Install CRDs into current cluster
make run           # Run operator locally against current cluster
go test ./internal/resources/ -v   # Fast unit tests (no envtest needed)
go vet ./...       # Go vet check

Architecture

api/v1alpha1/          → CRD types (OpenClawInstance)
internal/controller/   → Reconciliation logic (single controller)
internal/resources/    → Pure resource builder functions (Deployment, Service, etc.)
config/crd/bases/      → Generated CRD YAML (committed to git)
charts/                → Helm chart
bundle/                → OLM bundle for OperatorHub submissions
test/e2e/              → E2E tests (run against kind cluster)

Separation of concerns: Controller logic (internal/controller/) only orchestrates reconciliation. All resource construction happens in pure functions in internal/resources/. This makes builders easy to unit test without envtest.

Reconciliation Rules

These rules are enforced by CI (Reconcile Guard check) and must be followed:

Always use controllerutil.CreateOrUpdate for managed resources

Never call r.Update() or r.Create() directly on managed resources (Deployments, Services, ConfigMaps, etc.). Always use:

obj := &appsv1.Deployment{
    ObjectMeta: metav1.ObjectMeta{
        Name:      resources.DeploymentName(instance),
        Namespace: instance.Namespace,
    },
}
_, err := controllerutil.CreateOrUpdate(ctx, r.Client, obj, func() error {
    desired := resources.BuildDeployment(instance)
    obj.Labels = desired.Labels
    obj.Spec = desired.Spec
    return controllerutil.SetControllerReference(instance, obj, r.Scheme)
})