Controller Framework (ctrlfwk)

A powerful and extensible framework for building Kubernetes controllers using controller-runtime. Transform your imperative controller logic into a declarative, step-based system that's easier to understand, test, and extend.

Key Features

• Step-based Reconciliation: Break complex logic into manageable steps
• Declarative Resources: Builder pattern for resource and dependency management
• Type Safety: Full generic support for custom resources
• Minimal Migration: Works with existing Kubebuilder controllers
• Built-in Observability: Instrumentation, logging, and tracing

Quick Start

Installation

go get github.com/u-ctf/controller-fwk

Example Usage

Transform your Kubebuilder controller with minimal changes:

func (r *TestReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
    logger := logf.FromContext(ctx)
    fwkCtx := ctrlfwk.NewContext[*testv1.Test](ctx, r)

    stepper := ctrlfwk.NewStepperFor[*testv1.Test](fwkCtx, logger).
        WithStep(ctrlfwk.NewFindControllerCustomResourceStep(fwkCtx, r)).
        WithStep(ctrlfwk.NewResolveDynamicDependenciesStep(fwkCtx, r)).
        WithStep(ctrlfwk.NewReconcileResourcesStep(fwkCtx, r)).
        WithFinalStep(ctrlfwk.NewReadyConditionFinalStep(fwkCtx, r, ctrlfwk.SetReadyConditionFromResult(r))).
        Build()

    return stepper.Execute(fwkCtx, req)
}

Documentation

📚 Visit our Wiki for comprehensive guides and documentation:

• Getting Started: Current reconciliation pattern and setup
• Context: Custom-resource state and typed reconciliation data
• Dependencies: External resource resolution
• Resources: Managed object reconciliation
• Watcher Interface: Dynamic watch registration
• Instrumentation: Observability and monitoring

Support & Community

• Issues: Bug Reports & Feature Requests
• Discussions: GitHub Discussions
• API Reference: pkg.go.dev

Contributing

We welcome contributions! Please see our Contributing Guide for details.

---

Built with ❤️ by the U-CTF team