Skip to content

improve opening of the README #106

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sourcehawk merged 1 commit into from
Apr 2, 2026
Merged

improve opening of the README #106

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 6 additions & 11 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,25 +4,21 @@
[![Go Report Card](https://goreportcard.com/badge/github.com/sourcehawk/operator-component-framework)](https://goreportcard.com/report/github.com/sourcehawk/operator-component-framework)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)

A Go framework for building highly maintainable Kubernetes operators using a behavioral component model and
version-gated feature mutations.
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.

<p align="center">
<img width="400" height="400" alt="OCF Logo" src="https://github.com/user-attachments/assets/ac8162e7-5963-4284-a590-5a9215090103" />
</p>

---

The framework is organized into three composable layers:

- **Components** group related resources into a single reconcilable unit with one user-facing condition.
- **Resource Primitives** wrap individual Kubernetes objects with built-in lifecycle semantics (health, suspension,
completion).
- **Feature Mutations** apply version-gated or feature-gated modifications to resource definitions without polluting the
baseline.

## Mental Model

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

```
Controller
└─ Component
Expand All @@ -35,7 +31,6 @@ Controller
| **Controller** | Determines which components should exist; orchestrates reconciliation at a high level |
| **Component** | Represents one logical feature; reconciles its resources and reports a single condition |
| **Resource Primitive** | Encapsulates desired state and lifecycle behavior for a single Kubernetes object |
Comment on lines 22 to 33
Copy link

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Mental Model diagram includes a “Kubernetes Object” layer, but the responsibility table no longer includes a matching row. This makes the section inconsistent and can confuse readers; either add the Kubernetes Object row back (as before) or remove it from the diagram / adjust the intro wording so both representations align.

Copilot uses AI. Check for mistakes.
| **Kubernetes Object** | The raw `client.Object` (e.g. `Deployment`) persisted to the cluster |

## Features

Expand Down
Loading