Kubebuilder — SDK for Building Kubernetes APIs and Operators

Introduction

Kubebuilder is the official SIG-API-Machinery SDK for authoring Kubernetes operators in Go. It wraps controller-runtime, controller-gen and the Kubernetes libraries into an opinionated project layout so you can focus on reconciler logic instead of boilerplate client-gen, informer and RBAC wiring.

What Kubebuilder Does

• Scaffolds a full Go project with Makefile, Dockerfile and kustomize configs
• Generates CRD YAML, deepcopy methods, RBAC manifests and webhook scaffolding
• Provides a controller-runtime-based reconciler skeleton per Kind
• Bundles envtest for running controllers against a real apiserver locally
• Produces installable bundles (kustomize, Helm, OLM) for distribution

Architecture Overview

Kubebuilder leans on controller-runtime, which provides the Manager, client, cache and event-driven reconciliation loop. kubebuilder create api appends a Kind to api/v1/, registers it in the Scheme and wires a Reconciler. make generate invokes controller-gen to produce deepcopy functions; make manifests produces CRDs and RBAC. The compiled binary runs inside a cluster, watches resources via an informer cache, and reconciles desired vs. observed state.

Self-Hosting & Configuration

• PROJECT file tracks domain, repo and scaffolding version so upgrades are reproducible
• Use kubebuilder create webhook to add validating, mutating or conversion webhooks
• config/ kustomize bases let you layer overlays (dev, staging, prod)
• envtest binaries download Kubernetes control-plane components for offline integration tests
• Multi-group layouts support operators that own resources across multiple API groups

Key Features

• Code-gen and scaffolding in one command: kubebuilder create api
• First-class webhook, conversion and defaulting support
• Project layout follows SIG guidelines, accepted upstream
• Rich plugin system (go/v4, declarative, helm) for alternative scaffolds
• Compatible with Operator SDK, which layers extras on top of the same bases

Comparison with Similar Tools

• Operator SDK — supports Go, Ansible and Helm operators; Go mode is built on Kubebuilder
• kopf (Python) — great for quick scripts, but less idiomatic for distributed operators
• Metacontroller — lets you write controllers in any language via hooks, less type-safe
• Crossplane Providers — specialised for cloud APIs rather than generic CRDs
• controller-runtime alone — powerful library, but Kubebuilder provides the project harness

FAQ

Q: Do I have to write my operator in Go? A: Kubebuilder itself is Go-first. For Python or JavaScript operators, consider kopf or metacontroller.

Q: How do I upgrade an existing project? A: Bump the scaffold version in the PROJECT file, run kubebuilder alpha generate and reconcile the diff against your custom code.

Q: How do I test a controller without a cluster? A: Use envtest, which starts a local etcd and kube-apiserver so your reconciler talks to a real API surface during go test.

Q: Can I expose metrics? A: Yes — the manager exposes a Prometheus endpoint by default and includes leader-election and health probes out of the box.

Sources

• https://github.com/kubernetes-sigs/kubebuilder
• https://book.kubebuilder.io