Operator SDK

Operator SDK Overview

Operator SDK provides tools for building Kubernetes operators. Kubebuilder scaffolds the project structure, controller-runtime provides the framework, and envtest enables integration testing. Together they eliminate boilerplate and enforce patterns.

# Initialize a new project
operator-sdk init \
  --domain=example.com \
  --repo=github.com/my-org/my-operator

# Create a new API (CRD + controller)
operator-sdk create api \
  --group=app \
  --version=v1 \
  --kind=WebApp \
  --resource=true \
  --controller=true

# Generate CRD manifests
make generate
make manifests

Kubebuilder Scaffolding

Kubebuilder scaffolds the project with standard patterns: api/ for CRD types, internal/controller/ for controllers, config/ for Kubernetes manifests, and hack/ for build scripts. Follow these conventions for maintainable operators.

my-operator/
  api/
    v1/
      webapp_types.go     # CRD type definitions
      groupversion_info.go # API group registration
  internal/
    controller/
      webapp_controller.go # Reconciler logic
  config/
    crd/bases/           # Generated CRD YAML
    rbac/                # Generated RBAC rules
    manager/             # Manager deployment
    samples/             # Sample CRs
  hack/
    boilerplate.go.txt   # License header
  Dockerfile
  Makefile
  PROJECT               # Kubebuilder metadata

Controller-Runtime

Controller-runtime is the framework for building controllers. It provides: Manager (handles lifecycle), Reconciler (business logic), Informers (watch resources), and Client (CRUD operations). It's the foundation of Kubebuilder operators.

envtest Testing

envtest provides a real API server and etcd for testing controllers. It creates a temporary cluster, installs CRDs, and runs tests. This catches issues that unit tests miss.

RBAC Markers

RBAC markers generate ClusterRole rules from comments. Add markers to the Reconciler and make manifests generates the RBAC YAML. This keeps RBAC in sync with actual controller needs.

Generated Manifests

# Generate deepcopy methods
make generate

# Generate CRD and RBAC manifests
make manifests

# Build and push the operator image
make docker-build docker-push IMG=ghcr.io/my-org/my-operator:v1

# Deploy to cluster
make deploy IMG=ghcr.io/my-org/my-operator:v1

# Undeploy
make undeploy