A controller to identify unused and unhealthy Kubernetes resources
Tags: kubernetes, showdev, devops, opensource
Published: 2024-01-30 12:31:46

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](https://github.com/gianlucam76/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:

```yaml
# 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](https://github.com/gianlucam76/k8s-cleaner/blob/main/examples/persistent-volume-claims/unused_persistent-volume-claims.yaml) finds all PersistentVolumeClaims currently not used by any Pods.

## Library

k8s-cleaner comes with [library](https://github.com/gianlucam76/k8s-cleaner/tree/main/unused-resources-examples) 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)](https://github.com/gianlucam76/k8s-cleaner/blob/main/unused-resources-examples/time_based_delete/delete_resource_based_on_ttl_annotation.yaml)**: Detect resources that have exceeded their specified TTL.
2️⃣ **[Expiration date](https://github.com/gianlucam76/k8s-cleaner/blob/main/unused-resources-examples/time_based_delete/delete_resource_based_on_expire_date.yaml)**: Identify resources with an explicit expiration date that has passed.
3️⃣ **[Age](https://github.com/gianlucam76/k8s-cleaner/blob/main/unused-resources-examples/time_based_delete/delete_resources_older_than_24hours.yaml)**: Locate resources that are older than given time.

The k8s-cleaner [library](https://github.com/gianlucam76/k8s-cleaner/tree/main/unhealthy-resources-examples) also extends its capabilities to detect unhealthy resources, with examples of such conditions including:

1️⃣ **[Pods using outdated secrets](https://github.com/gianlucam76/k8s-cleaner/blob/main/unhealthy-resources-examples/pod-with-outdated-secrets/pods-with-outdated-secret-data.yaml)**: Identify pods that are mounting secrets but are referencing outdated content.
2️⃣ **[Pods relying on expired certificates](https://github.com/gianlucam76/k8s-cleaner/blob/main/unhealthy-resources-examples/pod-with-expired-certificates/pods-with-expired-certificates.yaml)**: Detect pods that are using certificates that have exceeded their validity period.
3️⃣ **[Ingress instances exposing non-existent services](https://github.com/gianlucam76/k8s-cleaner/blob/main/unhealthy-resources-examples/object-references/ingress-referencing-non-existent-service.yaml)**: Find Ingress rules referring to nonexistent Services, indicating potential errors or disruptions.
4️⃣ **[Deployment instances mounting non-existent ConfigMaps or Secrets](https://github.com/gianlucam76/k8s-cleaner/blob/main/unhealthy-resources-examples/object-references/deployment-referencing-non-existent-resources.yaml)**: Identify Deployments that are attempting to mount ConfigMaps or Secrets that no longer exist.

## Notifications

[k8s-cleaner](https://github.com/gianlucam76/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

```yaml
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.