# Kubebuilder — SDK for Building Kubernetes APIs and Operators

> Kubebuilder is a framework for building Kubernetes APIs using Custom Resource Definitions. It scaffolds an idiomatic controller-runtime project, manages code generation, and gives you the tooling to publish a production-grade operator.

## Install

Save as a script file and run:

# Kubebuilder — SDK for Building Kubernetes APIs

## Quick Use
```bash
# Install kubebuilder
curl -L -o kubebuilder https://go.kubebuilder.io/dl/latest/$(go env GOOS)/$(go env GOARCH)
chmod +x kubebuilder && sudo mv kubebuilder /usr/local/bin/

# Bootstrap a new project
mkdir guestbook && cd guestbook
kubebuilder init --domain example.com --repo example.com/guestbook
kubebuilder create api --group webapp --version v1 --kind Guestbook

# Generate manifests and run the controller
make manifests generate
make install run
```

## 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

---
Source: https://tokrepo.com/en/workflows/95910ea9-38e6-11f1-9bc6-00163e2b0d79
Author: Script Depot