Skip to main content
When building a Kubernetes operator you’ll typically choose between two main toolchains: Kubebuilder and the Operator SDK. They look and behave similarly because both are built on the same Go library: controller-runtime. Both tools share the same foundation and runtime behavior, so understanding what they have in common makes the decision straightforward.
The image illustrates two tools, KubeBuilder and Operator SDK, using a shared Go engine called controller-runtime, maintained by Kubernetes SIG API Machinery.

​
Shared foundation: controller-runtime

controller-runtime provides the core building blocks used by both Kubebuilder and the Operator SDK:
  • Manager: runs your operator process, sets up shared caches, and starts controllers.
  • Client: typed/untyped client used to read and write Kubernetes API objects.
  • Reconciler: where your reconciliation logic (the control loop) lives.
  • Webhook server: handles admission webhooks for validation and mutation.
At runtime, an operator generated by either project calls the same controller-runtime APIs and behaves the same way.
The image shows a diagram of core building blocks with labeled boxes for "Manager," "Client," "Reconciler," and "Webhook server," each describing a specific function.
Think of controller-runtime as a shared workbench. Kubebuilder gives you a clean bench with core tools and minimal scaffolding. Operator SDK starts from the same bench but adds extra drawers and adapters for Helm, Ansible, and OperatorHub/OLM packaging. The distinction boils down to what each tool wraps around controller-runtime.
The image compares "Kubebuilder" and "Operator SDK," highlighting that Operator SDK includes additional tools like Helm, Ansible, and OperatorHub packaging.

​
Kubebuilder: minimal, upstream, SIG-owned

Kubebuilder is the upstream project maintained by the Kubernetes SIG that also owns controller-runtime. It intentionally keeps the CLI and scaffolding minimal:
  • A Go module and go.mod.
  • A PROJECT file.
  • api/ for CRD type definitions.
  • controllers/ (or internal/controller/) for reconcilers.
  • A Makefile and Dockerfile.
This minimal structure maps directly to controller-runtime concepts and keeps distractions to a minimum.
The image describes the "Intentionally Minimal" structure of Kubebuilder, highlighting key components such as "go.mod," "PROJECT," "api/," and "internal/controller/," and notes that it is upstream and owned by the same SIG.

​
Operator SDK: a superset for multiple workflows

Maintained by Red Hat, the Operator SDK builds on top of Kubebuilder for Go projects (it uses Kubebuilder plugins under the hood) and adds first-class support for alternative operator implementations and distribution tooling:
  • Helm operator: wrap a Helm chart as an operator with minimal or no Go code.
  • Ansible operator: run Ansible roles/playbooks as operator logic.
  • OLM integration: tooling to produce bundles and ClusterServiceVersion metadata for Operator Lifecycle Manager (OLM) and OperatorHub.
The image outlines three features that the Operator SDK adds: Helm operator, Ansible operator, and OLM integration, each described with a brief note.
Operator SDK also provides Makefile targets to build OLM bundles and generate the ClusterServiceVersion (CSV) and other metadata required to publish an operator to OperatorHub. Example: build an OLM bundle for your operator:
OperatorHub and OLM expect these files to list, install, and manage your operator on clusters.

​
Which should you choose?

The right choice depends on your goals and distribution needs.
  • Use Kubebuilder if your objective is to learn controller patterns: CRDs, reconcilers, webhooks, and finalizers. Its minimal scaffold surfaces controller-runtime concepts directly and reduces complexity. This makes Kubebuilder ideal for learning or building custom Go-based operators from scratch.
The image is an informational slide for learning Kubebuilder, highlighting its features such as CRDs, Reconcilers, Webhooks, and Finalizers, with benefits like less complexity and fewer files.
  • Use Operator SDK in two common scenarios:
    1. You have an existing Helm chart and want to ship it as an operator with little or no Go code (Helm operator).
    2. You need OLM/OperatorHub bundle generation and metadata out-of-the-box — common for OpenShift or when publishing to OperatorHub.
The image outlines scenarios for using Operator SDK, specifically when utilizing Helm charts without Go, and its compatibility with OpenShift/OperatorHub.

​
Quick decision table

Skills and code transfer cleanly between the two: a reconciler written for Kubebuilder will generally drop into an Operator SDK project unchanged, because both target controller-runtime. Learn Kubebuilder first and you’ll already have covered most of what Operator SDK uses for Go-based operators.
The image illustrates the compatibility between Kubebuilder and Operator SDK, highlighting that 90% of the Operator SDK is already covered through unchanged skills transfer using controller-runtime.
If your goal is to understand the internals and controller patterns, start with Kubebuilder. If you need quick Helm/Ansible integration or automatic OLM bundle generation for distribution, choose Operator SDK.

Watch Video