operator-component-framework

module
v0.16.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 2, 2026 License: Apache-2.0

README

Operator Component Framework

Go Reference Go Report Card License

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.

OCF Logo

[!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

⚪ 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

License

Apache License 2.0. See LICENSE for details.

Directories

Path Synopsis
e2e
framework
Package framework provides shared infrastructure for E2E tests.
 Package framework provides shared infrastructure for E2E tests.
examples
component-prerequisites command
Package main demonstrates component-level prerequisites with DependsOn.
 Package main demonstrates component-level prerequisites with DependsOn.
component-prerequisites/app
Package app provides a sample controller demonstrating component-level prerequisites.
 Package app provides a sample controller demonstrating component-level prerequisites.
component-prerequisites/resources
Package resources provides resource factories for the component-prerequisites example.
 Package resources provides resource factories for the component-prerequisites example.
custom-resource command
Package main demonstrates managing a custom resource using the unstructured static builder.
 Package main demonstrates managing a custom resource using the unstructured static builder.
custom-resource/app
Package app provides a sample controller demonstrating custom resource management via the unstructured static builder.
 Package app provides a sample controller demonstrating custom resource management via the unstructured static builder.
custom-resource/resources
Package resources provides resource factories for the custom-resource example.
 Package resources provides resource factories for the custom-resource example.
extraction-and-guards command
Package main demonstrates data extraction and guard-based resource ordering.
 Package main demonstrates data extraction and guard-based resource ordering.
extraction-and-guards/app
Package app provides a sample controller demonstrating data extraction and guards.
 Package app provides a sample controller demonstrating data extraction and guards.
extraction-and-guards/resources
Package resources provides resource factories for the extraction-and-guards example.
 Package resources provides resource factories for the extraction-and-guards example.
grace-inconsistency command
Package main demonstrates suppressing the grace inconsistency warning.
 Package main demonstrates suppressing the grace inconsistency warning.
grace-inconsistency/app
Package app provides a sample controller demonstrating grace inconsistency suppression.
 Package app provides a sample controller demonstrating grace inconsistency suppression.
grace-inconsistency/resources
Package resources provides resource factories for the grace-inconsistency example.
 Package resources provides resource factories for the grace-inconsistency example.
mutations-and-gating command
Package main demonstrates mutations and resource-level gating.
 Package main demonstrates mutations and resource-level gating.
mutations-and-gating/app
Package app provides a sample controller demonstrating mutations and gating.
 Package app provides a sample controller demonstrating mutations and gating.
mutations-and-gating/features
Package features provides example mutations for the mutations-and-gating example.
 Package features provides example mutations for the mutations-and-gating example.
mutations-and-gating/resources
Package resources provides resource factories for the mutations-and-gating example.
 Package resources provides resource factories for the mutations-and-gating example.
shared/app
Package app provides the ExampleApp CRD definition shared across examples.
 Package app provides the ExampleApp CRD definition shared across examples.
version-matrix/app
Package app re-exports the shared ExampleApp CRD for the version-matrix example.
 Package app re-exports the shared ExampleApp CRD for the version-matrix example.
version-matrix/resources
Package resources builds the version-gated StatefulSet for the version-matrix example.
 Package resources builds the version-gated StatefulSet for the version-matrix example.
internal
scope
Package scope provides utilities for determining Kubernetes resource scope compatibility, particularly for owner reference eligibility.
 Package scope provides utilities for determining Kubernetes resource scope compatibility, particularly for owner reference eligibility.
pkg
component
Package component provides the core framework for managing Kubernetes resources as logical components.
 Package component provides the core framework for managing Kubernetes resources as logical components.
component/concepts
Package concepts defines the core concepts for the operator component framework.
 Package concepts defines the core concepts for the operator component framework.
feature
Package feature provides gating mechanisms for conditional mutations and resource lifecycle control.
 Package feature provides gating mechanisms for conditional mutations and resource lifecycle control.
generic
Package generic provides generic builders and resources for operator components.
 Package generic provides generic builders and resources for operator components.
mutation/editors
Package editors provides editors for mutating Kubernetes objects.
 Package editors provides editors for mutating Kubernetes objects.
mutation/selectors
Package selectors provides selectors for filtering Kubernetes objects.
 Package selectors provides selectors for filtering Kubernetes objects.
primitives
Package primitives hosts cross-kind contracts shared by the concrete primitive packages under pkg/primitives.
 Package primitives hosts cross-kind contracts shared by the concrete primitive packages under pkg/primitives.
primitives/clusterrole
Package clusterrole provides a builder and resource for managing Kubernetes ClusterRoles.
 Package clusterrole provides a builder and resource for managing Kubernetes ClusterRoles.
primitives/clusterrolebinding
Package clusterrolebinding provides a builder and resource for managing Kubernetes ClusterRoleBindings.
 Package clusterrolebinding provides a builder and resource for managing Kubernetes ClusterRoleBindings.
primitives/configmap
Package configmap provides a builder and resource for managing Kubernetes ConfigMaps.
 Package configmap provides a builder and resource for managing Kubernetes ConfigMaps.
primitives/cronjob
Package cronjob provides a builder and resource for managing Kubernetes CronJobs.
 Package cronjob provides a builder and resource for managing Kubernetes CronJobs.
primitives/daemonset
Package daemonset provides a builder and resource for managing Kubernetes DaemonSets.
 Package daemonset provides a builder and resource for managing Kubernetes DaemonSets.
primitives/deployment
Package deployment provides a builder and resource for managing Kubernetes Deployments.
 Package deployment provides a builder and resource for managing Kubernetes Deployments.
primitives/hpa
Package hpa provides a builder and resource for managing Kubernetes HorizontalPodAutoscalers.
 Package hpa provides a builder and resource for managing Kubernetes HorizontalPodAutoscalers.
primitives/ingress
Package ingress provides a builder and resource for managing Kubernetes Ingresses.
 Package ingress provides a builder and resource for managing Kubernetes Ingresses.
primitives/job
Package job provides a builder and resource for managing Kubernetes Jobs.
 Package job provides a builder and resource for managing Kubernetes Jobs.
primitives/networkpolicy
Package networkpolicy provides a builder and resource for managing Kubernetes NetworkPolicies.
 Package networkpolicy provides a builder and resource for managing Kubernetes NetworkPolicies.
primitives/pdb
Package pdb provides a builder and resource for managing Kubernetes PodDisruptionBudgets.
 Package pdb provides a builder and resource for managing Kubernetes PodDisruptionBudgets.
primitives/pod
Package pod provides a builder and resource for managing Kubernetes Pods.
 Package pod provides a builder and resource for managing Kubernetes Pods.
primitives/pv
Package pv provides a builder and resource for managing Kubernetes PersistentVolumes.
 Package pv provides a builder and resource for managing Kubernetes PersistentVolumes.
primitives/pvc
Package pvc provides a builder and resource for managing Kubernetes PersistentVolumeClaims.
 Package pvc provides a builder and resource for managing Kubernetes PersistentVolumeClaims.
primitives/replicaset
Package replicaset provides a builder and resource for managing Kubernetes ReplicaSets.
 Package replicaset provides a builder and resource for managing Kubernetes ReplicaSets.
primitives/role
Package role provides a builder and resource for managing Kubernetes Roles.
 Package role provides a builder and resource for managing Kubernetes Roles.
primitives/rolebinding
Package rolebinding provides a builder and resource for managing Kubernetes RoleBindings.
 Package rolebinding provides a builder and resource for managing Kubernetes RoleBindings.
primitives/secret
Package secret provides a builder and resource for managing Kubernetes Secrets.
 Package secret provides a builder and resource for managing Kubernetes Secrets.
primitives/service
Package service provides a builder and resource for managing Kubernetes Services.
 Package service provides a builder and resource for managing Kubernetes Services.
primitives/serviceaccount
Package serviceaccount provides a builder and resource for managing Kubernetes ServiceAccounts.
 Package serviceaccount provides a builder and resource for managing Kubernetes ServiceAccounts.
primitives/statefulset
Package statefulset provides a builder and resource for managing Kubernetes StatefulSets.
 Package statefulset provides a builder and resource for managing Kubernetes StatefulSets.
primitives/unstructured
Package unstructured provides shared types for building unstructured Kubernetes resource primitives.
 Package unstructured provides shared types for building unstructured Kubernetes resource primitives.
primitives/unstructured/integration
Package integration provides an unstructured resource primitive for Kubernetes integration objects that depend on external assignments and require operational status tracking and suspension support.
 Package integration provides an unstructured resource primitive for Kubernetes integration objects that depend on external assignments and require operational status tracking and suspension support.
primitives/unstructured/static
Package static provides an unstructured resource primitive for static Kubernetes objects that do not model convergence health, grace periods, or suspension.
 Package static provides an unstructured resource primitive for static Kubernetes objects that do not model convergence health, grace periods, or suspension.
primitives/unstructured/task
Package task provides an unstructured resource primitive for Kubernetes objects that run to completion, requiring completion status tracking and suspension support.
 Package task provides an unstructured resource primitive for Kubernetes objects that run to completion, requiring completion status tracking and suspension support.
primitives/unstructured/workload
Package workload provides an unstructured resource primitive for long-running Kubernetes workload objects that require health tracking, graceful rollouts, and suspension support.
 Package workload provides an unstructured resource primitive for long-running Kubernetes workload objects that require health tracking, graceful rollouts, and suspension support.
recording
Package recording provides utilities for recording Kubernetes events.
 Package recording provides utilities for recording Kubernetes events.
testing/golden
Package golden provides snapshot testing utilities for verifying resource primitive output across versions.
 Package golden provides snapshot testing utilities for verifying resource primitive output across versions.
testing/goldengen
Package goldengen is a test-only helper that sweeps a consumer-supplied version universe, classifies versions into behaviorally-distinct gating regimes by firing-set, generates the minimal goldens covering them, and asserts per-fixture mutation gating.
 Package goldengen is a test-only helper that sweeps a consumer-supplied version universe, classifies versions into behaviorally-distinct gating regimes by firing-set, generates the minimal goldens covering them, and asserts per-fixture mutation gating.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.