Skip to content

Commit 352894e

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

File tree

2 files changed

+223
-0
lines changed

2 files changed

+223
-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: 222 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,222 @@
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+
- [ ] Run `make generate`
115+
- [ ] Run `make lint-fix`
116+
- [ ] Run `make test-unit`
117+
- [ ] Update docs if adding features:
118+
- `docs/book/src/reference/reference.md` for features
119+
- `docs/book/src/plugins/plugins.md` for plugins
120+
- `docs/book/src/reference/cli.md` for CLI changes
121+
122+
## Core Concepts
123+
124+
### Plugin Architecture
125+
Plugins implement interfaces from `pkg/plugin/`:
126+
- `Plugin` - base interface (Name, Version, SupportedProjectVersions)
127+
- `Init` - provides `init` subcommand
128+
- `CreateAPI` - provides `create api` subcommand
129+
- `CreateWebhook` - provides `create webhook` subcommand
130+
- `Edit` - provides `edit` subcommand
131+
- `Bundle` - groups multiple plugins
132+
133+
### Scaffolding Machinery
134+
From `pkg/machinery/`:
135+
- `Template` - file generation via Go templates
136+
- `Inserter` - code injection at markers
137+
- `Marker` - special comments (e.g., `// +kubebuilder:scaffold:imports`)
138+
- `Filesystem` - abstraction over afero for testability
139+
140+
### Scaffolded Project Structure
141+
`kubebuilder init` creates:
142+
- `cmd/main.go` - Entry point (manager setup)
143+
- `api/v1/*_types.go` - API definitions with `+kubebuilder` markers
144+
- `internal/controller/*_controller.go` - Reconcile logic
145+
- `config/` - Kustomize manifests (CRDs, RBAC, manager, webhooks)
146+
- `Dockerfile`, `Makefile` - Build and deployment automation
147+
148+
### Reconciliation Pattern
149+
Controllers implement `Reconcile(ctx, req) (ctrl.Result, error)`:
150+
- **Idempotent** - Safe to run multiple times
151+
- **Level-triggered** - React to current state, not events
152+
- **Requeue on pending work** - Return `ctrl.Result{Requeue: true}`
153+
154+
### Testing Pattern
155+
E2E tests use `test/e2e/utils/test_context.go`:
156+
```go
157+
ctx := utils.NewTestContext("kubebuilder", "GO111MODULE=on")
158+
ctx.Init() // Run kubebuilder init
159+
ctx.CreateAPI(...) // Run create api
160+
ctx.Make("build") // Run make targets
161+
ctx.LoadImageToKindCluster() // Load image to kind
162+
```
163+
164+
## Tool Commands
165+
166+
### CLI Commands
167+
```bash
168+
kubebuilder init --domain example.com --repo github.com/example/myproject
169+
kubebuilder create api --group batch --version v1 --kind CronJob
170+
kubebuilder create webhook --group batch --version v1 --kind CronJob
171+
kubebuilder edit --plugins=helm/v2-alpha
172+
```
173+
174+
### Alpha Commands (Experimental)
175+
```bash
176+
kubebuilder alpha generate # Generate from existing PROJECT file
177+
kubebuilder alpha update # Update to latest plugin versions
178+
```
179+
180+
## Common Patterns
181+
182+
### Code Style
183+
- Avoid abbreviations: `context` not `ctx` (except receivers)
184+
- Descriptive names: `projectConfig` not `pc`
185+
- Single/double-letter receivers OK: `(c CLI)` or `(p Plugin)`
186+
187+
### Testing Philosophy
188+
- Test behaviors, not implementations
189+
- Use real components over mocks
190+
- Test cases as specifications (Ginkgo: `Describe`, `It`, `Context`, `By`)
191+
- Use **Ginkgo v2** + **Gomega** for BDD-style tests.
192+
- Tests depending on the Kubebuilder binary should use: `utils.NewTestContext(util.KubebuilderBinName, "GO111MODULE=on")`
193+
194+
### Scaffolding
195+
- Use library helpers from `pkg/plugin/util/`
196+
- Use markers for extensibility
197+
- Follow existing template patterns in `pkg/machinery`
198+
199+
## Search Tips
200+
201+
```bash
202+
# Use rg (ripgrep) for searching
203+
rg "pattern" --type go
204+
rg "\\+kubebuilder:scaffold" --type go # Find markers to inject code via Machinery
205+
rg "\\+kubebuilder" --type go # Find all markers
206+
rg "type.*Plugin struct" pkg/plugins/ # Find plugins
207+
```
208+
209+
## Design Philosophy
210+
211+
- **Libraries over code generation** - Use libraries when possible; generated code is hard to maintain
212+
- **Common cases easy, uncommon cases possible** - 80-90% use cases should be simple
213+
- **Batteries included** - Projects should be deployable/testable out-of-box
214+
- **No copy-paste** - Refactor into libraries or remote Kustomize bases
215+
216+
## References
217+
218+
- `Makefile` - All automation targets (source of truth for commands)
219+
- `CONTRIBUTING.md` - CLA, pre-submit checklist, PR emoji policy
220+
- `VERSIONING.md` - Release workflow and PR tagging
221+
- `docs/book/` - User documentation (https://book.kubebuilder.io)
222+
- `test/e2e/utils/test_context.go` - E2E test helpers

0 commit comments

Comments
 (0)