Skip to content

Update AGENTS.md #14

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
AdheipSingh merged 1 commit into from
Apr 13, 2026
Merged

Update AGENTS.md #14

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
129 changes: 43 additions & 86 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,109 +17,66 @@ specific language governing permissions and limitations
under the License.
-->

# Druid Operator — Agent Guide
# 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/).
Operational guidance for AI agents working in the druid-operator repository.

## Project Structure

| Path | Purpose |
|------|---------|
| `apis/druid/v1alpha1/` | CRD type definitions (`Druid`, `DruidIngestion`). Edit here to change the API. |
| `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/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.
| `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. |

## 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
## Working Rules

```shell
make test # Unit tests using envtest (no real cluster required)
make e2e # End-to-end tests (requires kind cluster — see below)
```
- 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.

### License audit
## Generated Artifacts

```shell
make rat # Apache RAT license header check
```
- 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.

### 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:
## Key Make Targets

```shell
make kind
make e2e
```
- `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 Submitting a PR
## Before Sending a PR

1. Run `make manifests generate` if you touched any `*_types.go` file.
1. If you changed `*_types.go`, run `make manifests` and `make generate`.
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.
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

- **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.
- 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.
Loading