Operator Component Framework

A Go framework for building Kubernetes operators that stay maintainable as they grow. It pulls reconciliation mechanics, status reporting, and lifecycle behavior into reusable building blocks (components and resource primitives), so your controllers stay thin and focused on construction and orchestration, without sacrificing customizability where it matters.

Note

This framework is not a replacement for controller-runtime. It is a library you use inside controller-runtime reconcilers, such as in Kubebuilder-generated projects, to manage the layers between the reconciler and the Kubernetes resources it manages.

Architecture

An operator built with this framework has two layers between the controller and raw Kubernetes objects:

graph TB
    subgraph controller [" "]
        R["⚪ Your Reconciler"]
    end

    subgraph components [" "]
        C1["🔵 Web Interface component"]
        C2["🔵 Monitoring component"]
    end

    subgraph primitives [" "]
        P1["🟢 ConfigMap"]
        P2["🟢 Deployment"]
        P3["🟢 Service"]
        P4["🟢 ServiceAccount"]
        P5["🟢 DaemonSet"]
    end

    subgraph cluster [" "]
        K["⚪ Kubernetes API"]
    end

    R --> C1 & C2
    C1 --> P1 & P2 & P3
    C2 --> P4 & P5
    P1 & P2 & P3 & P4 & P5 --> K

Loading

⚪ What you already have   🔵 OCF component layer   🟢 OCF primitive layer

A component composes resource primitives into one reconcilable unit with a single condition on the owner. The reconciler builds it and hands it to the framework, which applies the resources, aggregates their health, and writes the condition back.

comp, err := component.NewComponentBuilder().
    WithName("web-interface").
    WithConditionType("WebInterfaceReady").
    WithResource(configMap).
    WithResource(deployment).
    WithResource(service).
    WithGracePeriod(5 * time.Minute).
    Suspend(owner.Spec.Suspended).
    Build()
if err != nil {
    return err
}

return comp.Reconcile(ctx, recCtx)

Installation

go get github.com/sourcehawk/operator-component-framework

Requires Go 1.26+ and controller-runtime v0.22 or later. See compatibility for the tested version combinations.

Scaffolding

Wrapping a CRD the built-in primitives do not cover is mechanical. The ocf CLI generates the whole wrapper package, compiling and tested, from one command:

go install github.com/sourcehawk/operator-component-framework/cmd/ocf@latest

ocf scaffold wrapper \
  --type github.com/cert-manager/cert-manager/pkg/apis/certmanager/v1.Certificate \
  --variant integration \
  --group cert-manager.io

See the CLI guide for the full flag set and what to replace in the generated code.

Documentation

Full documentation, including a step-by-step tutorial, is at sourcehawk.github.io/operator-component-framework.

Guide	What it covers
Getting Started	Build your first component, end to end
Component	Lifecycle, status model, grace periods, suspension, guards
Primitives	Typed wrappers, the mutation system, editors, feature gating
Custom Resources	Wrap your own CRDs with pkg/generic
CLI	Scaffold wrapper packages with ocf scaffold wrapper
Guidelines	Patterns for structuring operators well
Testing	Golden snapshots and version-matrix coverage
Compatibility	Supported Kubernetes and controller-runtime versions

The full Go API reference is on pkg.go.dev.

Claude Code plugin

The repository ships a Claude Code plugin that teaches Claude the framework's concepts and idioms: skills for components, primitives, custom resource wrappers, operator structure, and testing, plus scaffolding commands and a guidelines reviewer.

Install it for yourself from this repository:

/plugin marketplace add sourcehawk/operator-component-framework
/plugin install ocf

To share it with everyone working on your operator, commit the marketplace and plugin to your repository's .claude/settings.json. Pin ref to the framework tag your go.mod requires, so the skills Claude reads describe the same API you compile against:

{
  "extraKnownMarketplaces": {
    "operator-component-framework": {
      "source": {
        "source": "github",
        "repo": "sourcehawk/operator-component-framework",
        "ref": "v0.18.0"
      }
    }
  },
  "enabledPlugins": {
    "ocf@operator-component-framework": true
  }
}

Collaborators are prompted to install the plugin the first time they trust the project folder. Bump ref in the same commit that bumps the framework in go.mod; without it the marketplace tracks the default branch and the guidance can drift ahead of your pinned release.

Then use /ocf:docs <topic>, /ocf:new-component, /ocf:new-wrapper, and /ocf:review inside your operator project.

Contributing

Contributions are welcome. Open an issue to discuss significant changes before submitting a pull request. New code should include tests; run go test ./... (or make all) before opening a PR.

Further Reading

• The Missing Layers in Your Kubernetes Operator, a walkthrough of common structural problems in Kubernetes operators and how the framework addresses them.

License

Apache License 2.0. See LICENSE for details.