Skip to content

Commit f3d4ca0

Browse files
camilamacedo86camilamacedo86
committed
(docs): Add AGENTS.md to support AI tools
1 parent 17fc377 commit f3d4ca0

File tree

2 files changed

+225
-0
lines changed

2 files changed

+225
-0
lines changed

‎.github/*.instructions.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
See [AGENTS.md](../AGENTS.md) for AI agent guidelines.

‎AGENTS.md‎

Lines changed: 224 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,224 @@
1+
# Kubebuilder AI Agent Guide
2+
3+
**Kubebuilder** is a **framework** and **command-line interface (CLI)** for building **Kubernetes APIs** using **Custom Resource Definitions (CRDs)**.
4+
It provides scaffolding and abstractions that accelerate the development of **controllers**, **webhooks**, and **APIs** written in **Go**.
5+
6+
## Quick Reference
7+
8+
| Item | Value |
9+
|------|-------|
10+
| Language | Go >= 1.25 |
11+
| Module | `sigs.k8s.io/kubebuilder/v4` |
12+
| Binary | `./bin/kubebuilder` |
13+
| Core deps | `controller-runtime`, `controller-tools`, Helm, Kustomize |
14+
| Docs | https://book.kubebuilder.io |
15+
16+
## Directory Map
17+
18+
```
19+
pkg/
20+
cli/ CLI commands (init, create api, create webhook, edit, alpha)
21+
machinery/ Scaffolding engine (templates, markers, injectors, filesystem)
22+
model/ Resource and stage models
23+
plugin/ Plugin interfaces and utilities
24+
plugins/ Plugin implementations
25+
golang/v4/ Main Go operator scaffolding (used by default combined with kustomize/v2; see PluginBundle in cli/init.go)
26+
golang/deployimage/ Implements create api interface to generate code to deploy and manage container images with controller
27+
common/kustomize/v2/ Kustomize manifests (used by default combined with go/v4; see PluginBundle in cli/init.go)
28+
optional/helm/ Helm chart generation to distribute the projects (v1alpha; deprecated, v2alpha)
29+
optional/grafana/ Grafana dashboards
30+
optional/autoupdate/ Auto-update workflow
31+
external/ External plugin support
32+
docs/book/ mdBook sources + tutorial samples
33+
test/
34+
e2e/ End-to-end tests (v4, helm, grafana, deployimage, alpha*)
35+
testdata/ Testdata generation scripts
36+
testdata/ Generated sample projects (DO NOT EDIT)
37+
hack/docs/ Documentation generation scripts
38+
```
39+
40+
## Critical Rules
41+
42+
### NEVER Manually Edit
43+
- `testdata/` - regenerated via `make generate-testdata`
44+
- `docs/book/**/testdata/` - regenerated via `make generate-docs`
45+
- `*/dist/chart/` - regenerated via `make generate-charts`
46+
47+
### Always Run Before PR
48+
```bash
49+
make generate # Regenerate all (testdata + docs + k8s version + tidy)
50+
make lint-fix # Auto-fix Go code style
51+
make test-unit # Verify unit tests pass
52+
```
53+
54+
### File-Specific Requirements
55+
- After editing `*.go` → `make lint-fix`
56+
- After editing `*.md` → `make remove-spaces`
57+
- After modifying scaffolding/templates → `make generate`
58+
59+
## Development Workflow
60+
61+
### Build & Install
62+
```bash
63+
make build # Build to ./bin/kubebuilder
64+
make install # Copy to $(go env GOBIN)
65+
```
66+
67+
### Generate Everything
68+
```bash
69+
make generate # Master command (runs all below + tidy + remove-spaces)
70+
make generate-testdata # Recreate testdata/project-*
71+
make generate-docs # Regenerate docs samples & marker docs
72+
make generate-charts # Rebuild Helm charts
73+
```
74+
75+
### Lint & Format
76+
```bash
77+
make lint # Check only (golangci-lint + yamllint)
78+
make lint-fix # Auto-fix Go code
79+
```
80+
81+
### Testing
82+
```bash
83+
make test-unit # Fast unit tests (./pkg/..., ./test/e2e/utils/...)
84+
make test-integration # Integration tests
85+
make test-features # Feature tests
86+
make test-testdata # Test all testdata projects
87+
make test-e2e-local # Full e2e (creates kind cluster)
88+
make test # CI aggregate (all of above + license)
89+
```
90+
91+
## PR Submission
92+
93+
### Title Format (MANDATORY)
94+
```
95+
:emoji: (optional/scope): User-facing description
96+
```
97+
98+
**Emojis:**
99+
- ⚠️ - Breaking change
100+
- ✨ - New feature
101+
- 🐛 - Bug fix
102+
- 📖 - Documentation
103+
- 🌱 - Infrastructure/tests/non-user-facing/refactor
104+
105+
**Examples:**
106+
```
107+
✨ (helm/v2-alpha): Add chart generation for cluster-scoped resources
108+
🐛: Fix project creation failure when GOBIN is unset
109+
📖: Update migration guide for Go 1.25 compatibility
110+
```
111+
112+
### Pre-PR Checklist
113+
- [ ] One commit per PR (squash all)
114+
- [ ] Add/update tests for new behavior
115+
- [ ] Add/update docs for new behavior
116+
- [ ] Run `make generate`
117+
- [ ] Run `make lint-fix`
118+
- [ ] Run `make test-unit`
119+
- [ ] Update docs if adding features:
120+
- `docs/book/src/reference/reference.md` for features
121+
- `docs/book/src/plugins/plugins.md` for plugins
122+
- `docs/book/src/reference/cli.md` for CLI changes
123+
124+
## Core Concepts
125+
126+
### Plugin Architecture
127+
Plugins implement interfaces from `pkg/plugin/`:
128+
- `Plugin` - base interface (Name, Version, SupportedProjectVersions)
129+
- `Init` - provides `init` subcommand
130+
- `CreateAPI` - provides `create api` subcommand
131+
- `CreateWebhook` - provides `create webhook` subcommand
132+
- `Edit` - provides `edit` subcommand
133+
- `Bundle` - groups multiple plugins
134+
135+
### Scaffolding Machinery
136+
From `pkg/machinery/`:
137+
- `Template` - file generation via Go templates
138+
- `Inserter` - code injection at markers
139+
- `Marker` - special comments (e.g., `// +kubebuilder:scaffold:imports`)
140+
- `Filesystem` - abstraction over afero for testability
141+
142+
### Scaffolded Project Structure
143+
`kubebuilder init` creates:
144+
- `cmd/main.go` - Entry point (manager setup)
145+
- `api/v1/*_types.go` - API definitions with `+kubebuilder` markers
146+
- `internal/controller/*_controller.go` - Reconcile logic
147+
- `config/` - Kustomize manifests (CRDs, RBAC, manager, webhooks)
148+
- `Dockerfile`, `Makefile` - Build and deployment automation
149+
150+
### Reconciliation Pattern
151+
Controllers implement `Reconcile(ctx, req) (ctrl.Result, error)`:
152+
- **Idempotent** - Safe to run multiple times
153+
- **Level-triggered** - React to current state, not events
154+
- **Requeue on pending work** - Return `ctrl.Result{Requeue: true}`
155+
156+
### Testing Pattern
157+
E2E tests use `test/e2e/utils/test_context.go`:
158+
```go
159+
ctx := utils.NewTestContext("kubebuilder", "GO111MODULE=on")
160+
ctx.Init() // Run kubebuilder init
161+
ctx.CreateAPI(...) // Run create api
162+
ctx.Make("build") // Run make targets
163+
ctx.LoadImageToKindCluster() // Load image to kind
164+
```
165+
166+
## Tool Commands
167+
168+
### CLI Commands
169+
```bash
170+
kubebuilder init --domain example.com --repo github.com/example/myproject
171+
kubebuilder create api --group batch --version v1 --kind CronJob
172+
kubebuilder create webhook --group batch --version v1 --kind CronJob
173+
kubebuilder edit --plugins=helm/v2-alpha
174+
```
175+
176+
### Alpha Commands (Experimental)
177+
```bash
178+
kubebuilder alpha generate # Generate from existing PROJECT file
179+
kubebuilder alpha update # Update to latest plugin versions
180+
```
181+
182+
## Common Patterns
183+
184+
### Code Style
185+
- Avoid abbreviations: `context` not `ctx` (except receivers)
186+
- Descriptive names: `projectConfig` not `pc`
187+
- Single/double-letter receivers OK: `(c CLI)` or `(p Plugin)`
188+
189+
### Testing Philosophy
190+
- Test behaviors, not implementations
191+
- Use real components over mocks
192+
- Test cases as specifications (Ginkgo: `Describe`, `It`, `Context`, `By`)
193+
- Use **Ginkgo v2** + **Gomega** for BDD-style tests.
194+
- Tests depending on the Kubebuilder binary should use: `utils.NewTestContext(util.KubebuilderBinName, "GO111MODULE=on")`
195+
196+
### Scaffolding
197+
- Use library helpers from `pkg/plugin/util/`
198+
- Use markers for extensibility
199+
- Follow existing template patterns in `pkg/machinery`
200+
201+
## Search Tips
202+
203+
```bash
204+
# Use rg (ripgrep) for searching
205+
rg "pattern" --type go
206+
rg "\\+kubebuilder:scaffold" --type go # Find markers to inject code via Machinery
207+
rg "\\+kubebuilder" --type go # Find all markers
208+
rg "type.*Plugin struct" pkg/plugins/ # Find plugins
209+
```
210+
211+
## Design Philosophy
212+
213+
- **Libraries over code generation** - Use libraries when possible; generated code is hard to maintain
214+
- **Common cases easy, uncommon cases possible** - 80-90% use cases should be simple
215+
- **Batteries included** - Projects should be deployable/testable out-of-box
216+
- **No copy-paste** - Refactor into libraries or remote Kustomize bases
217+
218+
## References
219+
220+
- `Makefile` - All automation targets (source of truth for commands)
221+
- `CONTRIBUTING.md` - CLA, pre-submit checklist, PR emoji policy
222+
- `VERSIONING.md` - Release workflow and PR tagging
223+
- `docs/book/` - User documentation (https://book.kubebuilder.io)
224+
- `test/e2e/utils/test_context.go` - E2E test helpers

0 commit comments

Comments
 (0)