Master Kubernetes Operators with Kubebuilder: Build a SidecarSet from Scratch

Overview

The article explains how to extend the Kubernetes API using the Operator development framework, focusing on a practical case that builds a SidecarSet operator with Kubebuilder.

Basic Concepts

CRD (Custom Resource Definition): defines a new Kubernetes resource type.

CR (Custom Resource): an instance of a CRD.

Webhook: an HTTP callback registered with the apiserver, used for mutating or validating resources.

Work queue: core component of a controller that stores events such as Pod creation.

Controller: processes items from the work queue and drives the cluster toward the desired state.

Operator: combines CRD, optional webhook, and controller to implement custom business logic (Operator = CRD + webhook + controller).

Common Operator Work Modes

Operators typically use mutating webhooks to set default values and validating webhooks to enforce constraints before persisting resources.

Operator Framework Overview

Two mainstream frameworks are highlighted: kubebuilder and operator-sdk . Both rely on controller‑tools and controller‑runtime; kubebuilder offers richer scaffolding, while operator‑sdk provides better support for Ansible operators.

Kubebuilder Hands‑On (SidecarSet Example)

Step 1: Initialize Run kubebuilder init --domain=kruise.io to create a GitLab project, fetch dependencies, and generate the basic scaffold (Makefile, Dockerfile, etc.).

Step 2: Create API Run kubebuilder create api --group apps --version v1alpha1 --kind SidecarSet --namespace=false . This generates the CRD definition and controller scaffold. Important flags: group : apps.kruise.io version : v1alpha1 (unstable), v1beta1 (stable), v1 (fully stable) kind : SidecarSet namespaced : false (cluster‑wide resource)

Step 3: Fill CRD Edit pkg/apis/apps/v1alpha1/sidecarset_types.go to add annotations ( genclient:nonNamespaced , kubebuilder:subresource:status , custom print columns) and define SidecarSetSpec (selector and containers) and SidecarSetStatus (matched, updated, ready pods).

Step 4: Generate Webhook Scaffold Run the following commands to create webhook handlers: Mutating SidecarSet: kubebuilder alpha webhook --group apps --version v1alpha1 --kind SidecarSet --type=mutating --operations=create Mutating Pod: kubebuilder alpha webhook --group core --version v1 --kind Pod --type=mutating --operations=create Validating SidecarSet: kubebuilder alpha webhook --group apps --version v1alpha1 --kind SidecarSet --type=validating --operations=create,update

Step 5: Implement Webhook Logic Fill the generated handler files ( pkg/webhook/default_server/sidecarset/mutating/…_handler.go , …/validating/…_handler.go , pkg/webhook/default_server/pod/mutating/…_handler.go ) with defaulting and validation code. For the mutating SidecarSet handler, set default values; for the validating handler, check required fields; for the Pod mutating handler, inject the sidecar containers based on the matching SidecarSet.

Step 6: Implement Controller Logic Edit pkg/controller/sidecarset/sidecarset_controller.go to: Adjust RBAC annotations. Add work‑queue logic for SidecarSet and related Pods. Implement the Reconcile function to select matching Pods, compute status, and update SidecarSetStatus .

SidecarSet Workflow

User creates a SidecarSet resource.

Mutating webhook sets defaults and validates the resource, then stores it.

User creates a Pod; the mutating Pod webhook retrieves the matching SidecarSet and injects the sidecar containers.

The controller continuously watches cluster state; when a SidecarSet is updated, it enqueues the resource, processes the work queue, and updates status fields such as MatchedPods, UpdatedPods, and ReadyPods.

Conclusion

Operators are built from CRDs, optional webhooks, and controllers to extend Kubernetes functionality. Kubebuilder provides a standardized, community‑backed framework that automates much of the boilerplate, allowing developers to focus on the business logic needed for custom resources like SidecarSet.