{"id":18641062,"url":"https://github.com/mfojtik/controller-framework","last_synced_at":"2025-11-04T21:30:24.320Z","repository":{"id":185567893,"uuid":"673744606","full_name":"mfojtik/controller-framework","owner":"mfojtik","description":"Simple and Flexible Kubernetes Controller Development Kit","archived":false,"fork":false,"pushed_at":"2023-10-11T23:39:46.000Z","size":7648,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-12-27T10:11:07.463Z","etag":null,"topics":["controllers","kubernetes","operators"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mfojtik.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-08-02T10:21:42.000Z","updated_at":"2023-08-02T13:16:49.000Z","dependencies_parsed_at":null,"dependency_job_id":"7a0a2a24-bd56-4a5f-9ccb-20414c5843dd","html_url":"https://github.com/mfojtik/controller-framework","commit_stats":null,"previous_names":["mfojtik/controller-framework"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mfojtik%2Fcontroller-framework","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mfojtik%2Fcontroller-framework/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mfojtik%2Fcontroller-framework/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mfojtik%2Fcontroller-framework/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mfojtik","download_url":"https://codeload.github.com/mfojtik/controller-framework/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239441677,"owners_count":19639122,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["controllers","kubernetes","operators"],"created_at":"2024-11-07T05:56:22.265Z","updated_at":"2025-11-04T21:30:24.171Z","avatar_url":"https://github.com/mfojtik.png","language":"Go","readme":"# Simple Kubernetes Controller Development Kit\n\n[![CodeQL](https://github.com/mfojtik/controller-framework/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/mfojtik/controller-framework/actions/workflows/github-code-scanning/codeql)\n[![Dependency Review](https://github.com/mfojtik/controller-framework/actions/workflows/dependency-review.yml/badge.svg)](https://github.com/mfojtik/controller-framework/actions/workflows/dependency-review.yml)\n[![Go](https://github.com/mfojtik/controller-framework/actions/workflows/go.yml/badge.svg)](https://github.com/mfojtik/controller-framework/actions/workflows/go.yml)\n[![Go Reference](https://pkg.go.dev/badge/github.com/mfojtik/controller-framework.svg)](https://pkg.go.dev/github.com/mfojtik/controller-framework)\n\nThe **controller-framework** is a versatile Golang module designed to facilitate the creation of robust and feature-rich [Kubernetes controllers](https://kubernetes.io/docs/concepts/architecture/controller). This framework offers a straightforward approach to building controllers with essential functionalities, including graceful shutdown handling, informer synchronization, and work queue management. Contrasted with the [controller-runtime](https://github.com/kubernetes-sigs/controller-runtime) library, the controller-framework prioritizes simplicity and flexibility, making it an ideal choice for crafting controllers that closely resemble the traditional ones used within the Kubernetes project.\n\n## Features\n\n- **Graceful Shutdown**: The Controller Framework ensures a smooth and graceful shutdown of your controllers. It allows ongoing workers to finalize and resources to be managed appropriately before the controller terminates.\n\n- **Informer Synchronization**: Easily synchronize informers with the controller-framework, enabling seamless tracking and reaction to changes in Kubernetes resources. The module abstracts the complexity of informer cache synchronization.\n\n- **Workqueue Management**: The framework streamlines work queue management, allowing tasks to be efficiently queued and processed. It handles retries and back-off strategies for any failed tasks, promoting reliability.\n\n- **Simplicity and Flexibility**: Prioritizing simplicity, the controller-framework minimizes boilerplate code, empowering developers to focus on implementing the core logic of their controllers.\n\n- **Familiar Kubernetes Controller Paradigm**: Controllers created using this framework mirror the established structure and design principles of traditional Kubernetes controllers. Developers familiar with Kubernetes controller development will find it intuitive to work with this framework.\n\nThe original location for this framework is OpenShift [library-go](https://github.com/openshift/library-go/tree/master/pkg/controller/factory) repository and this framework is used as controller framework\nfor all OpenShift control plane operators. It has been proven stable, reliable and with minimum issues for multiple OpenShift releases.\n\n\n## Installation\n\nStart to integrate the controller framework into your Golang project by using `factory` Go modules:\n\n```bash\nimport \"github.com/mfojtik/controller-framework/pkg/factory\"\n```\n\nThe factory provide a builder that produce all Kubernetes controller boilerplate. To learn how flexible it is, read the  [documentation](https://pkg.go.dev/github.com/mfojtik/controller-framework@master/pkg/factory)\n\n```go\nfunc New() framework.controller {\n    return factory.New().ToController(\"new-controller\", eventRecorder)\t\n}\n```\n\nYou can access the workqueue inside the `sync()` function via the [controller context](https://pkg.go.dev/github.com/mfojtik/controller-framework@master/pkg/context).\n\n```go\nfunc (c *controller) sync(ctx context.Context, syncCtx framework.Context) error {\n\tsyncCtx.Recorder().Eventf(...)\n\tsyncCtx.Queue().Add(\"key\")\n}\n```\n\nAnd finally, for Kubernetes Event management, you can use included [Event Recorder](https://pkg.go.dev/github.com/mfojtik/controller-framework@master/pkg/events) which offers various\nbackends for storing events (filesystem, [Kubernetes Events](https://pkg.go.dev/k8s.io/client-go@v0.27.4/kubernetes/typed/events/v1#NewForConfig), in-memory events, etc.)\n```go\n...\n\nrecorder := events.NewRecorder(client.CoreV1().Events(\"test-namespace\"), \"test-operator\", controllerRef)\n\n...\n```\n\n## Getting Started\n\nUtilizing the controller framework is straightforward. Here's a simple example showcasing how to create a controller:\n\n```go\n// simple_controller.go:\npackage simple\n\nimport (\n\t\"context\"\n\t\"errors\"\n\t\"os\"\n\t\"time\"\n\n\t\"github.com/mfojtik/controller-framework/pkg/events\"\n\t\"github.com/mfojtik/controller-framework/pkg/factory\"\n\t\"github.com/mfojtik/controller-framework/pkg/framework\"\n)\n\ntype controller struct {}\n\nfunc New(recorder events.Recorder) framework.Controller {\n\tc := \u0026controller{}\n\treturn factory.New().\n\t\tWithSync(c.sync).                // reconcile function\n\t\t// WithInformers(secretInformer) // react to secretInformer changes\n\t\tResyncEvery(10*time.Second).     // queue sync() every 10s regardless of informers\n\t\tToController(\"simple\", recorder)\n}\n\nfunc (c *controller) sync(ctx context.Context, controllerContext framework.Context) error {\n\t// do stuff\n\t_, err := os.ReadFile(\"/etc/cert.pem\")\n\tif errors.Is(err, os.ErrNotExist) {\n\t\t// controller will requeue and retry\n\t\treturn errors.New(\"file not found\")\n\t}\n\treturn nil\n}\n\n// main.go:\n\nfunc main() {\n\t// the controllerRef is an Kubernetes ownerReference to an object the events will tied to (a pod, namespace, etc)\n\trecorder := events.NewRecorder(client.CoreV1().Events(\"test-namespace\"), \"test-operator\", controllerRef)\n\t\n\tcontroller := simple.New(recorder)\n\t\n\t// when this context is done, the controllers will gracefully shutddown\n\tctx := context.Background()\n\t\n\t// start the controller with one worker\n\tgo controller.Run(ctx, 1)\n\t...\n}\n```\n\nCheck the [Examples](https://github.com/mfojtik/controller-framework/tree/master/examples) for more controller examples.\n\n## Contribution\n\nContributions to the controller-framework are welcomed! Feel free to submit issues and pull requests via the [GitHub repository](https://github.com/mfojtik/controller-framework).\n\n## License\n\nThe Controller Framework is distributed under the Apache v2 License. Refer to the [LICENSE](LICENSE) file for more details.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmfojtik%2Fcontroller-framework","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmfojtik%2Fcontroller-framework","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmfojtik%2Fcontroller-framework/lists"}