Create AGENTS.md

AGENTS.md

@@ -0,0 +1,125 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Druid Operator — Agent Guide
+
+This document provides guidance for AI agents working on the druid-operator codebase. It is a Go-based Kubernetes operator for [Apache Druid](https://druid.apache.org/), built with [Kubebuilder v3](https://book.kubebuilder.io/).
+
+## Project Structure
+
+| Path | Purpose |
+|------|---------|
+| `apis/druid/v1alpha1/` | CRD type definitions (`Druid`, `DruidIngestion`). Edit here to change the API. |
+| `controllers/druid/` | Reconciler logic for the `Druid` custom resource. |
+| `controllers/ingestion/` | Reconciler logic for the `DruidIngestion` custom resource. |
+| `pkg/druidapi/` | Client for the Druid HTTP API. |
+| `pkg/http/` | Shared HTTP utilities. |
+| `pkg/util/` | General-purpose utilities. |
+| `chart/` | Helm chart for deploying the operator. CRDs live under `chart/crds/` and are **generated** — do not edit them by hand. |
+| `config/` | Kustomize manifests for CRDs, RBAC, manager, samples, and related deployment config. Only `config/crd/bases/` and `config/rbac/role.yaml` are generated — do not edit those by hand. |
+| `e2e/` | End-to-end tests. Requires a [kind](https://kind.sigs.k8s.io/) cluster. |
+| `docs/` | Documentation, including API specifications generated from Go types. |
+| `hack/` | Boilerplate and tooling scripts. |
+
+## Code Standards
+
+- All source files must include the Apache 2.0 license header. This is audited by `make rat` in CI. New files without a header will fail the check.
+- `zz_generated.deepcopy.go` is auto-generated by `controller-gen`. Never edit it manually — run `make generate` instead.
+- CRD YAML files under `config/crd/bases/` and `chart/crds/` have their Apache header prepended automatically by `make manifests`. Do not add the header manually to these files.
+- Follow standard Go conventions. Run `make fmt` and `make vet` before committing.
+
+## Key Make Targets
+
+Run `make help` to see all available targets with descriptions.
+
+### After editing `*_types.go` (API changes)
+
+These two commands **must** be run together whenever the CRD types change:
+
+```shell
+make manifests   # Regenerate CRDs, RBAC role, and webhook config
+make generate    # Regenerate DeepCopy methods (zz_generated.deepcopy.go)
+```
+
+### Formatting and linting
+
+```shell
+make fmt         # Run go fmt
+make vet         # Run go vet
+```
+
+### Testing
+
+```shell
+make test        # Unit tests using envtest (no real cluster required)
+make e2e         # End-to-end tests (requires kind cluster — see below)
+```
+
+### License audit
+
+```shell
+make rat         # Apache RAT license header check
+```
+
+### Documentation
+
+```shell
+make api-docs    # Regenerate docs/api_specifications/druid.md from Go types
+```
+
+### Building
+
+```shell
+make build                 # Compile the manager binary to bin/manager
+make docker-build          # Build the operator Docker image
+```
+
+## Running Locally with kind
+
+```shell
+make kind                      # Bootstrap a local kind cluster
+make install                   # Install CRDs into the cluster
+make run                       # Run the operator from your host (no image build needed)
+```
+
+For E2E tests, the full flow is:
+
+```shell
+make kind
+make e2e
+```
+
+## Before Submitting a PR
+
+1. Run `make manifests generate` if you touched any `*_types.go` file.
+2. Run `make fmt vet`.
+3. Run `make test` — all unit tests must pass.
+4. Run `make rat` — all files must have the Apache license header.
+5. If you changed the CRD API, run `make api-docs` to update `docs/api_specifications/druid.md`.
+6. Verify the checklist in `.github/pull_request_template.md`:
+   - Tested on a real Kubernetes cluster.
+   - Backward compatibility verified (or breaking changes noted).
+   - Documentation updated for new or modified behavior.
+
+## Common Pitfalls
+
+- **Stale generated files**: Editing `*_types.go` without running `make manifests generate` will cause the CRDs and DeepCopy methods to drift from the types. CI will catch this but it is easy to miss locally.
+- **Missing license headers**: Any new file (`.go`, `.yaml`, etc.) needs an Apache 2.0 header. Check `hack/boilerplate.go.txt` for the Go header template.
+- **E2E without kind**: `make e2e` assumes a kind cluster is running and configured. Running it without one will fail immediately.
+- **Hand-editing generated YAMLs**: Changes to `config/crd/bases/*.yaml`, `chart/crds/*.yaml`, or `config/rbac/role.yaml` will be overwritten by the next `make manifests` run.