{"owner":"kubernetes-sigs","repo":"kubebuilder","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# Kubebuilder AI Agent Guide\n\n**Kubebuilder** is a **framework** and **command-line interface (CLI)** for building **Kubernetes APIs** using **Custom Resource Definitions (CRDs)**.\nIt provides scaffolding and abstractions that accelerate the development of **controllers**, **webhooks**, and **APIs** written in **Go**.\n\n## Quick Reference\n\n| Item       | Value                                                     |\n|------------|-----------------------------------------------------------|\n| Language   | Defined in the go.mod                                     |\n| Module     | `sigs.k8s.io/kubebuilder/v4`                              |\n| Binary     | `./bin/kubebuilder`                                       |\n| Core deps  | `controller-runtime`, `controller-tools`, Helm, Kustomize |\n| Docs       | https://book.kubebuilder.io                               |\n\n\n## Directory Map\n\n```\npkg/\n  cli/              CLI command implementations\n    alpha/          Alpha/experimental commands (generate, update, etc.)\n    init.go         'init' command + default PluginBundle definition\n    api.go          'create api' command\n    webhook.go      'create webhook' command\n    edit.go         'edit' command\n    root.go         Root command setup\n  machinery/        Scaffolding engine (templates, markers, injectors)\n    template.go     Base template interface\n    inserter.go     Code injection engine\n    marker.go       Marker detection and processing\n    filesystem.go   Filesystem abstraction (uses afero)\n  model/\n    resource/       Resource model (GVK, API, Controller, Webhook)\n    stage/          Plugin execution stages\n  plugin/           Plugin interfaces and utilities\n    interface.go    Core plugin interfaces (Plugin, Init, CreateAPI, etc.)\n    bundle.go       Plugin composition\n    util/           Helper functions for plugin authors\n  plugins/          Plugin implementations (ADD NEW PLUGINS HERE)\n    golang/v4/      Main Go scaffolding (default for go projects)\n      scaffolds/    Scaffolding for init, api, webhook\n        internal/templates/  Template implementations\n    golang/deployimage/  Deploy-image pattern plugin\n    common/kustomize/v2/  Kustomize manifest generation (default)\n    optional/       Optional plugins (enabled via --plugins flag)\n      helm/         Helm chart generation (v1alpha deprecated, v2alpha current)\n      grafana/      Grafana dashboard generation\n      autoupdate/   Auto-update GitHub workflow\n    external/       External plugin support (exec-based plugins)\ndocs/book/          mdBook documentation (https://book.kubebuilder.io)\n  src/              Markdown source files\n    **/testdata/    Sample projects used in docs (regenerated)\ntest/\n  e2e/              E2E tests requiring Kubernetes cluster\n    v4/             Tests for v4 plugin\n    helm/           Tests for Helm plugin\n    deployimage/    Tests for deploy-image plugin\n    utils/          Test helpers (TestContext, etc.)\n  testdata/         Scripts to generate testdata projects\n    generate.sh     Main generation script\n    test.sh         Tests all testdata projects\ntestdata/           Generated complete sample projects (DO NOT EDIT)\n  project-v4/                    Basic v4 project\n  project-v4-multigroup/         Multigroup project\n  project-v4-with-plugins/       Project with optional plugins\nhack/docs/          Documentation generation\n  generate.sh       Regenerate docs samples + marker docs\n  generate_samples.go  Sample generation logic\ncmd/                CLI entry point\n  version.go        Version info (updated by make update-k8s-version)\nmain.go             Application entry point\n```\n\n**Key Locations for Common Tasks:**\n- Add new plugin → `pkg/plugins/<category>/<name>/`\n- Add new template → `pkg/plugins/<plugin>/scaffolds/internal/templates/`\n- Modify CLI commands → `pkg/cli/`\n- Add scaffolding machinery → `pkg/machinery/`\n- Add tests → `test/e2e/all/plugin_<name>_test.go` or `pkg/<package>/*_test.go`\n\n## Critical Rules\n\n### Do Not Manually Edit Generated Files\n- `testdata/` - regenerated via `make generate-testdata`\n- `docs/book/**/testdata/` - regenerated via `make generate-docs`\n- `*/dist/chart/` - regenerated via `make generate-charts`\n\n### File-Specific Requirements\n\nAfter making changes, run the appropriate commands based on what you modified:\n\n**Generate Commands (rebuild artifacts):**\n- **If you modify files in `hack/docs/internal/`** → run `make install && make generate-docs`\n- **If you modify files in `pkg/plugins/optional/helm/`** → run `make install && make generate-charts`\n- **If you modify any boilerplate/template files** → run `make install && make generate`\n\n**Formatting Commands:**\n- After editing `*.go` → `make lint-fix`\n- After editing `*.md` → `make remove-spaces`\n\n**Always Run Before PR:**\n```bash\nmake lint-fix    # Auto-fix Go code style\nmake test-unit   # Verify unit tests pass\n```\n\n**Note:** Boilerplate/template files are Go files that define scaffolding templates, typically located in `pkg/plugins/**/scaffolds/internal/templates/` or files that generate code/configs for scaffolded projects.\n\n## Development Workflow\n\n### Build & Install\n```bash\nmake build    # Build to ./bin/kubebuilder\nmake install  # Copy to $(go env GOBIN)\n```\n\n### Lint & Format\n```bash\nmake lint       # Check only (golangci-lint + yamllint)\nmake lint-fix   # Auto-fix Go code\n```\n\n### Testing\n```bash\nmake test-unit         # Fast unit tests (./pkg/..., ./test/e2e/utils/...)\nmake test-integration  # Integration tests (may create temp dirs, download binaries)\nmake test-testdata     # Test all testdata projects\nmake test-e2e-local    # Full e2e (creates kind cluster)\nmake test              # CI aggregate (all of above + license)\n```\n\n## PR Submission\n\n### PR Title Format (MANDATORY)\n\nPR titles use **emojis** (appear in release notes).\n\nFormat: `:emoji: [(plugin/version)]: Description`\n\nThe `(plugin/version)` scope is optional; omit it for repo-wide or documentation-only changes.\n\n**Emojis:**\n- ⚠️ (`:warning:`) - Breaking change\n- ✨ (`:sparkles:`) - New feature\n- 🐛 (`:bug:`) - Bug fix\n- 📖 (`:book:`) - Documentation\n- 🌱 (`:seedling:`) - Infrastructure/tests/refactor\n\n**Examples:**\n```\n🐛 Resolve nil pointer panic in scaffold generator\n✨ (helm/v2-alpha): Add cluster-scoped resource support\n📖 (go/v4): Update deployment documentation\n✨ Update dependencies to latest versions\n```\n\n### Commit Message Format\n\nCommit messages follow the [Conventional Commits](https://www.conventionalcommits.org/) standard.\n\nFormat: `<type>[optional scope]: <description>`\n\nThe `[optional scope]` is typically the plugin/version (e.g., `helm/v2-alpha`, `go/v4`); omit it for repo-wide or non-plugin changes.\n\n**Types:**\n\n- **feat**: A new feature for the user or a plugin\n- **fix**: A bug fix for the user or a plugin\n- **docs**: Documentation changes only\n- **test**: Adding or updating tests\n- **refactor**: Code change that neither fixes a bug nor adds a feature\n- **chore**: Changes to build process, dependencies, or maintenance tasks\n- **breaking**: A breaking change (can be combined with other types)\n\n**Examples:**\n```\nfix: Resolve nil pointer panic in scaffold generator\nfeat(helm/v2-alpha): Add cluster-scoped resource support\ndocs(go/v4): Update deployment documentation\nchore: Update dependencies to latest versions\n```\n\n### Pre-PR Checklist\n- [ ] One commit per PR (squash all)\n- [ ] Add/update tests for new behavior\n- [ ] Add/update docs for new behavior\n- [ ] Run `make lint-fix`\n- [ ] Run `make install`\n- [ ] Run `make generate`\n- [ ] Run `make test-unit`\n\n## Core Concepts\n\n### Plugin Architecture\n\nPlugins implement interfaces from `pkg/plugin/`:\n- `Plugin` - base interface (Name, Version, SupportedProjectVersions)\n- `Init` - project initialization (`kubebuilder init`)\n- `CreateAPI` - API creation (`kubebuilder create api`)\n- `CreateWebhook` - webhook creation (`kubebuilder create webhook`)\n- `Edit` - post-init modifications (`kubebuilder edit`)\n- `Bundle` - groups multiple plugins\n\n**Plugin Bundles:**\n\nDefault bundle (`pkg/cli/init.go`): `go.kubebuilder.io/v4` + `kustomize.common.kubebuilder.io/v2`\n\nPlugins resolve via `pkg/plugin` registry and execute in order.\n\n**External Plugins:**\n\nExecutable binaries in `pkg/plugins/external/` that communicate via JSON over stdin/stdout.\n\n### Scaffolding Machinery\n\nFrom `pkg/machinery/`:\n- `Template` - file generation via Go templates\n- `Inserter` - code injection at markers\n- `Marker` - special comments (e.g., `// +kubebuilder:scaffold:imports`)\n- `Filesystem` - abstraction over afero for testability\n\n### Scaffolded Project Structure\n\nProjects generated by the Kubebuilder CLI use the default plugin bundle (`go/v4` + `kustomize/v2`). Each plugin scaffolds different files:\n\n**`go/v4` plugin scaffolds Go code:**\n- `cmd/main.go` - Entry point (manager setup)\n- `api/v1/*_types.go` - API definitions with `+kubebuilder` markers (via `create api`)\n- `internal/controller/*_controller.go` - Reconcile logic (via `create api`)\n- `Dockerfile`, `Makefile` - Build and deployment automation\n\n**`kustomize/v2` plugin scaffolds manifests:**\n- `config/` - Kustomize base manifests (CRDs, RBAC, manager, webhooks)\n- `config/crd/` - Custom Resource Definitions (via `create api`)\n- `config/samples/` - Example CR manifests (via `create api`)\n\n**`PROJECT` file:**\n- Project configuration tracking plugins, resources, domain, and layout\n\n**Note:** These are files in projects generated BY Kubebuilder, not the Kubebuilder source code itself.\n\n### Reconciliation Pattern\n\nControllers implement `Reconcile(ctx, req) (ctrl.Result, error)`:\n\n- **Idempotent** - Safe to run multiple times\n- **Level-triggered** - React to current state, not events\n- **Requeue on pending work** - Return `ctrl.Result{Requeue: true}`\n\n### Testing Pattern\nE2E tests use `utils.TestContext` from `test/e2e/utils/test_context.go`:\n\n```go\nctx := utils.NewTestContext(util.KubebuilderBinName, \"GO111MODULE=on\")\nctx.Init(\"--domain\", \"example.com\", \"--repo\", \"example.com/project\")\nctx.CreateAPI(\"--group\", \"crew\", \"--version\", \"v1\", \"--kind\", \"Captain\")\nctx.Make(\"build\", \"test\")\nctx.LoadImageToKindCluster()\n```\n\n## CLI Reference\n\nAfter `make install`:\n\n```bash\nkubebuilder init --domain example.com --repo github.com/example/myproject\nkubebuilder create api --group batch --version v1 --kind CronJob\nkubebuilder create webhook --group batch --version v1 --kind CronJob\nkubebuilder edit --plugins=helm/v2-alpha\nkubebuilder alpha generate    # Experimental: generate from PROJECT file\nkubebuilder alpha update      # Experimental: update to latest plugin versions\n```\n\n## Common Patterns\n\n### Code Style\n- Avoid abbreviations: `context` not `ctx` (except receivers)\n- Descriptive names: `projectConfig` not `pc`\n- Single/double-letter receivers OK: `(c CLI)` or `(p Plugin)`\n\n### Logging Conventions\n\nKubebuilder has two distinct types of code with different logging conventions:\n\n**1. Kubebuilder CLI Tool Code** → Go CLI best practices\n\nApplies to: `pkg/cli/*`, `pkg/plugins/*`, `pkg/machinery/*`, `pkg/config/*`, `pkg/model/*`, etc.\n\nThis is the Kubebuilder tool itself. Follow Go logging conventions for CLI tools:\n- **First word lowercase**, sentences after periods capitalized: `\"unable to find file. This file is required for...\"`\n- **No ending punctuation** (but use periods between sentences)\n- **Error strings lowercase**: `fmt.Errorf(\"something bad\")`\n\n```go\nlog.Info(\"writing scaffold for you to edit\")\nlog.Warn(\"unable to find boilerplate file. This file is used to generate the license header\")\nlog.Error(\"failed to read file\", \"file\", path)\nreturn fmt.Errorf(\"failed to load config: %w\", err)\n```\n\n**2. Generated Code (Template Output)** → Kubernetes conventions\n\nApplies to: Code GENERATED by templates in `pkg/plugins/*/scaffolds/internal/templates/*`\n\nTemplates produce controller code that runs in Kubernetes clusters. The GENERATED code follows Kubernetes conventions:\n- **Start with capital letter**: `\"Starting reconciliation\"`\n- **No ending period** (but use periods between sentences)\n- **Past tense**: `\"Failed to create Pod\"` not `\"Cannot create Pod\"`\n- **Active voice**: specify subject or omit when it's the program itself\n- **Specify object type**: `\"Created Deployment\"` not `\"Created\"`\n\n```go\n// In template files that generate controller code:\nlog.Info(\"Starting reconciliation\")\nlog.Info(\"Created Deployment\", \"name\", deploy.Name)\nlog.Error(err, \"Failed to create Pod\", \"name\", name)\n```\n\n**Note:** The distinction is based on WHERE the code runs:\n- CLI tool (runs on developer's machine) → Go conventions\n- Generated controllers (run in Kubernetes cluster) → Kubernetes conventions\n\n### Testing Philosophy\n- Test behaviors, not implementations\n- Use real components over mocks\n- Test cases as specifications (Ginkgo: `Describe`, `It`, `Context`, `By`)\n- Use **Ginkgo v2** + **Gomega** for BDD-style tests.\n- Tests depending on the Kubebuilder binary should use: `utils.NewTestContext(util.KubebuilderBinName, \"GO111MODULE=on\")`\n\n### Test Organization\n\n- **Unit tests** (`*_test.go` in `pkg/`) - Test individual packages in isolation, fast\n- **Integration tests** (`*_integration_test.go` in `pkg/`) - Test multiple components together without cluster\n  - Must have `//go:build integration` tag at the top\n  - May create temp dirs, download binaries, or scaffold files\n  - Examples: alpha update, grafana scaffolding, helm chart generation\n- **E2E tests** (`test/e2e/`) - **ONLY** for tests requiring a Kubernetes cluster (KIND)\n  - `v4/plugin_cluster_test.go` - Test v4 plugin deployment\n  - `helm/plugin_cluster_test.go` - Test Helm chart deployment\n  - `deployimage/plugin_cluster_test.go` - Test deploy-image plugin\n\n### Scaffolding\n- Use library helpers from `pkg/plugin/util/`\n- Use markers for extensibility\n- Follow existing template patterns in `pkg/machinery`\n\n## Search Tips\n\n```bash\nrg \"\\\\+kubebuilder:scaffold\" --type go  # Find markers\nrg \"type.*Plugin struct\" pkg/plugins/   # Plugin implementations\nrg \"PluginBundle\" pkg/cli/              # Plugin registration\nrg \"func.*SetTemplateDefaults\"          # Template definitions\nrg \"func new.*Command\" pkg/cli/         # CLI commands\nrg \"NewTestContext\" test/e2e/           # E2E test setup\n```\n\n## Design Philosophy\n\n- **Libraries over code generation** - Use libraries when possible; generated code is hard to maintain\n- **Common cases easy, uncommon cases possible** - 80-90% use cases should be simple\n- **Batteries included** - Projects should be deployable/testable out-of-box\n- **No copy-paste** - Refactor into libraries or remote Kustomize bases\n\n## References\n\n### Essential Files\n- **`Makefile`** - All automation targets (source of truth for build/test commands)\n- **`CONTRIBUTING.md`** - CLA, pre-submit checklist, PR requirements\n- **`VERSIONING.md`** - Release workflow, versioning policy, PR tagging\n- **`go.mod`** - Go version and dependencies\n\n### Key Directories\n- **`pkg/`** - Core Kubebuilder code (CLI, plugins, machinery)\n- **`test/e2e/`** - End-to-end tests with Kubernetes cluster\n- **`testdata/`** - Generated sample projects (regenerated automatically)\n- **`docs/book/`** - User documentation source (https://book.kubebuilder.io)\n\n### Important Code Files\n- **`pkg/cli/init.go`** - Default plugin bundle definition\n- **`pkg/plugin/interface.go`** - Plugin interface definitions\n- **`pkg/machinery/scaffold.go`** - Scaffolding engine\n- **`test/e2e/utils/test_context.go`** - E2E test helpers\n- **`cmd/version.go`** - Version info (includes K8S version)\n\n### Scripts\n- **`test/testdata/generate.sh`** - Regenerate all testdata projects\n- **`hack/docs/generate.sh`** - Regenerate documentation samples\n- **`test/e2e/local.sh`** - Run e2e tests locally with Kind\n\n### External Resources\n- **Kubebuilder Book**: https://book.kubebuilder.io\n- **Kubebuilder Repo**: https://github.com/kubernetes-sigs/kubebuilder\n- **controller-runtime**: https://github.com/kubernetes-sigs/controller-runtime\n- **controller-tools**: https://github.com/kubernetes-sigs/controller-tools\n- **API Conventions**: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md\n- **Operator Pattern**: https://kubernetes.io/docs/concepts/extend-kubernetes/operator/\n- **Kubernetes Logging Conventions:** https://github.com/kubernetes/community/blob/master/contributors/devel/sig-instrumentation/logging.md#message-style-guidelines\n- **Structured Logging Guidelines:** https://github.com/kubernetes/community/blob/master/contributors/devel/sig-instrumentation/migration-to-structured-logging.md\n"},"files":{"AGENTS.md":"# Kubebuilder AI Agent Guide\n\n**Kubebuilder** is a **framework** and **command-line interface (CLI)** for building **Kubernetes APIs** using **Custom Resource Definitions (CRDs)**.\nIt provides scaffolding and abstractions that accelerate the development of **controllers**, **webhooks**, and **APIs** written in **Go**.\n\n## Quick Reference\n\n| Item       | Value                                                     |\n|------------|-----------------------------------------------------------|\n| Language   | Defined in the go.mod                                     |\n| Module     | `sigs.k8s.io/kubebuilder/v4`                              |\n| Binary     | `./bin/kubebuilder`                                       |\n| Core deps  | `controller-runtime`, `controller-tools`, Helm, Kustomize |\n| Docs       | https://book.kubebuilder.io                               |\n\n\n## Directory Map\n\n```\npkg/\n  cli/              CLI command implementations\n    alpha/          Alpha/experimental commands (generate, update, etc.)\n    init.go         'init' command + default PluginBundle definition\n    api.go          'create api' command\n    webhook.go      'create webhook' command\n    edit.go         'edit' command\n    root.go         Root command setup\n  machinery/        Scaffolding engine (templates, markers, injectors)\n    template.go     Base template interface\n    inserter.go     Code injection engine\n    marker.go       Marker detection and processing\n    filesystem.go   Filesystem abstraction (uses afero)\n  model/\n    resource/       Resource model (GVK, API, Controller, Webhook)\n    stage/          Plugin execution stages\n  plugin/           Plugin interfaces and utilities\n    interface.go    Core plugin interfaces (Plugin, Init, CreateAPI, etc.)\n    bundle.go       Plugin composition\n    util/           Helper functions for plugin authors\n  plugins/          Plugin implementations (ADD NEW PLUGINS HERE)\n    golang/v4/      Main Go scaffolding (default for go projects)\n      scaffolds/    Scaffolding for init, api, webhook\n        internal/templates/  Template implementations\n    golang/deployimage/  Deploy-image pattern plugin\n    common/kustomize/v2/  Kustomize manifest generation (default)\n    optional/       Optional plugins (enabled via --plugins flag)\n      helm/         Helm chart generation (v1alpha deprecated, v2alpha current)\n      grafana/      Grafana dashboard generation\n      autoupdate/   Auto-update GitHub workflow\n    external/       External plugin support (exec-based plugins)\ndocs/book/          mdBook documentation (https://book.kubebuilder.io)\n  src/              Markdown source files\n    **/testdata/    Sample projects used in docs (regenerated)\ntest/\n  e2e/              E2E tests requiring Kubernetes cluster\n    v4/             Tests for v4 plugin\n    helm/           Tests for Helm plugin\n    deployimage/    Tests for deploy-image plugin\n    utils/          Test helpers (TestContext, etc.)\n  testdata/         Scripts to generate testdata projects\n    generate.sh     Main generation script\n    test.sh         Tests all testdata projects\ntestdata/           Generated complete sample projects (DO NOT EDIT)\n  project-v4/                    Basic v4 project\n  project-v4-multigroup/         Multigroup project\n  project-v4-with-plugins/       Project with optional plugins\nhack/docs/          Documentation generation\n  generate.sh       Regenerate docs samples + marker docs\n  generate_samples.go  Sample generation logic\ncmd/                CLI entry point\n  version.go        Version info (updated by make update-k8s-version)\nmain.go             Application entry point\n```\n\n**Key Locations for Common Tasks:**\n- Add new plugin → `pkg/plugins/<category>/<name>/`\n- Add new template → `pkg/plugins/<plugin>/scaffolds/internal/templates/`\n- Modify CLI commands → `pkg/cli/`\n- Add scaffolding machinery → `pkg/machinery/`\n- Add tests → `test/e2e/all/plugin_<name>_test.go` or `pkg/<package>/*_test.go`\n\n## Critical Rules\n\n### Do Not Manually Edit Generated Files\n- `testdata/` - regenerated via `make generate-testdata`\n- `docs/book/**/testdata/` - regenerated via `make generate-docs`\n- `*/dist/chart/` - regenerated via `make generate-charts`\n\n### File-Specific Requirements\n\nAfter making changes, run the appropriate commands based on what you modified:\n\n**Generate Commands (rebuild artifacts):**\n- **If you modify files in `hack/docs/internal/`** → run `make install && make generate-docs`\n- **If you modify files in `pkg/plugins/optional/helm/`** → run `make install && make generate-charts`\n- **If you modify any boilerplate/template files** → run `make install && make generate`\n\n**Formatting Commands:**\n- After editing `*.go` → `make lint-fix`\n- After editing `*.md` → `make remove-spaces`\n\n**Always Run Before PR:**\n```bash\nmake lint-fix    # Auto-fix Go code style\nmake test-unit   # Verify unit tests pass\n```\n\n**Note:** Boilerplate/template files are Go files that define scaffolding templates, typically located in `pkg/plugins/**/scaffolds/internal/templates/` or files that generate code/configs for scaffolded projects.\n\n## Development Workflow\n\n### Build & Install\n```bash\nmake build    # Build to ./bin/kubebuilder\nmake install  # Copy to $(go env GOBIN)\n```\n\n### Lint & Format\n```bash\nmake lint       # Check only (golangci-lint + yamllint)\nmake lint-fix   # Auto-fix Go code\n```\n\n### Testing\n```bash\nmake test-unit         # Fast unit tests (./pkg/..., ./test/e2e/utils/...)\nmake test-integration  # Integration tests (may create temp dirs, download binaries)\nmake test-testdata     # Test all testdata projects\nmake test-e2e-local    # Full e2e (creates kind cluster)\nmake test              # CI aggregate (all of above + license)\n```\n\n## PR Submission\n\n### PR Title Format (MANDATORY)\n\nPR titles use **emojis** (appear in release notes).\n\nFormat: `:emoji: [(plugin/version)]: Description`\n\nThe `(plugin/version)` scope is optional; omit it for repo-wide or documentation-only changes.\n\n**Emojis:**\n- ⚠️ (`:warning:`) - Breaking change\n- ✨ (`:sparkles:`) - New feature\n- 🐛 (`:bug:`) - Bug fix\n- 📖 (`:book:`) - Documentation\n- 🌱 (`:seedling:`) - Infrastructure/tests/refactor\n\n**Examples:**\n```\n🐛 Resolve nil pointer panic in scaffold generator\n✨ (helm/v2-alpha): Add cluster-scoped resource support\n📖 (go/v4): Update deployment documentation\n✨ Update dependencies to latest versions\n```\n\n### Commit Message Format\n\nCommit messages follow the [Conventional Commits](https://www.conventionalcommits.org/) standard.\n\nFormat: `<type>[optional scope]: <description>`\n\nThe `[optional scope]` is typically the plugin/version (e.g., `helm/v2-alpha`, `go/v4`); omit it for repo-wide or non-plugin changes.\n\n**Types:**\n\n- **feat**: A new feature for the user or a plugin\n- **fix**: A bug fix for the user or a plugin\n- **docs**: Documentation changes only\n- **test**: Adding or updating tests\n- **refactor**: Code change that neither fixes a bug nor adds a feature\n- **chore**: Changes to build process, dependencies, or maintenance tasks\n- **breaking**: A breaking change (can be combined with other types)\n\n**Examples:**\n```\nfix: Resolve nil pointer panic in scaffold generator\nfeat(helm/v2-alpha): Add cluster-scoped resource support\ndocs(go/v4): Update deployment documentation\nchore: Update dependencies to latest versions\n```\n\n### Pre-PR Checklist\n- [ ] One commit per PR (squash all)\n- [ ] Add/update tests for new behavior\n- [ ] Add/update docs for new behavior\n- [ ] Run `make lint-fix`\n- [ ] Run `make install`\n- [ ] Run `make generate`\n- [ ] Run `make test-unit`\n\n## Core Concepts\n\n### Plugin Architecture\n\nPlugins implement interfaces from `pkg/plugin/`:\n- `Plugin` - base interface (Name, Version, SupportedProjectVersions)\n- `Init` - project initialization (`kubebuilder init`)\n- `CreateAPI` - API creation (`kubebuilder create api`)\n- `CreateWebhook` - webhook creation (`kubebuilder create webhook`)\n- `Edit` - post-init modifications (`kubebuilder edit`)\n- `Bundle` - groups multiple plugins\n\n**Plugin Bundles:**\n\nDefault bundle (`pkg/cli/init.go`): `go.kubebuilder.io/v4` + `kustomize.common.kubebuilder.io/v2`\n\nPlugins resolve via `pkg/plugin` registry and execute in order.\n\n**External Plugins:**\n\nExecutable binaries in `pkg/plugins/external/` that communicate via JSON over stdin/stdout.\n\n### Scaffolding Machinery\n\nFrom `pkg/machinery/`:\n- `Template` - file generation via Go templates\n- `Inserter` - code injection at markers\n- `Marker` - special comments (e.g., `// +kubebuilder:scaffold:imports`)\n- `Filesystem` - abstraction over afero for testability\n\n### Scaffolded Project Structure\n\nProjects generated by the Kubebuilder CLI use the default plugin bundle (`go/v4` + `kustomize/v2`). Each plugin scaffolds different files:\n\n**`go/v4` plugin scaffolds Go code:**\n- `cmd/main.go` - Entry point (manager setup)\n- `api/v1/*_types.go` - API definitions with `+kubebuilder` markers (via `create api`)\n- `internal/controller/*_controller.go` - Reconcile logic (via `create api`)\n- `Dockerfile`, `Makefile` - Build and deployment automation\n\n**`kustomize/v2` plugin scaffolds manifests:**\n- `config/` - Kustomize base manifests (CRDs, RBAC, manager, webhooks)\n- `config/crd/` - Custom Resource Definitions (via `create api`)\n- `config/samples/` - Example CR manifests (via `create api`)\n\n**`PROJECT` file:**\n- Project configuration tracking plugins, resources, domain, and layout\n\n**Note:** These are files in projects generated BY Kubebuilder, not the Kubebuilder source code itself.\n\n### Reconciliation Pattern\n\nControllers implement `Reconcile(ctx, req) (ctrl.Result, error)`:\n\n- **Idempotent** - Safe to run multiple times\n- **Level-triggered** - React to current state, not events\n- **Requeue on pending work** - Return `ctrl.Result{Requeue: true}`\n\n### Testing Pattern\nE2E tests use `utils.TestContext` from `test/e2e/utils/test_context.go`:\n\n```go\nctx := utils.NewTestContext(util.KubebuilderBinName, \"GO111MODULE=on\")\nctx.Init(\"--domain\", \"example.com\", \"--repo\", \"example.com/project\")\nctx.CreateAPI(\"--group\", \"crew\", \"--version\", \"v1\", \"--kind\", \"Captain\")\nctx.Make(\"build\", \"test\")\nctx.LoadImageToKindCluster()\n```\n\n## CLI Reference\n\nAfter `make install`:\n\n```bash\nkubebuilder init --domain example.com --repo github.com/example/myproject\nkubebuilder create api --group batch --version v1 --kind CronJob\nkubebuilder create webhook --group batch --version v1 --kind CronJob\nkubebuilder edit --plugins=helm/v2-alpha\nkubebuilder alpha generate    # Experimental: generate from PROJECT file\nkubebuilder alpha update      # Experimental: update to latest plugin versions\n```\n\n## Common Patterns\n\n### Code Style\n- Avoid abbreviations: `context` not `ctx` (except receivers)\n- Descriptive names: `projectConfig` not `pc`\n- Single/double-letter receivers OK: `(c CLI)` or `(p Plugin)`\n\n### Logging Conventions\n\nKubebuilder has two distinct types of code with different logging conventions:\n\n**1. Kubebuilder CLI Tool Code** → Go CLI best practices\n\nApplies to: `pkg/cli/*`, `pkg/plugins/*`, `pkg/machinery/*`, `pkg/config/*`, `pkg/model/*`, etc.\n\nThis is the Kubebuilder tool itself. Follow Go logging conventions for CLI tools:\n- **First word lowercase**, sentences after periods capitalized: `\"unable to find file. This file is required for...\"`\n- **No ending punctuation** (but use periods between sentences)\n- **Error strings lowercase**: `fmt.Errorf(\"something bad\")`\n\n```go\nlog.Info(\"writing scaffold for you to edit\")\nlog.Warn(\"unable to find boilerplate file. This file is used to generate the license header\")\nlog.Error(\"failed to read file\", \"file\", path)\nreturn fmt.Errorf(\"failed to load config: %w\", err)\n```\n\n**2. Generated Code (Template Output)** → Kubernetes conventions\n\nApplies to: Code GENERATED by templates in `pkg/plugins/*/scaffolds/internal/templates/*`\n\nTemplates produce controller code that runs in Kubernetes clusters. The GENERATED code follows Kubernetes conventions:\n- **Start with capital letter**: `\"Starting reconciliation\"`\n- **No ending period** (but use periods between sentences)\n- **Past tense**: `\"Failed to create Pod\"` not `\"Cannot create Pod\"`\n- **Active voice**: specify subject or omit when it's the program itself\n- **Specify object type**: `\"Created Deployment\"` not `\"Created\"`\n\n```go\n// In template files that generate controller code:\nlog.Info(\"Starting reconciliation\")\nlog.Info(\"Created Deployment\", \"name\", deploy.Name)\nlog.Error(err, \"Failed to create Pod\", \"name\", name)\n```\n\n**Note:** The distinction is based on WHERE the code runs:\n- CLI tool (runs on developer's machine) → Go conventions\n- Generated controllers (run in Kubernetes cluster) → Kubernetes conventions\n\n### Testing Philosophy\n- Test behaviors, not implementations\n- Use real components over mocks\n- Test cases as specifications (Ginkgo: `Describe`, `It`, `Context`, `By`)\n- Use **Ginkgo v2** + **Gomega** for BDD-style tests.\n- Tests depending on the Kubebuilder binary should use: `utils.NewTestContext(util.KubebuilderBinName, \"GO111MODULE=on\")`\n\n### Test Organization\n\n- **Unit tests** (`*_test.go` in `pkg/`) - Test individual packages in isolation, fast\n- **Integration tests** (`*_integration_test.go` in `pkg/`) - Test multiple components together without cluster\n  - Must have `//go:build integration` tag at the top\n  - May create temp dirs, download binaries, or scaffold files\n  - Examples: alpha update, grafana scaffolding, helm chart generation\n- **E2E tests** (`test/e2e/`) - **ONLY** for tests requiring a Kubernetes cluster (KIND)\n  - `v4/plugin_cluster_test.go` - Test v4 plugin deployment\n  - `helm/plugin_cluster_test.go` - Test Helm chart deployment\n  - `deployimage/plugin_cluster_test.go` - Test deploy-image plugin\n\n### Scaffolding\n- Use library helpers from `pkg/plugin/util/`\n- Use markers for extensibility\n- Follow existing template patterns in `pkg/machinery`\n\n## Search Tips\n\n```bash\nrg \"\\\\+kubebuilder:scaffold\" --type go  # Find markers\nrg \"type.*Plugin struct\" pkg/plugins/   # Plugin implementations\nrg \"PluginBundle\" pkg/cli/              # Plugin registration\nrg \"func.*SetTemplateDefaults\"          # Template definitions\nrg \"func new.*Command\" pkg/cli/         # CLI commands\nrg \"NewTestContext\" test/e2e/           # E2E test setup\n```\n\n## Design Philosophy\n\n- **Libraries over code generation** - Use libraries when possible; generated code is hard to maintain\n- **Common cases easy, uncommon cases possible** - 80-90% use cases should be simple\n- **Batteries included** - Projects should be deployable/testable out-of-box\n- **No copy-paste** - Refactor into libraries or remote Kustomize bases\n\n## References\n\n### Essential Files\n- **`Makefile`** - All automation targets (source of truth for build/test commands)\n- **`CONTRIBUTING.md`** - CLA, pre-submit checklist, PR requirements\n- **`VERSIONING.md`** - Release workflow, versioning policy, PR tagging\n- **`go.mod`** - Go version and dependencies\n\n### Key Directories\n- **`pkg/`** - Core Kubebuilder code (CLI, plugins, machinery)\n- **`test/e2e/`** - End-to-end tests with Kubernetes cluster\n- **`testdata/`** - Generated sample projects (regenerated automatically)\n- **`docs/book/`** - User documentation source (https://book.kubebuilder.io)\n\n### Important Code Files\n- **`pkg/cli/init.go`** - Default plugin bundle definition\n- **`pkg/plugin/interface.go`** - Plugin interface definitions\n- **`pkg/machinery/scaffold.go`** - Scaffolding engine\n- **`test/e2e/utils/test_context.go`** - E2E test helpers\n- **`cmd/version.go`** - Version info (includes K8S version)\n\n### Scripts\n- **`test/testdata/generate.sh`** - Regenerate all testdata projects\n- **`hack/docs/generate.sh`** - Regenerate documentation samples\n- **`test/e2e/local.sh`** - Run e2e tests locally with Kind\n\n### External Resources\n- **Kubebuilder Book**: https://book.kubebuilder.io\n- **Kubebuilder Repo**: https://github.com/kubernetes-sigs/kubebuilder\n- **controller-runtime**: https://github.com/kubernetes-sigs/controller-runtime\n- **controller-tools**: https://github.com/kubernetes-sigs/controller-tools\n- **API Conventions**: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md\n- **Operator Pattern**: https://kubernetes.io/docs/concepts/extend-kubernetes/operator/\n- **Kubernetes Logging Conventions:** https://github.com/kubernetes/community/blob/master/contributors/devel/sig-instrumentation/logging.md#message-style-guidelines\n- **Structured Logging Guidelines:** https://github.com/kubernetes/community/blob/master/contributors/devel/sig-instrumentation/migration-to-structured-logging.md\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# Kubebuilder AI Agent Guide\n\n**Kubebuilder** is a **framework** and **command-line interface (CLI)** for building **Kubernetes APIs** using **Custom Resource Definitions (CRDs)**.\nIt provides scaffolding and abstractions that accelerate the development of **controllers**, **webhooks**, and **APIs** written in **Go**.\n\n## Quick Reference\n\n| Item       | Value                                                     |\n|------------|-----------------------------------------------------------|\n| Language   | Defined in the go.mod                                     |\n| Module     | `sigs.k8s.io/kubebuilder/v4`                              |\n| Binary     | `./bin/kubebuilder`                                       |\n| Core deps  | `controller-runtime`, `controller-tools`, Helm, Kustomize |\n| Docs       | https://book.kubebuilder.io                               |\n\n\n## Directory Map\n\n```\npkg/\n  cli/              CLI command implementations\n    alpha/          Alpha/experimental commands (generate, update, etc.)\n    init.go         'init' command + default PluginBundle definition\n    api.go          'create api' command\n    webhook.go      'create webhook' command\n    edit.go         'edit' command\n    root.go         Root command setup\n  machinery/        Scaffolding engine (templates, markers, injectors)\n    template.go     Base template interface\n    inserter.go     Code injection engine\n    marker.go       Marker detection and processing\n    filesystem.go   Filesystem abstraction (uses afero)\n  model/\n    resource/       Resource model (GVK, API, Controller, Webhook)\n    stage/          Plugin execution stages\n  plugin/           Plugin interfaces and utilities\n    interface.go    Core plugin interfaces (Plugin, Init, CreateAPI, etc.)\n    bundle.go       Plugin composition\n    util/           Helper functions for plugin authors\n  plugins/          Plugin implementations (ADD NEW PLUGINS HERE)\n    golang/v4/      Main Go scaffolding (default for go projects)\n      scaffolds/    Scaffolding for init, api, webhook\n        internal/templates/  Template implementations\n    golang/deployimage/  Deploy-image pattern plugin\n    common/kustomize/v2/  Kustomize manifest generation (default)\n    optional/       Optional plugins (enabled via --plugins flag)\n      helm/         Helm chart generation (v1alpha deprecated, v2alpha current)\n      grafana/      Grafana dashboard generation\n      autoupdate/   Auto-update GitHub workflow\n    external/       External plugin support (exec-based plugins)\ndocs/book/          mdBook documentation (https://book.kubebuilder.io)\n  src/              Markdown source files\n    **/testdata/    Sample projects used in docs (regenerated)\ntest/\n  e2e/              E2E tests requiring Kubernetes cluster\n    v4/             Tests for v4 plugin\n    helm/           Tests for Helm plugin\n    deployimage/    Tests for deploy-image plugin\n    utils/          Test helpers (TestContext, etc.)\n  testdata/         Scripts to generate testdata projects\n    generate.sh     Main generation script\n    test.sh         Tests all testdata projects\ntestdata/           Generated complete sample projects (DO NOT EDIT)\n  project-v4/                    Basic v4 project\n  project-v4-multigroup/         Multigroup project\n  project-v4-with-plugins/       Project with optional plugins\nhack/docs/          Documentation generation\n  generate.sh       Regenerate docs samples + marker docs\n  generate_samples.go  Sample generation logic\ncmd/                CLI entry point\n  version.go        Version info (updated by make update-k8s-version)\nmain.go             Application entry point\n```\n\n**Key Locations for Common Tasks:**\n- Add new plugin → `pkg/plugins/<category>/<name>/`\n- Add new template → `pkg/plugins/<plugin>/scaffolds/internal/templates/`\n- Modify CLI commands → `pkg/cli/`\n- Add scaffolding machinery → `pkg/machinery/`\n- Add tests → `test/e2e/all/plugin_<name>_test.go` or `pkg/<package>/*_test.go`\n\n## Critical Rules\n\n### Do Not Manually Edit Generated Files\n- `testdata/` - regenerated via `make generate-testdata`\n- `docs/book/**/testdata/` - regenerated via `make generate-docs`\n- `*/dist/chart/` - regenerated via `make generate-charts`\n\n### File-Specific Requirements\n\nAfter making changes, run the appropriate commands based on what you modified:\n\n**Generate Commands (rebuild artifacts):**\n- **If you modify files in `hack/docs/internal/`** → run `make install && make generate-docs`\n- **If you modify files in `pkg/plugins/optional/helm/`** → run `make install && make generate-charts`\n- **If you modify any boilerplate/template files** → run `make install && make generate`\n\n**Formatting Commands:**\n- After editing `*.go` → `make lint-fix`\n- After editing `*.md` → `make remove-spaces`\n\n**Always Run Before PR:**\n```bash\nmake lint-fix    # Auto-fix Go code style\nmake test-unit   # Verify unit tests pass\n```\n\n**Note:** Boilerplate/template files are Go files that define scaffolding templates, typically located in `pkg/plugins/**/scaffolds/internal/templates/` or files that generate code/configs for scaffolded projects.\n\n## Development Workflow\n\n### Build & Install\n```bash\nmake build    # Build to ./bin/kubebuilder\nmake install  # Copy to $(go env GOBIN)\n```\n\n### Lint & Format\n```bash\nmake lint       # Check only (golangci-lint + yamllint)\nmake lint-fix   # Auto-fix Go code\n```\n\n### Testing\n```bash\nmake test-unit         # Fast unit tests (./pkg/..., ./test/e2e/utils/...)\nmake test-integration  # Integration tests (may create temp dirs, download binaries)\nmake test-testdata     # Test all testdata projects\nmake test-e2e-local    # Full e2e (creates kind cluster)\nmake test              # CI aggregate (all of above + license)\n```\n\n## PR Submission\n\n### PR Title Format (MANDATORY)\n\nPR titles use **emojis** (appear in release notes).\n\nFormat: `:emoji: [(plugin/version)]: Description`\n\nThe `(plugin/version)` scope is optional; omit it for repo-wide or documentation-only changes.\n\n**Emojis:**\n- ⚠️ (`:warning:`) - Breaking change\n- ✨ (`:sparkles:`) - New feature\n- 🐛 (`:bug:`) - Bug fix\n- 📖 (`:book:`) - Documentation\n- 🌱 (`:seedling:`) - Infrastructure/tests/refactor\n\n**Examples:**\n```\n🐛 Resolve nil pointer panic in scaffold generator\n✨ (helm/v2-alpha): Add cluster-scoped resource support\n📖 (go/v4): Update deployment documentation\n✨ Update dependencies to latest versions\n```\n\n### Commit Message Format\n\nCommit messages follow the [Conventional Commits](https://www.conventionalcommits.org/) standard.\n\nFormat: `<type>[optional scope]: <description>`\n\nThe `[optional scope]` is typically the plugin/version (e.g., `helm/v2-alpha`, `go/v4`); omit it for repo-wide or non-plugin changes.\n\n**Types:**\n\n- **feat**: A new feature for the user or a plugin\n- **fix**: A bug fix for the user or a plugin\n- **docs**: Documentation changes only\n- **test**: Adding or updating tests\n- **refactor**: Code change that neither fixes a bug nor adds a feature\n- **chore**: Changes to build process, dependencies, or maintenance tasks\n- **breaking**: A breaking change (can be combined with other types)\n\n**Examples:**\n```\nfix: Resolve nil pointer panic in scaffold generator\nfeat(helm/v2-alpha): Add cluster-scoped resource support\ndocs(go/v4): Update deployment documentation\nchore: Update dependencies to latest versions\n```\n\n### Pre-PR Checklist\n- [ ] One commit per PR (squash all)\n- [ ] Add/update tests for new behavior\n- [ ] Add/update docs for new behavior\n- [ ] Run `make lint-fix`\n- [ ] Run `make install`\n- [ ] Run `make generate`\n- [ ] Run `make test-unit`\n\n## Core Concepts\n\n### Plugin Architecture\n\nPlugins implement interfaces from `pkg/plugin/`:\n- `Plugin` - base interface (Name, Version, SupportedProjectVersions)\n- `Init` - project initialization (`kubebuilder init`)\n- `CreateAPI` - API creation (`kubebuilder create api`)\n- `CreateWebhook` - webhook creation (`kubebuilder create webhook`)\n- `Edit` - post-init modifications (`kubebuilder edit`)\n- `Bundle` - groups multiple plugins\n\n**Plugin Bundles:**\n\nDefault bundle (`pkg/cli/init.go`): `go.kubebuilder.io/v4` + `kustomize.common.kubebuilder.io/v2`\n\nPlugins resolve via `pkg/plugin` registry and execute in order.\n\n**External Plugins:**\n\nExecutable binaries in `pkg/plugins/external/` that communicate via JSON over stdin/stdout.\n\n### Scaffolding Machinery\n\nFrom `pkg/machinery/`:\n- `Template` - file generation via Go templates\n- `Inserter` - code injection at markers\n- `Marker` - special comments (e.g., `// +kubebuilder:scaffold:imports`)\n- `Filesystem` - abstraction over afero for testability\n\n### Scaffolded Project Structure\n\nProjects generated by the Kubebuilder CLI use the default plugin bundle (`go/v4` + `kustomize/v2`). Each plugin scaffolds different files:\n\n**`go/v4` plugin scaffolds Go code:**\n- `cmd/main.go` - Entry point (manager setup)\n- `api/v1/*_types.go` - API definitions with `+kubebuilder` markers (via `create api`)\n- `internal/controller/*_controller.go` - Reconcile logic (via `create api`)\n- `Dockerfile`, `Makefile` - Build and deployment automation\n\n**`kustomize/v2` plugin scaffolds manifests:**\n- `config/` - Kustomize base manifests (CRDs, RBAC, manager, webhooks)\n- `config/crd/` - Custom Resource Definitions (via `create api`)\n- `config/samples/` - Example CR manifests (via `create api`)\n\n**`PROJECT` file:**\n- Project configuration tracking plugins, resources, domain, and layout\n\n**Note:** These are files in projects generated BY Kubebuilder, not the Kubebuilder source code itself.\n\n### Reconciliation Pattern\n\nControllers implement `Reconcile(ctx, req) (ctrl.Result, error)`:\n\n- **Idempotent** - Safe to run multiple times\n- **Level-triggered** - React to current state, not events\n- **Requeue on pending work** - Return `ctrl.Result{Requeue: true}`\n\n### Testing Pattern\nE2E tests use `utils.TestContext` from `test/e2e/utils/test_context.go`:\n\n```go\nctx := utils.NewTestContext(util.KubebuilderBinName, \"GO111MODULE=on\")\nctx.Init(\"--domain\", \"example.com\", \"--repo\", \"example.com/project\")\nctx.CreateAPI(\"--group\", \"crew\", \"--version\", \"v1\", \"--kind\", \"Captain\")\nctx.Make(\"build\", \"test\")\nctx.LoadImageToKindCluster()\n```\n\n## CLI Reference\n\nAfter `make install`:\n\n```bash\nkubebuilder init --domain example.com --repo github.com/example/myproject\nkubebuilder create api --group batch --version v1 --kind CronJob\nkubebuilder create webhook --group batch --version v1 --kind CronJob\nkubebuilder edit --plugins=helm/v2-alpha\nkubebuilder alpha generate    # Experimental: generate from PROJECT file\nkubebuilder alpha update      # Experimental: update to latest plugin versions\n```\n\n## Common Patterns\n\n### Code Style\n- Avoid abbreviations: `context` not `ctx` (except receivers)\n- Descriptive names: `projectConfig` not `pc`\n- Single/double-letter receivers OK: `(c CLI)` or `(p Plugin)`\n\n### Logging Conventions\n\nKubebuilder has two distinct types of code with different logging conventions:\n\n**1. Kubebuilder CLI Tool Code** → Go CLI best practices\n\nApplies to: `pkg/cli/*`, `pkg/plugins/*`, `pkg/machinery/*`, `pkg/config/*`, `pkg/model/*`, etc.\n\nThis is the Kubebuilder tool itself. Follow Go logging conventions for CLI tools:\n- **First word lowercase**, sentences after periods capitalized: `\"unable to find file. This file is required for...\"`\n- **No ending punctuation** (but use periods between sentences)\n- **Error strings lowercase**: `fmt.Errorf(\"something bad\")`\n\n```go\nlog.Info(\"writing scaffold for you to edit\")\nlog.Warn(\"unable to find boilerplate file. This file is used to generate the license header\")\nlog.Error(\"failed to read file\", \"file\", path)\nreturn fmt.Errorf(\"failed to load config: %w\", err)\n```\n\n**2. Generated Code (Template Output)** → Kubernetes conventions\n\nApplies to: Code GENERATED by templates in `pkg/plugins/*/scaffolds/internal/templates/*`\n\nTemplates produce controller code that runs in Kubernetes clusters. The GENERATED code follows Kubernetes conventions:\n- **Start with capital letter**: `\"Starting reconciliation\"`\n- **No ending period** (but use periods between sentences)\n- **Past tense**: `\"Failed to create Pod\"` not `\"Cannot create Pod\"`\n- **Active voice**: specify subject or omit when it's the program itself\n- **Specify object type**: `\"Created Deployment\"` not `\"Created\"`\n\n```go\n// In template files that generate controller code:\nlog.Info(\"Starting reconciliation\")\nlog.Info(\"Created Deployment\", \"name\", deploy.Name)\nlog.Error(err, \"Failed to create Pod\", \"name\", name)\n```\n\n**Note:** The distinction is based on WHERE the code runs:\n- CLI tool (runs on developer's machine) → Go conventions\n- Generated controllers (run in Kubernetes cluster) → Kubernetes conventions\n\n### Testing Philosophy\n- Test behaviors, not implementations\n- Use real components over mocks\n- Test cases as specifications (Ginkgo: `Describe`, `It`, `Context`, `By`)\n- Use **Ginkgo v2** + **Gomega** for BDD-style tests.\n- Tests depending on the Kubebuilder binary should use: `utils.NewTestContext(util.KubebuilderBinName, \"GO111MODULE=on\")`\n\n### Test Organization\n\n- **Unit tests** (`*_test.go` in `pkg/`) - Test individual packages in isolation, fast\n- **Integration tests** (`*_integration_test.go` in `pkg/`) - Test multiple components together without cluster\n  - Must have `//go:build integration` tag at the top\n  - May create temp dirs, download binaries, or scaffold files\n  - Examples: alpha update, grafana scaffolding, helm chart generation\n- **E2E tests** (`test/e2e/`) - **ONLY** for tests requiring a Kubernetes cluster (KIND)\n  - `v4/plugin_cluster_test.go` - Test v4 plugin deployment\n  - `helm/plugin_cluster_test.go` - Test Helm chart deployment\n  - `deployimage/plugin_cluster_test.go` - Test deploy-image plugin\n\n### Scaffolding\n- Use library helpers from `pkg/plugin/util/`\n- Use markers for extensibility\n- Follow existing template patterns in `pkg/machinery`\n\n## Search Tips\n\n```bash\nrg \"\\\\+kubebuilder:scaffold\" --type go  # Find markers\nrg \"type.*Plugin struct\" pkg/plugins/   # Plugin implementations\nrg \"PluginBundle\" pkg/cli/              # Plugin registration\nrg \"func.*SetTemplateDefaults\"          # Template definitions\nrg \"func new.*Command\" pkg/cli/         # CLI commands\nrg \"NewTestContext\" test/e2e/           # E2E test setup\n```\n\n## Design Philosophy\n\n- **Libraries over code generation** - Use libraries when possible; generated code is hard to maintain\n- **Common cases easy, uncommon cases possible** - 80-90% use cases should be simple\n- **Batteries included** - Projects should be deployable/testable out-of-box\n- **No copy-paste** - Refactor into libraries or remote Kustomize bases\n\n## References\n\n### Essential Files\n- **`Makefile`** - All automation targets (source of truth for build/test commands)\n- **`CONTRIBUTING.md`** - CLA, pre-submit checklist, PR requirements\n- **`VERSIONING.md`** - Release workflow, versioning policy, PR tagging\n- **`go.mod`** - Go version and dependencies\n\n### Key Directories\n- **`pkg/`** - Core Kubebuilder code (CLI, plugins, machinery)\n- **`test/e2e/`** - End-to-end tests with Kubernetes cluster\n- **`testdata/`** - Generated sample projects (regenerated automatically)\n- **`docs/book/`** - User documentation source (https://book.kubebuilder.io)\n\n### Important Code Files\n- **`pkg/cli/init.go`** - Default plugin bundle definition\n- **`pkg/plugin/interface.go`** - Plugin interface definitions\n- **`pkg/machinery/scaffold.go`** - Scaffolding engine\n- **`test/e2e/utils/test_context.go`** - E2E test helpers\n- **`cmd/version.go`** - Version info (includes K8S version)\n\n### Scripts\n- **`test/testdata/generate.sh`** - Regenerate all testdata projects\n- **`hack/docs/generate.sh`** - Regenerate documentation samples\n- **`test/e2e/local.sh`** - Run e2e tests locally with Kind\n\n### External Resources\n- **Kubebuilder Book**: https://book.kubebuilder.io\n- **Kubebuilder Repo**: https://github.com/kubernetes-sigs/kubebuilder\n- **controller-runtime**: https://github.com/kubernetes-sigs/controller-runtime\n- **controller-tools**: https://github.com/kubernetes-sigs/controller-tools\n- **API Conventions**: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md\n- **Operator Pattern**: https://kubernetes.io/docs/concepts/extend-kubernetes/operator/\n- **Kubernetes Logging Conventions:** https://github.com/kubernetes/community/blob/master/contributors/devel/sig-instrumentation/logging.md#message-style-guidelines\n- **Structured Logging Guidelines:** https://github.com/kubernetes/community/blob/master/contributors/devel/sig-instrumentation/migration-to-structured-logging.md\n","category":"root","tokens":4135}]}