{"id":15406356,"url":"https://github.com/otherguy/k8s-pod-cleanup-operator","last_synced_at":"2025-04-17T07:33:30.947Z","repository":{"id":98594786,"uuid":"465856836","full_name":"otherguy/k8s-pod-cleanup-operator","owner":"otherguy","description":"A simple Kubernetes Pod Cleanup Operator","archived":false,"fork":false,"pushed_at":"2025-03-07T11:46:31.000Z","size":96,"stargazers_count":2,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-29T06:04:43.687Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/otherguy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"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},"funding":{"github":"otherguy"}},"created_at":"2022-03-03T19:26:23.000Z","updated_at":"2025-02-07T11:47:16.000Z","dependencies_parsed_at":"2024-02-08T13:29:46.681Z","dependency_job_id":"5e18c719-f098-4b73-85df-9d52b4a71d38","html_url":"https://github.com/otherguy/k8s-pod-cleanup-operator","commit_stats":{"total_commits":55,"total_committers":3,"mean_commits":"18.333333333333332","dds":"0.34545454545454546","last_synced_commit":"b456276a81c4af7e19d72bbc1698b50e74ecedea"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/otherguy%2Fk8s-pod-cleanup-operator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/otherguy%2Fk8s-pod-cleanup-operator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/otherguy%2Fk8s-pod-cleanup-operator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/otherguy%2Fk8s-pod-cleanup-operator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/otherguy","download_url":"https://codeload.github.com/otherguy/k8s-pod-cleanup-operator/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249323351,"owners_count":21251138,"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":[],"created_at":"2024-10-01T16:21:30.324Z","updated_at":"2025-04-17T07:33:30.884Z","avatar_url":"https://github.com/otherguy.png","language":"Python","funding_links":["https://github.com/sponsors/otherguy"],"categories":[],"sub_categories":[],"readme":"# ☸️ Kubernetes Pod Cleanup Operator\n\nA Kubernetes Operator to clean up expired pods in any desired non-running state.\n\n[![Docker Version](https://img.shields.io/docker/v/otherguy/k8s-operator-cleanup?sort=semver\u0026style=for-the-badge\u0026logo=docker\u0026logoColor=aaa)][dockerhub]\n[![Docker Pulls](https://img.shields.io/docker/pulls/otherguy/k8s-operator-cleanup?style=for-the-badge\u0026logo=docker\u0026logoColor=aaa)][dockerhub]\n[![GitHub issues](https://img.shields.io/github/issues/otherguy/k8s-pod-cleanup-operator?style=for-the-badge\u0026logo=github)][issues]\n[![License](https://img.shields.io/github/license/otherguy/k8s-pod-cleanup-operator?style=for-the-badge\u0026logo=readthedocs\u0026logoColor=aaa)][license]\n\n## What does it do? 🛠 \n\nThis lightweight Kubernetes Operator will clean up expired pods in any desired non-running state.\n\nFor example, pods with `Evicted` or `Terminated` reason, or even all `Failed` or `Succeeded` pods regardless\nof their termination reason, can be cleaned up.\n\nAdditionally, this operator can be used to clean up pods that are running for a specified amount of time.\n\nTo give a pod a certain lifetime, add the `pod.kubernetes.io/lifetime` annotation to the pod. The value of this annotation\nneeds to be a valid duration in a format [understandable to `parse_timedelta`](https://tempora.readthedocs.io/en/latest/#tempora.parse_timedelta).\n\nExample:\n\n```yaml\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: example\nspec:\n  template:\n    metadata:\n      annotations:\n        pod.kubernetes.io/lifetime: \"12 hours\"\n```\n\n## Usage and Deployment 🚀 \n\n- First, you need a _Kubernetes Service Account_ with the permission to look and, if necessary, delete Pods and Jobs.\n- Then, adapt the [`deployment.yaml`](k8s/deployment.yaml) to suit your needs. This involves picking the correct image\n  tag and modifying the `args` to suit your requirements.\n- Lastly, apply the Deployment to your cluster.\n\n_**Note:** You cannot create a Role that defines permissions unless you already have the permissions defined in the Role. If you\nhave been granted the [cluster-admin](https://cloud.google.com/iam/docs/understanding-roles#kubernetes-engine-roles) IAM role,\nthis is sufficient._\n\nApply the 3 `.yaml` files after you have adapted them:\n\n```bash\n$ kubectl apply --validate -f k8s/namespace.yaml -f k8s/rbac.yaml -f k8s/deployment.yaml\nnamespace/pod-cleanup created\nserviceaccount/pod-cleanup-operator created\nclusterrole.rbac.authorization.k8s.io/pod-cleanup-operator created\nclusterrolebinding.rbac.authorization.k8s.io/pod-cleanup-operator created\ndeployment.apps/pod-cleanup-operator created\n```\n\n### Command Line Arguments\n\n| Argument                         | Default Value                | Example                           | Purpose                                                                                                                                                                                                      |\n|----------------------------------|------------------------------|-----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `-n` or \u003cbr\u003e `--namespace`       |                              | `default`                         | Restrict the filter to just a single namespace. The default (no value) means _all namespaces_.                                                                                                               |\n| `-u` or \u003cbr\u003e `--user`            |                              |                                   | Limit the scope to only user namespaces and exclude `kube-system` objects                                                                                                                                    |\n| `-g` or \u003cbr\u003e `--graceperiod`     | `300`                        | `60`                              | How many seconds a pod has to be in the given state(s) to be considered for deletion.                                                                                                                        |\n| `-l` or \u003cbr\u003e `--label-selector`  | `'{}'`                       | `'{\"app\": \"colortransfer-api\"}'`  | Restrict the filter to just Pods and Jobs that match the [label selector](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/). _Note that the argument value needs to be valid JSON!_ |\n| `--lifetime-annotation`          | `pod.kubernetes.io/lifetime` |                                   | The pod annotation to specify the maximum lifetime.                                                                                                                                                          |\n| `--lifetime-max-kills`           | `1`                          |                                   | How many expired pods to terminate per run.                                                                                                                                                                  |\n| `--quiet`                        |                              |                                   | Be more quiet and only print output when actually deleting pods.                                                                                                                                             |\n| `--interval`                     | `60`                         |                                   | Seconds to wait between runs.                                                                                                                                                                                |\n| `--error-limit`                  | `5`                          |                                   | How many errors are allowed before exiting.                                                                                                                                                                  |\n| `--dry-run`                      |                              |                                   | If the `--dry-run` flag is set, no actual deletion is performed. This can be used for testing.                                                                                                               |\n| `--skip-with-owner`              |                              |                                   | Kubernetes resources with active owner reference will be skipped by enabling this flag \n\nIn addition to the parameters above, the application takes 1 or more status arguments that filter the set of pods to be\ndeleted based on their current state. Each of those arguments can either just be\n[a status](https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/) or a combination of status and reason of Pods\nand Jobs that should be considered for deletion.\n\nFor example, passing `Failed` and `Succeeded` as arguments, would delete all pods that are in the `Failed` or `Succeeded`\nstate, regardless of their termination reason. Passing `Failed:Shutdown` as an argument would delete pods that are in `Failed`\nstate and have their termination reason set to `Shutdown`.\n\n### Additional Reading\n\n- [Managing Service Accounts](https://kubernetes.io/docs/reference/access-authn-authz/service-accounts-admin/)\n- [Configure Service Accounts for Pods](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/)\n\n## Running Locally 👩🏼‍💻 \n\nThe Python script can use either a Service Account for authenticatiob (when deployed in Kubernetes) or your local\n`~/.kube/config` file when running locally.\n\nFirst, install the dependencies:\n\n```bash\npython -m pip install -r requirements.txt\n```\n\nMake sure you have switched to the correct project and cluster and your `kubectl` is configured. Then, simply run\nthe `cleaner.py` script with the desired arguments:\n\n```bash\n$ python cleaner.py --graceperiod 60 --dry-run Failed:Shutdown\nPod Cleanup Operator. Version: 0.x, Commit: main, Build Date: 2021-07-06T13:36:10.700541+00:00\nUsing local ~/.kube/config for authentication\nDeleted 0 pods and 0 jobs.\n```\n\n## What is a Kubernetes Operator? 🤔 \n\nA Kubernetes operator is an application-specific controller that extends the functionality of\nthe Kubernetes API to create, configure, and manage instances of complex applications on behalf\nof a Kubernetes user.\n\n## Contributing 🚧\n\nBug reports and pull requests are welcome on GitHub at [`otherguy/k8s-pod-cleanup-operator`](https://github.com/otherguy/k8s-pod-cleanup-operator).\n\n## Acknowledgements ♥️\n\n* Thank you to [`@tonobo`](https://github.com/tonobo) for contributing https://github.com/otherguy/k8s-pod-cleanup-operator/pull/44\n\nA big ♥️ _thank you_ to all creators!\n\n\n\n[dockerhub]: https://hub.docker.com/repository/docker/otherguy/k8s-operator-cleanup\n[issues]: https://github.com/otherguy/k8s-pod-cleanup-operator/issues\n[license]: https://github.com/otherguy/k8s-pod-cleanup-operator/blob/main/LICENSE.md\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fotherguy%2Fk8s-pod-cleanup-operator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fotherguy%2Fk8s-pod-cleanup-operator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fotherguy%2Fk8s-pod-cleanup-operator/lists"}