Home

Controller Framework (ctrlfwk) Wiki

Welcome to the Controller Framework wiki! This framework provides a structured, step-based approach to building Kubernetes controllers using controller-runtime.

What is Controller Framework?

Controller Framework is a powerful abstraction layer that sits on top of controller-runtime, making it easier to build maintainable and robust Kubernetes controllers. It transforms the traditional imperative approach into a declarative, step-based system that's easier to understand, test, and extend.

Key Benefits

• Step-based Reconciliation: Break complex controller logic into manageable, discrete steps
• Dependency Management: Handle external resource dependencies with built-in waiting and validation
• Resource Management: Declaratively manage Kubernetes resources with lifecycle hooks
• Type Safety: Full generic type support for your custom resources
• Minimal Migration: Requires minimal changes to existing Kubebuilder controllers
• Builder Pattern: Fluent APIs for creating resources and dependencies
• Observability: Built-in instrumentation, logging, and error handling
• Testing: Comprehensive mocking support for unit testing

Framework Philosophy

The Controller Framework is built around several key principles:

Declarative Over Imperative

Instead of writing procedural reconciliation logic, you declare:

• What resources your controller manages
• What dependencies it requires
• What steps should be executed in order

Composability

Every component is designed to be:

• Reusable across different controllers
• Testable in isolation
• Extensible with custom logic

Type Safety

• Full generic support ensures compile-time safety
• No runtime type casting or reflection surprises
• Clear interfaces that guide implementation

Observability First

• Built-in structured logging
• Automatic instrumentation hooks
• Clear error propagation and handling

Architecture Overview

The framework builds on top a basic principle: Each reconciliation is a sequence of well-defined steps, where each step guide you towards achieving your desired state. In that sense, when the reconciliation process reaches the final step successfully, it indicates that the resource is in the desired "Ready" state. If any issues arise during the steps, the framework allows you to explicitly mark the resource as not ready and halt further processing.

The framework also provides you with a bunch of pre-defined generic steps to handle common tasks like dependency resolution and resource reconciliation, while also allowing you to define custom steps for your specific logic.

This is what an example controller looks like under the hood:

┌─────────────────────────────────────────────────────────────────┐
│                        Your Controller                          │
├─────────────────────────────────────────────────────────────────┤
│  Reconciler Interface  │  Dependencies  │    Resources          │
├─────────────────────────────────────────────────────────────────┤
│                          Stepper                                │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐    │
│  │  Find   │ │Resolve  │ │Reconcile│ │ Custom  │ │   End   │    │
│  │   CR    │ │  Deps   │ │Resources│ │  Steps  │ │  Step   │    │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘    │
├─────────────────────────────────────────────────────────────────┤
│                    Controller Framework                         │
├─────────────────────────────────────────────────────────────────┤
│                     Controller Runtime                          │
└─────────────────────────────────────────────────────────────────┘

Getting Help

• Documentation: Start with this wiki for comprehensive guides
• Discussions: GitHub Discussions for questions and ideas
• Issues: GitHub Issues for bug reports and feature requests
• API Docs: pkg.go.dev for API reference

---

Built by the U-CTF team