Skip to content

Shuttle Scaffolding Instructions for Claude Code

Hand-scaffolded — no Kubebuilder, no operator-sdk.

Step 1: go mod init github.com/starform/shuttle

Step 2: Add dependencies:

go get sigs.k8s.io/controller-runtime@latest
go get k8s.io/api@latest k8s.io/apimachinery@latest k8s.io/client-go@latest
go get sigs.k8s.io/gateway-api@latest

Step 3: Create directory structure from §21.

Step 4: Scaffold each file with stubs (TODO bodies):

  • cmd/agent/main.go — Manager setup, scheme registration (corev1, appsv1, rbacv1, networkingv1, policyv1, gatewayv1), cache label filter, register 3 Runnables, signal handler
  • internal/config/config.go — Config struct, LoadConfig() from env vars
  • internal/types/types.go — Snapshot, SnapshotBatch, CapacityReport, DesiredState, ClusterConfig, ServiceSpec structs with json tags
  • internal/client/starbase.go — Client struct with PullDesiredState, PostSnapshots, PostCapacity method signatures
  • internal/runner/desiredstate.go — DesiredStateRunnable with 30s ticker loop (TODO body)
  • internal/runner/snapshot.go — SnapshotRunnable with 60s ticker loop (TODO body)
  • internal/runner/capacity.go — CapacityRunnable with 60s ticker loop (TODO body)
  • internal/apply/namespace.go — EnsureNamespace, EnsureServiceAccount, EnsureRBAC, EnsureNetworkPolicy, EnsureResourceQuota, EnsureLimitRange stubs
  • internal/apply/workload.go — EnsureDeployment, EnsureService, EnsureConfigMap, EnsureSecret, EnsurePodDisruptionBudget stubs
  • internal/apply/routing.go — EnsureHTTPRoute stub
  • internal/apply/garbage.go — GarbageCollect stub

Step 5: Add Dockerfile (multi-stage, distroless), Makefile, .gitignore, .dockerignore, README.md

Step 6: Add deploy/ manifests (rbac.yaml, deployment.yaml, servicemonitor.yaml) from §22 RBAC and §28 resources.

Step 7: Verify: go mod tidy && go build ./... && go vet ./...

Claude Code must NOT: implement business logic, write tests, add CI/CD, use Kubebuilder/operator-sdk, define a Reconciler, add WAL/leader election/mTLS.

Cross-references

The directory tree Step 3 creates → §21 · the Runnables Step 4 stubs → §19.3 · the ClusterRole for deploy/rbac.yaml → §22 · the resource requests for deploy/deployment.yaml → §28 · the env-var Config struct → §23.