Demo Kubebuilder Init

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

Check Go:

$ 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

Example install (fetches the latest binary compatible with your OS):

$ 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.

$ 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:

$ kubebuilder init --domain kodekloud.com --repo github.com/kodekloud/webapp-operator --project-name webapp-operator

Typical scaffold output:

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:

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:

$ 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
Kubernetes documentation: https://kubernetes.io/docs/
Go installation: https://go.dev/doc/install

Watch Video

Kubebuilder Vs Operator SDK

Demo Project Structure Walkthrough

Introduction to Operator Fundamentals

Custom Resource Definitions Deep Dive

Kubebuilder Scaffolding

Building The WebApp Operator Core Reconcile

Running Testing Debugging Locally

Status Conditions Events

Finalizers And Cleanup

Validation Webhooks And CEL Policies

Packaging And Distribution

Alternative Approaches Operator SDK Helm Operator

Consuming Popular Operators

Production Readiness Testing Wrap Up

Demo Kubebuilder Init

Prerequisites

Install Kubebuilder

Verify toolchain

Initialize the project

What Kubebuilder creates

Build the scaffold

Next steps

Watch Video

​Prerequisites

​Install Kubebuilder

​Verify toolchain

​Initialize the project

​What Kubebuilder creates

​Build the scaffold

​Next steps

Watch Video

Prerequisites

Install Kubebuilder

Verify toolchain

Initialize the project

What Kubebuilder creates

Build the scaffold

Next steps