{"id":16513914,"url":"https://github.com/twin/k8s-ttl-controller","last_synced_at":"2025-03-16T19:30:37.546Z","repository":{"id":43533289,"uuid":"511318493","full_name":"TwiN/k8s-ttl-controller","owner":"TwiN","description":"Kubernetes controller that enables timed resource deletion using TTL annotation","archived":false,"fork":false,"pushed_at":"2025-03-05T00:51:14.000Z","size":6658,"stargazers_count":54,"open_issues_count":6,"forks_count":7,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-03-16T04:51:10.588Z","etag":null,"topics":["annotations","controller","delete","expiration","golang","janitor","kubernetes","kubernetes-controller","temporary","timed","ttl"],"latest_commit_sha":null,"homepage":"","language":"Go","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/TwiN.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,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["TwiN"]}},"created_at":"2022-07-06T23:13:27.000Z","updated_at":"2025-03-10T12:05:50.000Z","dependencies_parsed_at":"2023-02-16T13:30:44.609Z","dependency_job_id":"a848a301-6b39-4b50-a767-98843f63acfd","html_url":"https://github.com/TwiN/k8s-ttl-controller","commit_stats":{"total_commits":105,"total_committers":2,"mean_commits":52.5,"dds":"0.36190476190476195","last_synced_commit":"94bf8aaa86d8065c53ec5345e075f00bebef34e9"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TwiN%2Fk8s-ttl-controller","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TwiN%2Fk8s-ttl-controller/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TwiN%2Fk8s-ttl-controller/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TwiN%2Fk8s-ttl-controller/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TwiN","download_url":"https://codeload.github.com/TwiN/k8s-ttl-controller/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243919845,"owners_count":20368956,"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":["annotations","controller","delete","expiration","golang","janitor","kubernetes","kubernetes-controller","temporary","timed","ttl"],"created_at":"2024-10-11T16:10:50.129Z","updated_at":"2025-03-16T19:30:37.533Z","avatar_url":"https://github.com/TwiN.png","language":"Go","funding_links":["https://github.com/sponsors/TwiN"],"categories":[],"sub_categories":[],"readme":"# k8s-ttl-controller\n![test](https://github.com/TwiN/k8s-ttl-controller/actions/workflows/test.yml/badge.svg)\n\nThis application allow you to specify a TTL (time to live) on your Kubernetes resources. Once the TTL is reached,\nthe resource will be automatically deleted.\n\nTo configure the TTL, all you have to do is annotate the relevant resource(s) with `k8s-ttl-controller.twin.sh/ttl` and\na value such as `30m`, `24h` and `7d`. \n\nThe resource is deleted after the current timestamp surpasses the sum of the resource's `metadata.creationTimestamp` and \nthe duration specified by the `k8s-ttl-controller.twin.sh/ttl` annotation.\n\nIf the resource is annotated with `k8s-ttl-controller.twin.sh/refreshed-at`, the TTL will be calculated from the value of\nthis annotation instead of the `metadata.creationTimestamp`.\n\n## Usage\n### Setting a TTL on a resource\nTo set a TTL on a resource, all you have to do is add the annotation `k8s-ttl-controller.twin.sh/ttl` on the resource\nyou want to eventually expire with a duration from the creation of the resource as value.\n\nIn other words, if you had a pod named `hello-world` that was created 20 minutes ago, and you annotated it with:\n```console\nkubectl annotate pod hello-world k8s-ttl-controller.twin.sh/ttl=1h\n```\nThe pod `hello-world` would be deleted in approximately 40 minutes, because 20 minutes have already elapsed, leaving\n40 minutes until the target TTL of 1h is reached.\n\nAlternatively, you can create resources with the annotation already present:\n```yaml\napiVersion: v1\nkind: Pod\nmetadata:\n  name: nginx\n  annotations:\n    k8s-ttl-controller.twin.sh/ttl: \"1h\"\nspec:\n  containers:\n    - name: web\n      image: nginx\n```\nThe above would cause the pod to be deleted 1 hour after its creation.\n\nThis is especially useful if you want to create temporary resources without having to worry about unnecessary\nresources accumulating over time.\n\nYou can delay a resource from being deleted by using the `k8s-ttl-controller.twin.sh/refreshed-at` annotation, as \nthe value of said annotation will be used instead of `metadata.creationTimestamp` to calculate the TTL:\n```console\nkubectl annotate pod hello-world k8s-ttl-controller.twin.sh/refreshed-at=2024-12-08T20:48:11Z\n```\nYou can use the following to save yourself from timezone shenanigans:\n```console\nkubectl annotate pod hello-world k8s-ttl-controller.twin.sh/refreshed-at=$(date -u +\"%Y-%m-%dT%H:%M:%SZ\")\n```\n\nYou can use environment variable `API_RESOURCES_TO_WATCH` to specify the resources to watch. By default, the controller watches\nall resources in the cluster. You can specify a comma-separated list of resources to watch, such as `pods,deployments`.\n\n```console\nexport API_RESOURCES_TO_WATCH=pods,deployments\n```\n\n## Deploying on Kubernetes\n### Using Helm\nFor the chart associated to this project, see [TwiN/helm-charts](https://github.com/TwiN/helm-charts):\n```console\nhelm repo add twin https://twin.github.io/helm-charts\nhelm repo update\nhelm install k8s-ttl-controller twin/k8s-ttl-controller -n kube-system\n```\n\n### Using a YAML file\n```yaml\napiVersion: v1\nkind: ServiceAccount\nmetadata:\n  name: k8s-ttl-controller\n  namespace: kube-system\n  labels:\n    app: k8s-ttl-controller\n---\napiVersion: rbac.authorization.k8s.io/v1\nkind: ClusterRole\nmetadata:\n  name: k8s-ttl-controller\n  labels:\n    app: k8s-ttl-controller\nrules:\n  - apiGroups:\n      - \"*\"\n    resources:\n      - \"*\"\n    verbs:\n      - \"get\"\n      - \"list\"\n      - \"delete\"\n  - apiGroups:\n      - \"\"\n      - \"events.k8s.io\"\n    resources:\n      - \"events\"\n    verbs:\n      - \"create\"\n---\napiVersion: rbac.authorization.k8s.io/v1\nkind: ClusterRoleBinding\nmetadata:\n  name: k8s-ttl-controller\n  labels:\n    app: k8s-ttl-controller\nroleRef:\n  kind: ClusterRole\n  name: k8s-ttl-controller\n  apiGroup: rbac.authorization.k8s.io\nsubjects:\n  - kind: ServiceAccount\n    name: k8s-ttl-controller\n    namespace: kube-system\n---\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: k8s-ttl-controller\n  namespace: kube-system\n  labels:\n    app: k8s-ttl-controller\nspec:\n  replicas: 1\n  selector:\n    matchLabels:\n      app: k8s-ttl-controller\n  template:\n    metadata:\n      labels:\n        app: k8s-ttl-controller\n    spec:\n      automountServiceAccountToken: true\n      serviceAccountName: k8s-ttl-controller\n      restartPolicy: Always\n      dnsPolicy: Default\n      containers:\n        - name: k8s-ttl-controller\n          image: ghcr.io/twin/k8s-ttl-controller\n          imagePullPolicy: Always\n```\n\n### Docker \n```console\ndocker pull ghcr.io/twin/k8s-ttl-controller\n```\n\n\n## Development\nFirst, you need to configure your kubeconfig to point to an existing, accessible cluster from your machine so that `kubectl` can be used.\n\nIf you don't have one or wish to use a different cluster, you can create a kind cluster using the following command:\n```console\nmake kind-create-cluster\n```\nNext, you must start k8s-ttl-controller locally:\n```console\nmake run\n```\n\nTo test the application, you can create any resource and annotate it with the `k8s-ttl-controller.twin.sh/ttl` annotation:\n```console\nkubectl run nginx --image=nginx\nkubectl annotate pod nginx k8s-ttl-controller.twin.sh/ttl=1h\n```\nYou should then see something like this in the logs:\n```console\n2022/07/10 13:31:40 [pods/nginx] is configured with a TTL of 1h, which means it will expire in 57m10s\n```\nIf you want to ensure that expired resources are properly deleted, you can simply set a very low TTL, such as:\n```console\nkubectl annotate pod nginx k8s-ttl-controller.twin.sh/ttl=1s\n```\nYou would then see something like this in the logs:\n```console\n2022/07/10 13:36:53 [pods/nginx2] is configured with a TTL of 1s, which means it has expired 2m3s ago\n2022/07/10 13:36:53 [pods/nginx2] deleted\n```\n\nTo clean up the kind cluster:\n```console\nmake kind-clean\n```\n\n\n## Debugging\nTo enable debugging logs, you may set the `DEBUG` environment variable to `true`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftwin%2Fk8s-ttl-controller","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftwin%2Fk8s-ttl-controller","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftwin%2Fk8s-ttl-controller/lists"}