Imported from open-viz/trickster-config (AGENTS.md). Install upstream with npx skills add open-viz/trickster-config. Copyright stays with the author.

AGENTS.md

This file provides guidance to coding agents (e.g. Claude Code, claude.ai/code) when working with code in this repository.

Repository purpose

Go module go.openviz.dev/trickster-config — a Kubebuilder-scaffolded operator that materializes a Trickster configuration from Kubernetes CRDs. It defines CRDs that map onto Trickster's native config structs and reconciles them by importing github.com/trickstercache/trickster/v2/cmd/trickster/config and emitting the equivalent Trickster YAML / live config.

Domain is org (not appscode.com or openviz.dev) — that is the legacy Kubebuilder scaffold default. CRD API group is trickstercache.org/v1alpha1. (README's "TODO(user)" placeholders are leftover from kubebuilder init; treat this file as the source of truth.)

Architecture

• main.go — controller-runtime manager bootstrap; registers the scheme, sets up metrics/healthz, starts controllers.TricksterReconciler. Imports trickstercache/trickster/v2/cmd/trickster/config so the CRD spec types can be marshaled into a real Trickster config blob.
• api/v1alpha1/ — Kubebuilder API types. Six kinds in this single API group:
  • Trickster (the parent, owns the rendered config)
  • TricksterBackend, TricksterCache, TricksterTracingConfig, TricksterRule, TricksterRequestRewriter (the child building blocks)
  • groupversion_info.go registers trickstercache.org/v1alpha1.
  • zz_generated.deepcopy.go is generated; do not hand-edit.
• controllers/ — reconcilers:
  • trickster_controller.go — the only reconciler today; aggregates child CRDs into the upstream Trickster config struct and exposes it.
  • suite_test.go — envtest-based controller test harness.
• config/ — Kubebuilder Kustomize bases (crd/, default/, manager/, rbac/, prometheus/, samples/).
• PROJECT — Kubebuilder project metadata. Do not hand-edit unless you also run kubebuilder edit.
• Dockerfile — manager image build.
• hack/, Makefile — Kubebuilder-flavored Make targets, plus tool downloaders (controller-gen, kustomize, envtest) under bin/.
• vendor/ — checked-in deps.

Generation flow: edit api/v1alpha1/*_types.go, then make generate manifests to regenerate deepcopies and CRDs under config/crd/.

Common commands

This repo uses the Kubebuilder Make harness (no AppsCode Docker image required), so commands run with your local Go toolchain. make downloads controller-gen, kustomize, and envtest into bin/ on first use.

• make help — list all targets with descriptions.
• make generate — regenerate DeepCopy implementations via controller-gen.
• make manifests — regenerate CRDs, RBAC, and webhook manifests under config/.
• make fmt — go fmt ./....
• make vet — go vet ./....
• make test — manifests generate fmt vet envtest; runs the envtest controller suite.
• make build — same dependencies plus a manager binary build.
• make run — run the controller against ~/.kube/config locally.
• make docker-build IMG=… / make docker-push IMG=… — build/push the manager image. make docker-buildx builds multi-arch.
• make install / make uninstall — apply / remove CRDs against the current kubectl context (uses config/crd).
• make deploy IMG=… / make undeploy — deploy the operator via config/default Kustomize bundle.

Run a single controller-runtime test:

go test ./controllers/... -run TestName -v

Conventions

• Module path is go.openviz.dev/trickster-config (vanity URL); imports must use that, not the GitHub URL (open-viz/trickster-config).
• Kubebuilder layout go.kubebuilder.io/v3. Use kubebuilder to scaffold new APIs and controllers; do not hand-create files that PROJECT should track.
• Domain is org (legacy scaffold default); API group is trickstercache.org. Do not rename without a coordinated migration — the PROJECT file and every CRD's group string would have to change in lockstep.
• License: Apache-2.0.
• Sign off commits (git commit -s).
• Vendor directory is checked in; keep go mod tidy && go mod vendor clean.
• zz_generated.*.go and everything under config/crd/bases/ are generated by make generate manifests; do not hand-edit. Change api/v1alpha1/*_types.go and re-run.
• The CRD spec is intentionally a thin wrapper over upstream Trickster config structs (github.com/trickstercache/trickster/v2/...); pin the Trickster dep deliberately when bumping, since field reshuffles upstream propagate directly into the CRD surface.