{"id":37431686,"url":"https://github.com/m3dev/broom","last_synced_at":"2026-01-16T06:35:44.318Z","repository":{"id":230865350,"uuid":"779163499","full_name":"m3dev/broom","owner":"m3dev","description":"broom is a Kubernetes Custom Controller designed to gracefully handle OOM events in CronJobs by dynamically increasing memory limits","archived":false,"fork":false,"pushed_at":"2025-04-17T10:06:49.000Z","size":67,"stargazers_count":8,"open_issues_count":2,"forks_count":0,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-12-22T11:53:18.292Z","etag":null,"topics":["cronjob","kubernetes"],"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/m3dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-03-29T07:20:38.000Z","updated_at":"2025-04-17T10:06:15.000Z","dependencies_parsed_at":"2024-04-11T23:39:11.882Z","dependency_job_id":"626d43d5-eb20-4402-b7be-3e1f08bb8a44","html_url":"https://github.com/m3dev/broom","commit_stats":null,"previous_names":["m3dev/broom"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/m3dev/broom","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m3dev%2Fbroom","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m3dev%2Fbroom/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m3dev%2Fbroom/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m3dev%2Fbroom/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/m3dev","download_url":"https://codeload.github.com/m3dev/broom/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m3dev%2Fbroom/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28477881,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T06:30:42.265Z","status":"ssl_error","status_checked_at":"2026-01-16T06:30:16.248Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["cronjob","kubernetes"],"created_at":"2026-01-16T06:35:43.543Z","updated_at":"2026-01-16T06:35:44.307Z","avatar_url":"https://github.com/m3dev.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"https://github.com/m3dev/broom/assets/60843722/8860aaa0-e0b8-45cf-9b9e-59197dfc57a3\" width=\"50%\"\u003e\n\n**broom** is a Kubernetes Custom Controller designed to gracefully handle Out of Memory (OOM) events in CronJobs by dynamically increasing memory limits.\n\nIt offers the following features:\n\n* **Dynamic Memory Limit Adjustment**: Automatically increases the memory limit of containers that experience OOM events within CronJob specs.\n\n* **Flexible Memory Adjustment Methods**: Users can choose between addition and multiplication methods for increasing memory limits.\n\n* **Automatic Job Restart**: Optionally, broom can restart the failed jobs with updated spec for recovery.\n\n* **Flexible Targeting**: Allows specifying target CronJobs using combinations of Name, Namespace, and Labels.\n\n* **Slack Notification Integration**: Provides webhook notifications to Slack, informing users about the results of updates and restarts.\n\n## Description\n\n### How it works\nWhen a `phase: Failed` Pod is detected, the reconciliation loop iterates as follows:\n\n\u003cimg src=\"https://github.com/m3dev/broom/assets/60843722/df5219f3-d30f-47e9-84ef-a8c045cf1c1f\" width=\"50%\"\u003e\n\nUpon identifying a Pod terminated due to `reason: OOMKilled`, the controller traces back through the `ownerReferences` from Pod to Job to CronJob.\nOnce the controller identifies the relevant CronJob, it prepares a modified specification with relaxed memory limits (`spec.jobTemplate.spec.containers[].resources.limits.memory`), such as doubling the original limit.\nSubsequently, the controller updates the specification of the CronJob with the modified memory limits.\nOptionally, the controller can restart the failed Job once using the updated memory limits. Finally, the controller sends a notification to Slack with the following content:\n\n\u003cimg src=\"https://github.com/m3dev/broom/assets/60843722/d7ed0819-0f4c-4f48-8763-04db017e6aac\" width=\"50%\"\u003e\n\n### Configuration\n\nThe controller can be configured using a `Broom` custom resource, which allows users to specify the following parameters:\n\n```yaml\napiVersion: ai.m3.com/v1alpha1\nkind: Broom\nmetadata:\n  name: broom-sample\nspec:\n  target:\n    name: oom-sample\n    labels:\n      m3.com/use-broom: \"true\"\n    namespace: broom\n  adjustment:\n    type: Mul\n    value: \"2\"\n    maxLimit: 250Mi\n  restartPolicy: OnSpecChanged\n  slackWebhook:\n    secret:\n      namespace: default\n      name: broom\n      key: SLACK_WEBHOOK_URL\n    channel: \"#alert\"\n```\n\n* `target` \u003csmall\u003e(optional)\u003c/small\u003e : Target CronJob conditions. If not specified, the controller will target all CronJobs in the cluster.\n  * `namespace` \u003csmall\u003e(optional)\u003c/small\u003e : Namespace of the target CronJob.\n  * `name` \u003csmall\u003e(optional)\u003c/small\u003e : Name of the target CronJob.\n  * `labels` \u003csmall\u003e(optional)\u003c/small\u003e : Labels to filter the target CronJobs.\n\n* `adjustment` \u003csmall\u003e(\u003cfont color=\"red\"\u003erequired\u003c/font\u003e)\u003c/small\u003e : Memory limit adjustment parameters.\n  * `type` \u003csmall\u003e(\u003cfont color=\"red\"\u003erequired\u003c/font\u003e)\u003c/small\u003e : Adjustment method. Choose between `Add` and `Mul`.\n  * `value` \u003csmall\u003e(\u003cfont color=\"red\"\u003erequired\u003c/font\u003e)\u003c/small\u003e : Adjustment value. For `Add`, it is the value to add to the current limit (e.g., `100Mi`). For `Mul`, it is the multiplier to apply to the current limit (e.g., `\"2\"`, must be double-quoted).\n  * `maxLimit` \u003csmall\u003e(optional)\u003c/small\u003e : Maximum memory limit to set.\n\n* `restartPolicy` \u003csmall\u003e(\u003cfont color=\"red\"\u003erequired\u003c/font\u003e)\u003c/small\u003e : Policy for restarting failed Jobs. Choose among `Never` (no restart), `OnOOM` (restart when OOM CronJob is detected), and `OnSpecChanged` (restart only when OOM CronJob is detected and the memory limit is updated).\n\n* `slackWebhook` \u003csmall\u003e(\u003cfont color=\"red\"\u003erequired\u003c/font\u003e)\u003c/small\u003e : Slack notification integration.\n  * `secret` \u003csmall\u003e(\u003cfont color=\"red\"\u003erequired\u003c/font\u003e)\u003c/small\u003e : Kubernetes Secret containing the Slack webhook URL.\n    * `namespace` \u003csmall\u003e(\u003cfont color=\"red\"\u003erequired\u003c/font\u003e)\u003c/small\u003e : Namespace of the Secret.\n    * `name` \u003csmall\u003e(\u003cfont color=\"red\"\u003erequired\u003c/font\u003e)\u003c/small\u003e : Name of the Secret.\n    * `key` \u003csmall\u003e(\u003cfont color=\"red\"\u003erequired\u003c/font\u003e)\u003c/small\u003e : Key containing the webhook URL.\n  * `channel` \u003csmall\u003e(optional)\u003c/small\u003e : Slack channel to send notifications. If not specified, the notification will be sent to the default channel.\n\n\n## Getting Started\n\n### Prerequisites\n- go version v1.21.0+\n- docker version 17.03+.\n- kubectl version v1.11.3+.\n- Access to a Kubernetes v1.11.3+ cluster.\n\n### To Deploy on the cluster\n**Build and push your image to the location specified by `IMG`:**\n\n```sh\nmake docker-build docker-push IMG=\u003csome-registry\u003e/broom:tag\n```\n\n**NOTE:** This image ought to be published in the personal registry you specified. \nAnd it is required to have access to pull the image from the working environment. \nMake sure you have the proper permission to the registry if the above commands don’t work.\n\n**Install the CRDs into the cluster:**\n\n```sh\nmake install\n```\n\n**Deploy the Manager to the cluster with the image specified by `IMG`:**\n\n```sh\nmake deploy IMG=\u003csome-registry\u003e/broom:tag\n```\n\n\u003e **NOTE**: If you encounter RBAC errors, you may need to grant yourself cluster-admin \nprivileges or be logged in as admin.\n\n**Create instances of your solution**\nYou can apply the samples (examples) from the config/sample:\n\n```sh\nkubectl apply -k config/samples/\n```\n\n\u003e**NOTE**: Ensure that the samples has default values to test it out.\n\n### To Uninstall\n**Delete the instances (CRs) from the cluster:**\n\n```sh\nkubectl delete -k config/samples/\n```\n\n**Delete the APIs(CRDs) from the cluster:**\n\n```sh\nmake uninstall\n```\n\n**UnDeploy the controller from the cluster:**\n\n```sh\nmake undeploy\n```\n\n## Project Distribution\n\nFollowing are the steps to build the installer and distribute this project to users.\n\n1. Build the installer for the image built and published in the registry:\n\n```sh\nmake build-installer IMG=\u003csome-registry\u003e/broom:tag\n```\n\nNOTE: The makefile target mentioned above generates an 'install.yaml'\nfile in the dist directory. This file contains all the resources built\nwith Kustomize, which are necessary to install this project without\nits dependencies.\n\n2. Using the installer\n\nUsers can just run kubectl apply -f \u003cURL for YAML BUNDLE\u003e to install the project, i.e.:\n\n```sh\nkubectl apply -f https://raw.githubusercontent.com/\u003corg\u003e/broom/\u003ctag or branch\u003e/dist/install.yaml\n# kubectl apply -f https://raw.githubusercontent.com/m3dev/broom/main/dist/install.yaml\n```\n\n\n**NOTE:** Run `make help` for more information on all potential `make` targets\n\nMore information can be found via the [Kubebuilder Documentation](https://book.kubebuilder.io/introduction.html)\n\n## Contributing\n\nWe welcome contributions from the community! If you'd like to contribute to this project, please follow these guidelines:\n\n### Issues\n\nIf you encounter a bug, have a feature request, or would like to suggest an improvement, please open an issue on the GitHub repository. Make sure to provide detailed information about the problem or suggestion.\n\n### Pull Requests\n\nWe gladly accept pull requests! Before submitting a pull request, please ensure the following:\n\n1. Fork the repository and create your branch from `main`.\n2. Ensure your code adheres to the project's coding standards.\n3. Test your changes thoroughly.\n4. Make sure your commits are descriptive and well-documented.\n5. Update the README and any relevant documentation if necessary.\n\n### Code of Conduct\n\nPlease note that this project is governed by our [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report any unacceptable behavior.\n\nThank you for contributing to our project!\n\n## License\n\nCopyright 2024.\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fm3dev%2Fbroom","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fm3dev%2Fbroom","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fm3dev%2Fbroom/lists"}