terdut-operator/CLAUDE.md

terdut-operator

Kubebuilder/controller-runtime operator for terdut-server. See DESIGN.md for the settled design (CRD catalog, reconciliation semantics, bootstrap/auth, RBAC) and ROADMAP.md for the staged build plan this repo is following. README.md stays the short pitch.

Checks

make fmt lint test helm-lint is the CI gate (.gitea/workflows/ci.yaml's test, security and chart jobs call these targets rather than restating them, same convention as terdut-server). test chains through the Kubebuilder-scaffolded manifests/generate (controller-gen) and setup-envtest targets automatically — everything needed lands in bin/ (gitignored) on first run, no separate tool install required beyond Go itself and network access to proxy.golang.org/storage.googleapis.com. security runs make security-go/security-secrets (govulncheck/gitleaks), same as terdut-server's own security job.

The kubebuilder-scaffolded make test-e2e (a disposable, generic smoke test) is separate from the real golden-path kind e2e pass ROADMAP.md's Stage 5 describes (create every CRD kind, verify against terdut-server's own API, delete, verify gone) — the latter is a manual pass run and recorded in ROADMAP.md, not a CI job, matching Stage 1-4's own precedent of validating against a real cluster outside CI.

Release

Wired as of Stage 5 (ROADMAP.md): .release.conf, make release-vars/helm-lint/ push/helm-package/helm-push/release, and .gitea/workflows/release.yaml (test → image/chart → scan-image) all follow terdut-server's established shape — see that repo's Makefile/.release.conf for the shared reasoning, not restated here.

The chart is charts/terdut-operator (via kubebuilder's own helm/v2-alpha plugin, regenerate with kubebuilder edit --plugins helm.kubebuilder.io/v2-alpha --output-dir charts --force after config/ changes, then re-review — --force does not touch Chart.yaml but does touch values.yaml, which carries hand-written additions, most importantly the optional terdutServer block, DESIGN.md §10). It installs the operator + CRDs + RBAC, and optionally one TerdutServer CR (terdutServer.enabled, off by default).

That one-time manual step — hand-creating the initial terdut-operator/ wrapper entry under Ryuvia/charts, since chart-bump only ever bumps an existing one — is done. It happened during this repo's actual first release (v0.1.1, 2026-10-01; v0.1.0 published but never deployed anywhere, after its own scan-image found a CVE in the grpc version it had just bumped to). Every release since bumps that wrapper entry like any other onboarded repo's.