A controller to identify unused and unhealthy Kubernetes resources

As Kubernetes deployments grow in complexity and scale, maintaining a clean and efficient cluster becomes increasingly important. While Kubernetes provides tools for resource management, such as garbage collection, it can still be challenging to identify and remove unused or stale resources manually. This is where k8s-cleaner comes in.

What is k8s-cleaner?

It is a Kubernetes controller that identifies stale/orphaned or unhealthy resources. It's designed to handle any Kubernetes resource types (including your own custom resources) and provides sophisticated filtering capabilities, including label-based selection and custom Lua-based criteria.

It provides a flexible and powerful set of features, including:

1️⃣ Flexible scheduling: k8s-cleaner can be scheduled as a DaemonSet or CronJob to run on a regular basis.
2️⃣ Label filtering: You can filter the resources to be cleaned up based on labels.
3️⃣ Lua-based selection criteria: Define custom logic to identify stale resources using Lua scripting.
4️⃣ Notifications: Receive notifications about cleanup activities via Slack, Webex, Discord, or reports.
5️⃣ Resource removal or updates: Remove or update the identified resources based on your preferences.

Why use k8s-cleaner?

There are tools (controllers and not) that can detect stale resources. So why k8s-cleaner? Mainly because those existing solutions have their own static definition of what an unused/unhealthy resource is. k8s-cleaner instead allows you to add your own definition of unused/unhealthy.

Other benefits of using k8s-cleaner:

• Reduced resource consumption: Removing unused or stale resources can free up valuable storage space and CPU/memory resources.
• Improved performance: A clean and efficient cluster can run applications more efficiently.
• Reduced risk of errors: Stale resources can lead to errors and instability in your cluster.
• Simplified management: k8s-cleaner automates the process of identifying and removing stale resources, saving you time and effort.

How to use k8s-cleaner

Installing and using k8s-cleaner is straightforward, simply run this command to install it in your cluster:

kubectl apply -f https://raw.githubusercontent.com/gianlucam76/k8s-cleaner/main/manifest/manifest.yaml

Then create a Cleaner instance to define what resources k8s-cleaner should go after and what to do with identified resources.

Here is an example:

# This Cleaner instance finds any Jobs that:
# - has status.completionTime set
# - has status.succeeded set to a value greater than zero
# - has no running or pending pods
# and instruct Cleaner to delete this Job.
apiVersion: apps.projectsveltos.io/v1alpha1
kind: Cleaner
metadata:
  name: completed-jobs
spec:
  schedule: "* 0 * * *"
  resourcePolicySet:
    resourceSelectors:
    - kind: Job
      group: "batch"
      version: v1
      evaluate: |
        function evaluate()
          hs = {}
          hs.matching = false
          if obj.status ~= nil then
            if obj.status.completionTime ~= nil and obj.status.succeeded > 0 and obj.status.active == 0 then
              hs.matching = true
            end
          end
          return hs
        end
  action: Delete

A Cleaner instance can even evaluate resources of different GroupVersionKinds all together.
For instance this instance finds all PersistentVolumeClaims currently not used by any Pods.

Library

k8s-cleaner comes with library that now includes Cleaner instances for detecting unused resources of various types, including ClusterRole, ConfigMap, Deployment, HorizontalPodAutoscaler, Ingress, Job, PersistentVolume, Pod, Role, Secret, ServiceAccount, and StatefulSet.

In addition to unused resource detection, the library also provides instances for identifying expired resources based on various criteria:

1️⃣ Time to live (TTL): Detect resources that have exceeded their specified TTL.
2️⃣ Expiration date: Identify resources with an explicit expiration date that has passed.
3️⃣ Age: Locate resources that are older than given time.

The k8s-cleaner library also extends its capabilities to detect unhealthy resources, with examples of such conditions including:

1️⃣ Pods using outdated secrets: Identify pods that are mounting secrets but are referencing outdated content.
2️⃣ Pods relying on expired certificates: Detect pods that are using certificates that have exceeded their validity period.
3️⃣ Ingress instances exposing non-existent services: Find Ingress rules referring to nonexistent Services, indicating potential errors or disruptions.
4️⃣ Deployment instances mounting non-existent ConfigMaps or Secrets: Identify Deployments that are attempting to mount ConfigMaps or Secrets that no longer exist.

Notifications

k8s-cleaner keeps you in the loop with handy notifications through Slack, Webex, Discord, or reports. Choose what works best for you!

For instance to send Slack notification, create a Kubernetes Secret:

kubectl create secret generic slack --from-literal=SLACK_TOKEN=<YOUR TOKEN> --from-literal=SLACK_CHANNEL_ID=<YOUR CHANNEL ID>                           

Set then the notifications field of a Cleaner instance

apiVersion: apps.projectsveltos.io/v1alpha1
kind: Cleaner
metadata:
  name: cleaner-with-slack-notifications
spec:
  schedule: "0 * * * *"
  action: Delete # Delete matching resources
  resourcePolicySet:
    resourceSelectors:
    - namespace: test
      kind: Deployment
      group: "apps"
      version: v1
  notifications:
  - name: slack
    type: Slack
    notificationRef:
     apiVersion: v1
     kind: Secret
     name: slack
     namespace: default

Anytime this Cleaner instance is processed, a Slack message is sent containing all the resources identified by k8s-cleaner.

Conclusion

k8s-cleaner is a valuable tool for maintaining a clean and efficient Kubernetes cluster. It can help you reduce resource consumption, improve performance, and reduce the risk of errors. If you are managing a Kubernetes cluster, I encourage you to try out k8s-cleaner.

Comments

[Gianluca]

👉 To get updates ⭐️ star this repository

👉 Working examples can be found in the examples section

If you find the idea useful, I encourage you to contribute to the example directory by adding your own Cleaner configurations 💡

That will help the community benefit from your expertise and build a stronger knowledge base of Cleaner use cases.

To add an example, simply create a new file in the example directory with a descriptive name and put your Cleaner configuration within the file. Once you've added your example, feel free to submit a pull request to share it with the community.

If you push a PR, you wil be automatically listed in the README as contributor as soon as PR is merged. So you will get the credit for that.