Skip to content

Commit f038b60

Browse files
camilamacedo86camilamacedo86
committed
Add agents
1 parent 045b3e1 commit f038b60

File tree

1 file changed

+179
-0
lines changed

1 file changed

+179
-0
lines changed

‎AGENTS.md‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
# AGENTS.md
2+
3+
## Kubebuilder
4+
5+
### Project Overview
6+
7+
**Kubebuilder** is a **framework** and **command-line interface (CLI)** for building **Kubernetes APIs** using **Custom Resource Definitions (CRDs)**.
8+
It provides scaffolding and abstractions that accelerate the development of **controllers**, **webhooks**, and **APIs** written in **Go**.
9+
10+
- **GitHub:** <https://github.com/kubernetes-sigs/kubebuilder>
11+
- **Go module:** `sigs.k8s.io/kubebuilder/v4` (requires **Go ≥1.25**)
12+
- **Core libraries:** `controller-runtime`, `controller-tools`
13+
14+
---
15+
16+
## Core Components
17+
18+
### controller-runtime
19+
- **Repository:** [kubernetes-sigs/controller-runtime](https://github.com/kubernetes-sigs/controller-runtime)
20+
- **Purpose:** Runtime building blocks for controllers.
21+
- **Capabilities:**
22+
- Define and manage **controllers** and **reconcilers**
23+
- Run **managers** coordinating multiple controllers
24+
- Register and handle **webhooks**
25+
- Expose **metrics** and **health probes**
26+
27+
### controller-tools
28+
- **Repository:** [kubernetes-sigs/controller-tools](https://github.com/kubernetes-sigs/controller-tools)
29+
- **Purpose:** Code and manifest generation.
30+
- **Capabilities:**
31+
- Generate **CRDs**, **RBAC**, **OpenAPI** specs
32+
- Provide Make targets: `make generate`, `make manifests`, etc.
33+
34+
---
35+
36+
## Extensibility and Integrations
37+
38+
- **Library mode:** Kubebuilder can be imported as a library by other SDKs.
39+
- **Example:** [Operator SDK](https://github.com/operator-framework/operator-sdk) builds on Kubebuilder for Ansible/Helm operators.
40+
- **Extension docs:** [docs/book/src/plugins/extending](https://github.com/kubernetes-sigs/kubebuilder/tree/master/docs/book/src/plugins/extending)
41+
42+
---
43+
44+
## Architecture
45+
46+
- **Design:** Modular, plugin-based.
47+
- **Core Plugins:**
48+
- `pkg/plugins/golang/v4` — scaffolds Go projects
49+
- `pkg/plugins/common/kustomize/v2` — scaffolds the `config/` dir using Kustomize
50+
- **Additional Plugins:**
51+
- `pkg/plugins/helm/v2-alpha` — Helm-based operators
52+
- `pkg/plugins/deploy-image` — container image support
53+
- `pkg/plugins/autoupdate/v1-alpha` — upgrade automation
54+
- Full list under [docs/book/src/plugins/available](https://github.com/kubernetes-sigs/kubebuilder/tree/master/docs/book/src/plugins/available)
55+
56+
---
57+
58+
## Repository Layout
59+
60+
| Path | Purpose |
61+
|---------------------------------------------------------|--------------------------------------------------|
62+
| `cmd/` | CLI entry point |
63+
| `pkg/plugins/` | Built-in plugins (Golang, Kustomize, Helm, etc.) |
64+
| `pkg/cli`, `pkg/machinery`, `pkg/model`, `pkg/internal` | Core framework used by plugins |
65+
| `hack/docs/` | Doc build scripts (`generate.sh`) |
66+
| `docs/book/` | User guide sources |
67+
| `testdata/` | Canonical scaffolded sample projects |
68+
| `test/` | Integration & E2E tests (`e2e/`, `features.sh`) |
69+
| `designs/` | PEPs and design proposals |
70+
| `roadmap/` | Release goals by year |
71+
72+
---
73+
74+
## Build & Test Commands
75+
76+
### Build Kubebuilder
77+
78+
```bash
79+
# Build local binary into ./bin/
80+
make build
81+
82+
# Install into $GOBIN so `kubebuilder` is on PATH
83+
make install
84+
```
85+
86+
> After modifying scaffolding or code generation, run:
87+
```bash
88+
make generate
89+
```
90+
91+
### Lint & Style Checks
92+
93+
```bash
94+
# Validate and fix code style issues
95+
make lint-fix
96+
```
97+
98+
---
99+
100+
## Testing Instructions
101+
102+
### Pre-requisites
103+
104+
To run tests under `test/` you need:
105+
- **Go**
106+
- **Docker**
107+
- **[kind](https://kind.sigs.k8s.io/)** (Kubernetes-in-Docker)
108+
- **Kubebuilder binary** built and installed locally
109+
110+
### Cluster setup
111+
112+
```bash
113+
# Install kubebuilder binary
114+
make install
115+
116+
# Clean up any existing test cluster
117+
kind delete cluster
118+
119+
# Create a new kind cluster
120+
kind create cluster
121+
```
122+
123+
Ensure `kubectl config current-context` points to `kind-kind` before running tests.
124+
125+
### Running e2e tests
126+
127+
```bash
128+
# Run all tests
129+
go test ./test/... -v
130+
```
131+
132+
The test suite includes both:
133+
- **Unit tests** — run locally without cluster dependencies.
134+
- **Integration / E2E tests** — under `test/e2e/`, which require a running kind cluster.
135+
136+
### Notes for automation agents
137+
138+
- Always ensure a clean kind environment before running E2E tests.
139+
- Some E2E scripts (e.g., `test/features.sh`) assume Docker-in-Docker capability.
140+
- Tests depending on the Kubebuilder binary should use:
141+
```go
142+
utils.NewTestContext(util.KubebuilderBinName, "GO111MODULE=on")
143+
```
144+
from `test/e2e/utils`.
145+
146+
---
147+
148+
## Code Style Guidelines
149+
150+
- Use `gofmt` and `goimports` formatting (`make lint-fix` automates both).
151+
- Run `make generate` after any scaffold or API change.
152+
- Regenerate documentation with:
153+
```bash
154+
make generate-docs
155+
```
156+
- Regenerate Helm plugin assets with:
157+
```bash
158+
make generate-charts
159+
```
160+
- Remove spaces after changes in the docs:
161+
```bash
162+
make remove-spaces
163+
```
164+
- Use **Ginkgo v2** + **Gomega** for BDD-style tests.
165+
- Tutorials embed executable code fragments marked with `/**? ... */`; regenerate via `make generate-docs`.
166+
167+
---
168+
169+
## Summary
170+
171+
| Aspect | Description |
172+
|--------------------|------------------------------------------------------------------|
173+
| **Purpose** | Framework & CLI to scaffold Kubernetes APIs and controllers |
174+
| **Language** | Go |
175+
| **Architecture** | Modular, plugin-driven |
176+
| **Core Libraries** | controller-runtime, controller-tools |
177+
| **Extensibility** | Plugin system; foundation for others tools. Example Operator SDK |
178+
| **Scaffolding** | Generates Go code, CRDs, RBAC, and manifests |
179+
| **Ecosystem Role** | Core tool for Kubernetes operators & controllers |

0 commit comments

Comments
 (0)