From f3d4ca02f1f3ae732194774fb7d75aede6c0d303 Mon Sep 17 00:00:00 2001 From: Camila Macedo <7708031+camilamacedo86@users.noreply.github.com> Date: Thu, 30 Oct 2025 18:10:14 +0000 Subject: [PATCH] (docs): Add AGENTS.md to support AI tools --- .github/*.instructions.md | 1 + AGENTS.md | 224 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 225 insertions(+) create mode 100644 .github/*.instructions.md create mode 100644 AGENTS.md diff --git a/.github/*.instructions.md b/.github/*.instructions.md new file mode 100644 index 00000000000..b37eb3af2e3 --- /dev/null +++ b/.github/*.instructions.md @@ -0,0 +1 @@ +See [AGENTS.md](../AGENTS.md) for AI agent guidelines. \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000000..7ebd2ce878e --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,224 @@ +# Kubebuilder AI Agent Guide + +**Kubebuilder** is a **framework** and **command-line interface (CLI)** for building **Kubernetes APIs** using **Custom Resource Definitions (CRDs)**. +It provides scaffolding and abstractions that accelerate the development of **controllers**, **webhooks**, and **APIs** written in **Go**. + +## Quick Reference + +| Item | Value | +|------|-------| +| Language | Go >= 1.25 | +| Module | `sigs.k8s.io/kubebuilder/v4` | +| Binary | `./bin/kubebuilder` | +| Core deps | `controller-runtime`, `controller-tools`, Helm, Kustomize | +| Docs | https://book.kubebuilder.io | + +## Directory Map + +``` +pkg/ + cli/ CLI commands (init, create api, create webhook, edit, alpha) + machinery/ Scaffolding engine (templates, markers, injectors, filesystem) + model/ Resource and stage models + plugin/ Plugin interfaces and utilities + plugins/ Plugin implementations + golang/v4/ Main Go operator scaffolding (used by default combined with kustomize/v2; see PluginBundle in cli/init.go) + golang/deployimage/ Implements create api interface to generate code to deploy and manage container images with controller + common/kustomize/v2/ Kustomize manifests (used by default combined with go/v4; see PluginBundle in cli/init.go) + optional/helm/ Helm chart generation to distribute the projects (v1alpha; deprecated, v2alpha) + optional/grafana/ Grafana dashboards + optional/autoupdate/ Auto-update workflow + external/ External plugin support +docs/book/ mdBook sources + tutorial samples +test/ + e2e/ End-to-end tests (v4, helm, grafana, deployimage, alpha*) + testdata/ Testdata generation scripts +testdata/ Generated sample projects (DO NOT EDIT) +hack/docs/ Documentation generation scripts +``` + +## Critical Rules + +### NEVER Manually Edit +- `testdata/` - regenerated via `make generate-testdata` +- `docs/book/**/testdata/` - regenerated via `make generate-docs` +- `*/dist/chart/` - regenerated via `make generate-charts` + +### Always Run Before PR +```bash +make generate # Regenerate all (testdata + docs + k8s version + tidy) +make lint-fix # Auto-fix Go code style +make test-unit # Verify unit tests pass +``` + +### File-Specific Requirements +- After editing `*.go` → `make lint-fix` +- After editing `*.md` → `make remove-spaces` +- After modifying scaffolding/templates → `make generate` + +## Development Workflow + +### Build & Install +```bash +make build # Build to ./bin/kubebuilder +make install # Copy to $(go env GOBIN) +``` + +### Generate Everything +```bash +make generate # Master command (runs all below + tidy + remove-spaces) +make generate-testdata # Recreate testdata/project-* +make generate-docs # Regenerate docs samples & marker docs +make generate-charts # Rebuild Helm charts +``` + +### Lint & Format +```bash +make lint # Check only (golangci-lint + yamllint) +make lint-fix # Auto-fix Go code +``` + +### Testing +```bash +make test-unit # Fast unit tests (./pkg/..., ./test/e2e/utils/...) +make test-integration # Integration tests +make test-features # Feature tests +make test-testdata # Test all testdata projects +make test-e2e-local # Full e2e (creates kind cluster) +make test # CI aggregate (all of above + license) +``` + +## PR Submission + +### Title Format (MANDATORY) +``` +:emoji: (optional/scope): User-facing description +``` + +**Emojis:** +- ⚠️ - Breaking change +- ✨ - New feature +- 🐛 - Bug fix +- 📖 - Documentation +- 🌱 - Infrastructure/tests/non-user-facing/refactor + +**Examples:** +``` +✨ (helm/v2-alpha): Add chart generation for cluster-scoped resources +🐛: Fix project creation failure when GOBIN is unset +📖: Update migration guide for Go 1.25 compatibility +``` + +### Pre-PR Checklist +- [ ] One commit per PR (squash all) +- [ ] Add/update tests for new behavior +- [ ] Add/update docs for new behavior +- [ ] Run `make generate` +- [ ] Run `make lint-fix` +- [ ] Run `make test-unit` +- [ ] Update docs if adding features: + - `docs/book/src/reference/reference.md` for features + - `docs/book/src/plugins/plugins.md` for plugins + - `docs/book/src/reference/cli.md` for CLI changes + +## Core Concepts + +### Plugin Architecture +Plugins implement interfaces from `pkg/plugin/`: +- `Plugin` - base interface (Name, Version, SupportedProjectVersions) +- `Init` - provides `init` subcommand +- `CreateAPI` - provides `create api` subcommand +- `CreateWebhook` - provides `create webhook` subcommand +- `Edit` - provides `edit` subcommand +- `Bundle` - groups multiple plugins + +### Scaffolding Machinery +From `pkg/machinery/`: +- `Template` - file generation via Go templates +- `Inserter` - code injection at markers +- `Marker` - special comments (e.g., `// +kubebuilder:scaffold:imports`) +- `Filesystem` - abstraction over afero for testability + +### Scaffolded Project Structure +`kubebuilder init` creates: +- `cmd/main.go` - Entry point (manager setup) +- `api/v1/*_types.go` - API definitions with `+kubebuilder` markers +- `internal/controller/*_controller.go` - Reconcile logic +- `config/` - Kustomize manifests (CRDs, RBAC, manager, webhooks) +- `Dockerfile`, `Makefile` - Build and deployment automation + +### Reconciliation Pattern +Controllers implement `Reconcile(ctx, req) (ctrl.Result, error)`: +- **Idempotent** - Safe to run multiple times +- **Level-triggered** - React to current state, not events +- **Requeue on pending work** - Return `ctrl.Result{Requeue: true}` + +### Testing Pattern +E2E tests use `test/e2e/utils/test_context.go`: +```go +ctx := utils.NewTestContext("kubebuilder", "GO111MODULE=on") +ctx.Init() // Run kubebuilder init +ctx.CreateAPI(...) // Run create api +ctx.Make("build") // Run make targets +ctx.LoadImageToKindCluster() // Load image to kind +``` + +## Tool Commands + +### CLI Commands +```bash +kubebuilder init --domain example.com --repo github.com/example/myproject +kubebuilder create api --group batch --version v1 --kind CronJob +kubebuilder create webhook --group batch --version v1 --kind CronJob +kubebuilder edit --plugins=helm/v2-alpha +``` + +### Alpha Commands (Experimental) +```bash +kubebuilder alpha generate # Generate from existing PROJECT file +kubebuilder alpha update # Update to latest plugin versions +``` + +## Common Patterns + +### Code Style +- Avoid abbreviations: `context` not `ctx` (except receivers) +- Descriptive names: `projectConfig` not `pc` +- Single/double-letter receivers OK: `(c CLI)` or `(p Plugin)` + +### Testing Philosophy +- Test behaviors, not implementations +- Use real components over mocks +- Test cases as specifications (Ginkgo: `Describe`, `It`, `Context`, `By`) +- Use **Ginkgo v2** + **Gomega** for BDD-style tests. +- Tests depending on the Kubebuilder binary should use: `utils.NewTestContext(util.KubebuilderBinName, "GO111MODULE=on")` + +### Scaffolding +- Use library helpers from `pkg/plugin/util/` +- Use markers for extensibility +- Follow existing template patterns in `pkg/machinery` + +## Search Tips + +```bash +# Use rg (ripgrep) for searching +rg "pattern" --type go +rg "\\+kubebuilder:scaffold" --type go # Find markers to inject code via Machinery +rg "\\+kubebuilder" --type go # Find all markers +rg "type.*Plugin struct" pkg/plugins/ # Find plugins +``` + +## Design Philosophy + +- **Libraries over code generation** - Use libraries when possible; generated code is hard to maintain +- **Common cases easy, uncommon cases possible** - 80-90% use cases should be simple +- **Batteries included** - Projects should be deployable/testable out-of-box +- **No copy-paste** - Refactor into libraries or remote Kustomize bases + +## References + +- `Makefile` - All automation targets (source of truth for commands) +- `CONTRIBUTING.md` - CLA, pre-submit checklist, PR emoji policy +- `VERSIONING.md` - Release workflow and PR tagging +- `docs/book/` - User documentation (https://book.kubebuilder.io) +- `test/e2e/utils/test_context.go` - E2E test helpers