chute

Development

Prerequisites

• Go (version in go.mod)
• ko — for building container images
• kind — for local Kubernetes cluster
• controller-gen — for CRD/RBAC generation
• kustomize — for manifest generation
• kubectl

Project Layout

api/v1alpha1/           CRD type definitions (ChuteConfig, ChuteInstance)
cmd/operator/           Operator entrypoint (main.go)
config/
  crd/bases/            Generated CRD YAML
  rbac/                 Generated RBAC (ClusterRole)
  manager/              Operator Deployment manifest
  default/              Kustomize overlay (namespace + all components)
  samples/              Example ChuteConfig and ChuteInstance YAML
internal/
  cloudflare/           Cloudflare v4 API client
  controller/           Reconcilers (ChuteConfig, ChuteInstance)
scripts/
  deploy.sh             One-command deploy with .env

Common Commands

make build          # Build binary to bin/manager
make run            # Build and run locally (uses ~/.kube/config)
make test           # Run all tests with verbose output
make fmt            # Format code
make vet            # Vet code

Running a Single Test

go test ./internal/controller/ -run TestReconcile -v

Building and Deploying to kind

Images are built with ko. The default target cluster is kind-kind.

make ko-build                  # Build image and load into kind
make deploy                    # Full deploy: CRDs + RBAC + operator image into kind
make undeploy                  # Tear down operator from kind
KUBE_CONTEXT=kind-other make deploy  # Target a different kind cluster

One-Command Deploy with .env

cp .env.example .env           # Fill in Cloudflare credentials
./scripts/deploy.sh            # Deploys operator + creates ChuteConfig from .env
./scripts/deploy.sh .env.prod  # Use a different env file

The deploy script builds with ko, loads into kind, installs CRDs/RBAC, deploys the operator, creates a Secret + ChuteConfig from the .env values, and prints an example ChuteInstance to apply.

Regenerating Manifests

If you change the CRD types in api/v1alpha1/:

make generate       # Regenerate deepcopy methods
make manifests      # Regenerate CRD and RBAC YAML from markers

!!! note Both commands require controller-gen. Install it with: bash go install sigs.k8s.io/controller-tools/cmd/controller-gen@latest

CI/CD

The CI pipeline (.github/workflows/publish.yaml) runs on every push and PR to main:

• Tests: go test ./... -v -count=1
• Release (push to main only): bumps semver tag, builds multi-arch image with ko, pushes to GHCR, builds a release manifest with kustomize, creates a GitHub Release with the manifest attached
• Build (PRs only): builds the image without pushing to verify it compiles