> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Section Overview
> Guide to using Kubebuilder to scaffold, generate, and manage a Go-based Kubernetes operator project including APIs, controllers, CRD and RBAC generation, and CLI commands.
By the end of this section you will have a working operator project on disk: scaffolded, compiled, and ready to grow into the WebApp operator we build throughout this course. The scaffold provides a clear layout for your Go module, CRD types, controller logic, manifests, and packaging.
```text theme={null}
text
operator-project/
├── Makefile
├── PROJECT
├── go.mod
├── api/v1/
│ └── webapp_types.go
├── controllers/
│ └── webapp_controller.go
└── config/
├── crd/
└── manager/
```
Kubebuilder provides a repeatable scaffolding workflow that organizes every artifact in a predictable place: project metadata, API types, controller code, generated manifests, a Dockerfile for packaging, and Makefile targets for common tasks. This section shows how to use Kubebuilder to create that scaffold so subsequent lessons can focus on operator logic instead of project plumbing.
Why use Kubebuilder? If you want to build a Kubernetes operator—software that watches custom resources and reconciles cluster state—you usually start with an empty directory and many structural decisions. Kubebuilder automates that: it bootstraps the manager, wires the controller to the manager, generates CRD manifests from Go types, and emits RBAC rules from annotations.
Kubebuilder is a generator and thin runtime layer built on top of controller-runtime, which is the library that actually watches resources, keeps caches, and runs reconciliation loops.
Quick reference — common scaffold files and their purpose:
| File / Directory | Purpose |
| ---------------- | ------------------------------------------------------------------- |
| `go.mod` | Go module identity for the operator project |
| `Makefile` | Repeatable build/test/manifest targets |
| `PROJECT` | Kubebuilder project metadata (scaffold history) |
| `api//` | Go structs (CRD types) live here, e.g. `api/v1/webapp_types.go` |
| `controllers/` | Reconciler implementations, e.g. `controllers/webapp_controller.go` |
| `config/` | Generated manifests (CRD, RBAC, manager, samples) |
| `Dockerfile` | Image build instructions for the operator container |
Starter controller code is already wired to the manager. Before adding your custom APIs and reconcile logic, it helps to compare Kubebuilder with the Operator SDK: both leverage controller-runtime but provide different developer experiences and tooling. For this course, Kubebuilder is the primary scaffold tool.
Getting started — CLI commands
1. Verify your toolchain and install Kubebuilder.
2. Initialize a new project and create an API for the WebApp kind.
Example shell session:
```bash theme={null}
$ mkdir webapp-operator && cd webapp-operator
$ ls
# empty. now what?
```
```bash theme={null}
$ kubebuilder version # verify CLI is installed
$ go version # verify Go toolchain
$ kubebuilder init --domain kodekloud.com --repo github.com/kodekloud/webapp-operator
$ kubebuilder create api --group apps --version v1 --kind WebApp
```
Ensure [`go`](https://go.dev) and [`kubebuilder`](https://book.kubebuilder.io) are in your PATH. The `--domain` you pass to `kubebuilder init` becomes the DNS domain for your CRD API group (for example: `apps.kodekloud.com/v1`).
After generation, inspect the code layout. Key files you will interact with:
* `api/v1/webapp_types.go` — the Go structs that define the WebApp spec and status.
* `controllers/webapp_controller.go` — the Reconciler that runs when WebApp resources change.
* `main.go` — wires the manager, controllers, and sets up leader election, metrics, etc.
* `Makefile` — contains common targets: `make` build, `make run`, `make docker-build`, `make install` (CRDs), `make deploy`.
The reconciler implements the Reconcile method: read desired state (the resource), compare with actual cluster state, and make changes to converge. The generated skeleton leaves an empty `Reconcile` where you add the operator logic.
controller-gen and markers
Kubebuilder uses controller-tools (`controller-gen`) to generate CRD manifests and RBAC rules from annotated comments (markers) in your Go types and controller code. Markers are straightforward and drive automation.
Example RBAC marker:
```go theme={null}
// +kubebuilder:rbac:groups=apps.kodekloud.com,resources=webapps,verbs=get;list;watch;create;update;patch;delete
```
These markers will be turned into RBAC YAML in `config/rbac/` and CRD YAML in `config/crd/bases/` after you run the generator targets (for example: `make generate` and `make manifests`, depending on your Makefile).
Always verify generated RBAC rules and CRD group/version names before applying to a cluster. Incorrect RBAC or API group names can prevent your controller from watching or acting on resources.
Multiple APIs in one repo
A single Kubebuilder project can hold multiple API groups, versions, and kinds. Use `kubebuilder create api` repeatedly to add new groups/versions/kinds; the scaffold keeps APIs and controllers organized under `api/` and `controllers/`, and `PROJECT` records your layout.
Wrap-up
After completing this section you will have:
* A compiling operator project.
* Generated CRD YAML to install into a cluster.
* An empty `Reconcile` method ready for your business logic.
* An understanding of how markers drive CRD and RBAC generation and where to add additional APIs.
Links and references
* [Kubebuilder Book](https://book.kubebuilder.io)
* [controller-runtime on GitHub](https://github.com/kubernetes-sigs/controller-runtime)
* [Operator SDK](https://sdk.operatorframework.io)
* [controller-tools / controller-gen](https://github.com/kubernetes-sigs/controller-tools)