> ## 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.
# Demo Kubebuilder Init
> Guide to initializing a Kubebuilder operator project, scaffolding a Go-based Kubernetes operator skeleton, and verifying build and tooling
Where do you actually start when building a Kubernetes operator?
Handwriting the Go module, Makefile, directory tree, and all the wiring that connects your controller to the Kubernetes API can be hours of boilerplate before a single line of real logic. Kubebuilder solves that problem by scaffolding a complete operator project so you can skip straight to the interesting parts.
In this guide you'll initialize a new Kubebuilder project and verify the generated skeleton builds. By the end you will have:
* A buildable Go module
* A working `Makefile`
* The controller-runtime manager entry point
This is a practical first step toward creating APIs, controllers, and webhooks with Kubebuilder.
## Prerequisites
* Go installed and available on your `PATH`. If `go version` fails, install Go from the official Go installation page: [https://go.dev/doc/install](https://go.dev/doc/install)
Check Go:
```bash theme={null}
$ go version
go version go1.26.3 linux/amd64
```
## Install Kubebuilder
Kubebuilder is not installed by default. Follow the Kubebuilder quick-start installation instructions:
* Official docs: [https://book.kubebuilder.io/quick-start.html](https://book.kubebuilder.io/quick-start.html)
Example install (fetches the latest binary compatible with your OS):
```bash theme={null}
$ curl -L -o kubebuilder "https://go.kubebuilder.io/dl/latest/$(go env GOOS)"
# make it executable and move into a directory on PATH, for example:
$ chmod +x kubebuilder
$ sudo mv kubebuilder /usr/local/bin/
$ kubebuilder version
```
Make sure `kubebuilder` is executable and located in a directory that is on your `PATH` (for example `/usr/local/bin`).
Kubebuilder will not scaffold into a directory that already contains files. Always run `kubebuilder init` from an empty project folder (check your editor or run `ls -la` first). If the folder contains files, create a clean directory before continuing.
## Verify toolchain
Confirm both Kubebuilder and Go are installed and reporting compatible versions. If versions differ significantly, the project layout and generated imports may vary.
```bash theme={null}
$ kubebuilder version && go version
KubeBuilder: v4.14.0
Kubernetes: 1.35.0
Git Commit: 505d63f3b272472b5556ff650f03ba64d885cf3a
Build Date: 2026-04-29T07:19:23Z
Go OS/Arch: linux/amd64
go version go1.26.3 linux/amd64
```
## Initialize the project
`kubebuilder init` scaffolds a new operator project. The most important flags:
| Flag | Purpose | Example |
| ---------------- | ------------------------------------------------ | --------------------------------------------- |
| `--domain` | API group suffix (used in CRD API groups) | `--domain kodekloud.com` |
| `--repo` | Go module path (becomes `module` in `go.mod`) | `--repo github.com/kodekloud/webapp-operator` |
| `--project-name` | Project name saved in Kubebuilder `PROJECT` file | `--project-name webapp-operator` |
Pick these values carefully: `domain` and `repo` are embedded into package import paths and generated manifests.
Example init command:
```bash theme={null}
$ kubebuilder init --domain kodekloud.com --repo github.com/kodekloud/webapp-operator --project-name webapp-operator
```
Typical scaffold output:
```text theme={null}
INFO Writing kustomize manifests
INFO Writing scaffold for you to follow
INFO Get controller runtime
INFO Update dependencies
Next: define a resource with:
$ kubebuilder create api
```
## What Kubebuilder creates
After `kubebuilder init` completes, you'll see a small project layout with source, build, and configuration files. Key files and directories:
| Path | Purpose |
| --------------------------- | ----------------------------------------------------------------------------- |
| `cmd/main.go` | Manager entry point — starts the controller-runtime manager. |
| `config/` | Kustomize manifests for deploying the manager, CRDs, RBAC, and webhooks. |
| `Dockerfile` and `Makefile` | Build, test, and packaging targets (e.g., `make build`, `make docker-build`). |
| `PROJECT` | Kubebuilder metadata that tracks CLI options and layout choices. |
A sample `PROJECT` file:
```yaml theme={null}
cliVersion: 4.14.0
domain: kodekloud.com
layout:
- go.kubebuilder.io/v4
projectName: webapp-operator
repo: github.com/kodekloud/webapp-operator
version: "3"
```
## Build the scaffold
The scaffold is intended to compile immediately. If `make build` succeeds, your Go toolchain and module path are configured correctly.
Scaffold and build:
```bash theme={null}
$ kubebuilder create api
$ make build
mkdir -p "/home/student/work/labs/bin"
Downloading sigs.k8s.io/controller-tools/cmd/controller-gen@v0.20.1
"/home/student/work/labs/bin/controller-gen"
rbac:roleName=manager-role crd webhook paths="./..." output:crd:artifacts:config=config/crd/bases
"/home/student/work/labs/bin/controller-gen" object:headerFile="hack/boilerplate.go.txt",year=2026 paths="./..."
```
If the build completes successfully, the manager binary compiles and you’re ready to scaffold APIs, controllers, and webhooks.
## Next steps
Now that the skeleton is in place and the manager compiles, continue with:
* A tour of the directories and files Kubebuilder `init` created (`cmd/`, `config/`, `api/`, `controllers/`)
* Using `kubebuilder create api` to define your first CustomResource and controller
* Implementing reconcile logic in the generated controller
References and further reading:
* Kubebuilder Quick Start: [https://book.kubebuilder.io/quick-start.html](https://book.kubebuilder.io/quick-start.html)
* Kubernetes documentation: [https://kubernetes.io/docs/](https://kubernetes.io/docs/)
* Go installation: [https://go.dev/doc/install](https://go.dev/doc/install)