k8s-workflow

name: k8s-workflow description: Agent contract and fast dev loop for K8s operator development

Kubernetes Operator Workflow

Operating Mode

• Dev-only: Target kind clusters only. Refuse operations on non-kind contexts unless user explicitly overrides.
• MCP preferred: If a Kubernetes MCP server is available, use it for cluster validation. Otherwise, fall back to kubectl commands.
• Safety first: Allow only kind-* contexts. Avoid destructive operations by default.

Agent Responsibilities

1. Ask questions to clarify CRD purpose, fields, validation rules, webhook type, and safety constraints.
2. Generate CRD schema and example custom resources.
3. Scaffold controller and webhook code using Go + Kubebuilder patterns.
4. Create dev loop config: Tiltfile + Kustomize dev overlay + Makefile target.
5. Create a kind cluster and install CRDs/webhooks.
6. Validate behavior using MCP or kubectl and logs.
7. Iterate until requirements are satisfied.

Required Q&A (ask before writing code)

Always ask these 10 questions and wait for answers:

1. CRD purpose (1 sentence)
2. Spec fields (name + type + required?)
3. Status fields (what should be reported?)
4. Webhook type (validating, mutating, or both)
5. Defaulting rules (if any)
6. Validation rules (invariants)
7. RBAC scope (namespace or cluster)
8. Resource ownership (what objects are created/managed)
9. Failure policy (for webhooks)
10. Safety gates (annotations/labels to enable mutations)

Dev Fast Loop Workflow

Default to Tilt (tilt up or make dev) for all build and deploy cycles. Do not manually run docker build, kind load, or kustomize build | kubectl apply unless Tilt live-update cannot handle the change.

Overview

• One command: make dev (wraps tilt up)
• Tilt builds the Docker image, loads it into kind, and applies Kustomize manifests
• Local go build produces the manager binary
• Tilt live-update syncs the binary into the running manager pod
• Tilt kills the process to restart with new code

Iteration Cycle

1. Edit Go files (types, controller, webhook)
2. Tilt recompiles locally
3. Binary syncs into the running pod
4. Process restarts
5. Check logs/events for feedback

Fall Back to Manual Build/Deploy When

Tilt live-update only syncs the compiled binary. Use manual docker build + kind load + kubectl apply when:

• CRD schema changed (make manifests needed, then re-apply CRDs)
• Dockerfile or base image changed
• Go dependencies changed that affect the container environment
• Tilt is not running or not recovering from an error

Files the Agent Should Manage

• api/v1/*_types.go — CRD spec and status types
• internal/controller/*_controller.go — Reconcile loop
• api/v1/*_webhook.go — Webhook handlers
• config/crd/bases/ — Generated CRD YAML
• config/webhook/ — Webhook configuration
• config/rbac/ — RBAC rules
• config/dev/ — Kustomize dev overlay
• Tiltfile — Tilt configuration
• Makefile — Build and dev targets

Safety Guardrails

• Only allow kind-* kubectl contexts
• Refuse operations on production or staging contexts
• Avoid destructive operations (delete namespace, delete CRD) unless explicitly confirmed
• Use failure policy Ignore for dev, Fail for production
• Disable leader election in dev (single replica)

MCP Validation (when available)

Use MCP to verify:

• CRDs installed and versions match
• Webhook configs present
• Manager/webhook pods healthy
• Logs show reconcile activity

If MCP is not available, use equivalent kubectl commands.