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.25.6+ and controller-runtime v0.22 or later.

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

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.