Druid Operator Agent Guide

Operational guidance for AI agents working in the druid-operator repository.

Project Structure

Path	Purpose
apis/druid/v1alpha1/	API types for Druid and DruidIngestion.
controllers/druid/	Reconciler logic for the Druid custom resource.
controllers/ingestion/	Reconciler logic for the DruidIngestion custom resource.
pkg/	Shared libraries such as the Druid API client, HTTP helpers, and utilities.
config/	Kustomize config for CRDs, RBAC, manager, samples, and deployment manifests.
chart/	Helm chart for the operator, including generated CRDs under chart/crds/.
e2e/	End-to-end test scripts and manifests.
docs/	Project docs, including generated API reference docs.
hack/	Boilerplate, templates, and tooling support files.

Working Rules

• Hand-written source, docs, and config files generally need the Apache 2.0 header.
• Do not infer header requirements from file extension alone. make rat excludes some paths, including shell scripts, zz_generated.*.go, PROJECT, .asf.yaml, and some binary or checksum artifacts.
• Never hand-edit generated files. Regenerate them with the owning Make target.
• Follow standard Go conventions. Run make fmt and make vet when validating code changes.

Generated Artifacts

• After editing *_types.go, run both make manifests and make generate.
• apis/druid/v1alpha1/zz_generated.deepcopy.go is generated by make generate.
• config/crd/bases/*.yaml and config/rbac/role.yaml are generated by make manifests.
• chart/crds/*.yaml is generated output and must not be edited by hand.
• make manifests prepends Apache headers to the generated YAML files it owns. Do not add those headers manually.

Key Make Targets

• make help: list available targets.
• make test: runs manifests, generate, fmt, vet, envtest setup, and go test ./....
• make build: lighter local compile path, but still runs manifests, generate, fmt, and vet first.
• make docker-build: heavyweight verification plus image build because it depends on make test.
• make kind: bootstrap a local kind cluster.
• make e2e: run end-to-end tests; assumes a working kind cluster.
• make api-docs: regenerate docs/api_specifications/druid.md after CRD API changes.
• make rat: run the Apache RAT license audit.

Before Sending a PR

1. If you changed *_types.go, run make manifests and make generate.
2. Run make fmt vet.
3. Run make test.
4. Run make rat.
5. If you changed the CRD API, run make api-docs.
6. Check .github/pull_request_template.md and ensure the change:
   • was tested on a real Kubernetes cluster when applicable,
   • considered backward compatibility or called out breaking changes,
   • adds comments explaining the “why” where intent is not obvious,
   • updates docs for new or changed behavior.

Common Pitfalls

• Editing *_types.go without regenerating manifests and DeepCopy code.
• Hand-editing generated YAML under config/crd/bases/, config/rbac/role.yaml, or chart/crds/.
• Adding license headers mechanically to excluded or generated files.
• Treating make docker-build as a cheap local smoke test.