feat: delete unused images after a configurable amount of time

Author: plaffitt

api/kuik/v1alpha1/image_types.go

@@ -75,6 +75,8 @@ type ImageStatus struct {
 	UsedByPods ReferencesWithCount `json:"usedByPods,omitempty"`
 	// Upstream is the information about the upstream image
 	Upstream Upstream `json:"upstream,omitempty"`
+	// UnusedSince is the time when the image was last used by a pod
+	UnusedSince metav1.Time `json:"unusedSince,omitempty"`
 }
 
 // +kubebuilder:object:root=true
@@ -85,6 +87,7 @@ type ImageStatus struct {
 // +kubebuilder:printcolumn:name="Image",type="string",JSONPath=".spec.image"
 // +kubebuilder:printcolumn:name="Pods count",type="integer",JSONPath=".status.usedByPods.count"
 // +kubebuilder:printcolumn:name="Upstream status",type="string",JSONPath=".status.upstream.status"
+// +kubebuilder:printcolumn:name="Unused since",type="date",JSONPath=".status.unusedSince"
 // +kubebuilder:printcolumn:name="Age",type="date",JSONPath=".metadata.creationTimestamp"
 
 // Image is the Schema for the images API.

api/kuik/v1alpha1/zz_generated.deepcopy.go

@@ -5,6 +5,7 @@ import (
 	"flag"
 	"os"
 	"path/filepath"
+	"time"
 
 	// Import all Kubernetes client auth plugins (e.g. Azure, GCP, OIDC, etc.)
 	// to ensure that exec-entrypoint and run can make use of them.
@@ -51,6 +52,7 @@ func main() {
 	var probeAddr string
 	var secureMetrics bool
 	var enableHTTP2 bool
+	var unusedImageTTL int
 	var tlsOpts []func(*tls.Config)
 	flag.StringVar(&metricsAddr, "metrics-bind-address", "0", "The address the metrics endpoint binds to. "+
 		"Use :8443 for HTTPS or :8080 for HTTP, or leave as 0 to disable the metrics service.")
@@ -69,6 +71,8 @@ func main() {
 	flag.StringVar(&metricsCertKey, "metrics-cert-key", "tls.key", "The name of the metrics server key file.")
 	flag.BoolVar(&enableHTTP2, "enable-http2", false,
 		"If set, HTTP/2 will be enabled for the metrics and webhook servers")
+	flag.IntVar(&unusedImageTTL, "unused-image-ttl", 30, "Unused image TTL in days.")
+
 	opts := zap.Options{
 		Development: true,
 	}
@@ -198,8 +202,9 @@ func main() {
 		os.Exit(1)
 	}
 	if err = (&kuikcontroller.ImageReconciler{
-		Client: mgr.GetClient(),
-		Scheme: mgr.GetScheme(),
+		Client:         mgr.GetClient(),
+		Scheme:         mgr.GetScheme(),
+		UnusedImageTTL: time.Hour * 24 * time.Duration(unusedImageTTL),
 	}).SetupWithManager(mgr); err != nil {
 		setupLog.Error(err, "unable to create controller", "controller", "Image")
 		os.Exit(1)

cmd/main.go

@@ -29,6 +29,9 @@ spec:
     - jsonPath: .status.upstream.status
       name: Upstream status
       type: string
+    - jsonPath: .status.unusedSince
+      name: Unused since
+      type: date
     - jsonPath: .metadata.creationTimestamp
       name: Age
       type: date
@@ -70,6 +73,11 @@ spec:
           status:
             description: ImageStatus defines the observed state of Image.
             properties:
+              unusedSince:
+                description: UnusedSince is the time when the image was last used
+                  by a pod
+                format: date-time
+                type: string
               upstream:
                 description: Upstream is the information about the upstream image
                 properties:

config/crd/bases/kuik.enix.io_images.yaml

@@ -14,6 +14,7 @@ require (
 	github.com/onsi/ginkgo/v2 v2.23.3
 	github.com/onsi/gomega v1.36.3
 	github.com/prometheus/client_golang v1.22.0
+	go.uber.org/zap v1.27.0
 	k8s.io/api v0.32.3
 	k8s.io/apimachinery v0.32.3
 	k8s.io/client-go v1.5.2
@@ -88,7 +89,6 @@ require (
 	go.opentelemetry.io/otel/trace v1.35.0 // indirect
 	go.opentelemetry.io/proto/otlp v1.5.0 // indirect
 	go.uber.org/multierr v1.11.0 // indirect
-	go.uber.org/zap v1.27.0 // indirect
 	golang.org/x/exp v0.0.0-20250408133849-7e4ce0ab07d0 // indirect
 	golang.org/x/net v0.39.0 // indirect
 	golang.org/x/oauth2 v0.29.0 // indirect

go.mod

@@ -28,6 +28,9 @@ spec:
     - jsonPath: .status.upstream.status
       name: Upstream status
       type: string
+    - jsonPath: .status.unusedSince
+      name: Unused since
+      type: date
     - jsonPath: .metadata.creationTimestamp
       name: Age
       type: date
@@ -69,6 +72,11 @@ spec:
           status:
             description: ImageStatus defines the observed state of Image.
             properties:
+              unusedSince:
+                description: UnusedSince is the time when the image was last used
+                  by a pod
+                format: date-time
+                type: string
               upstream:
                 description: Upstream is the information about the upstream image
                 properties:

helm/kube-image-keeper/crds/kuik.enix.io_images.yaml

@@ -42,6 +42,7 @@ spec:
             - -metrics-bind-address=:8080
             - -metrics-secure=false
             - -zap-log-level={{ .Values.manager.verbosity }}
+            - -unused-image-ttl={{ .Values.unusedImageTTL }}
           env:
             - name: KUIK_REGISTRY_MONITOR_DEFAULT_INTERVAL
               value: "{{ .Values.registryMonitors.defaultSpec.interval }}"

helm/kube-image-keeper/templates/manager-deployment.yaml

@@ -104,3 +104,6 @@ registryMonitors:
     ghcr.io: {}
     registry.k8s.io: {}
     public.ecr.aws: {}
+
+# -- Delay in days before deleting an Image not used by any pod
+unusedImageTTL: 30

helm/kube-image-keeper/values.yaml

@@ -3,11 +3,13 @@ package kuik
 import (
 	"context"
 	"net/http"
+	"time"
 
 	kuikv1alpha1 "github.com/enix/kube-image-keeper/api/kuik/v1alpha1"
 	corev1 "k8s.io/api/core/v1"
 	"k8s.io/apimachinery/pkg/api/errors"
 	apierrors "k8s.io/apimachinery/pkg/api/errors"
+	v1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 	"k8s.io/apimachinery/pkg/runtime"
 	"k8s.io/apimachinery/pkg/types"
 	ctrl "sigs.k8s.io/controller-runtime"
@@ -23,7 +25,8 @@ const (
 // ImageReconciler reconciles a Image object
 type ImageReconciler struct {
 	client.Client
-	Scheme *runtime.Scheme
+	Scheme         *runtime.Scheme
+	UnusedImageTTL time.Duration
 }
 
 // +kubebuilder:rbac:groups=kuik.enix.io,resources=images,verbs=get;list;watch;create;update;patch;delete
@@ -40,20 +43,33 @@ type ImageReconciler struct {
 // For more details, check Reconcile and its Result here:
 // - https://pkg.go.dev/sigs.k8s.io/[email protected]/pkg/reconcile
 func (r *ImageReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
-	_ = logf.FromContext(ctx)
+	log := logf.FromContext(ctx)
 
 	var image kuikv1alpha1.Image
 	if err := r.Get(ctx, req.NamespacedName, &image); err != nil {
 		return ctrl.Result{}, client.IgnoreNotFound(err)
 	}
 
+	log = log.WithValues("reference", image.Reference())
+
 	// update Pods and Nodes status for this Image
 	if requeue, err := r.updateReferenceCount(ctx, &image); requeue {
 		return ctrl.Result{Requeue: true}, nil
 	} else if err != nil {
 		return ctrl.Result{}, err
 	}
 
+	if !image.Status.UnusedSince.IsZero() {
+		if v1.Now().Sub(image.Status.UnusedSince.Time) > r.UnusedImageTTL {
+			log.Info("image is unused for too long, deleting it", "ttl", r.UnusedImageTTL)
+			if err := r.Delete(ctx, &image); err != nil {
+				return ctrl.Result{}, client.IgnoreNotFound(err)
+			}
+		} else {
+			return ctrl.Result{RequeueAfter: r.UnusedImageTTL - time.Since(image.Status.UnusedSince.Time)}, nil
+		}
+	}
+
 	return ctrl.Result{}, nil
 }
 
@@ -88,7 +104,7 @@ func (r *ImageReconciler) SetupWithManager(mgr ctrl.Manager) error {
 func (r *ImageReconciler) updateReferenceCount(ctx context.Context, image *kuikv1alpha1.Image) (requeue bool, err error) {
 	var podList corev1.PodList
 	if err = r.List(ctx, &podList, client.MatchingFields{ImagesIndexKey: image.Name}); err != nil && !apierrors.IsNotFound(err) {
-		return
+		return false, err
 	}
 
 	pods := []string{}
@@ -104,15 +120,23 @@ func (r *ImageReconciler) updateReferenceCount(ctx context.Context, image *kuikv
 		Count: len(pods),
 	}
 
+	if len(pods) == 0 {
+		if image.Status.UnusedSince.IsZero() {
+			image.Status.UnusedSince = v1.Now()
+		}
+	} else {
+		image.Status.UnusedSince = v1.Time{}
+	}
+
 	err = r.Status().Update(ctx, image)
 	if err != nil {
 		if statusErr, ok := err.(*errors.StatusError); ok && statusErr.Status().Code == http.StatusConflict {
 			requeue = true
 		}
-		return
+		return requeue, err
 	}
 
-	return
+	return false, nil
 }
 
 func (r *ImageReconciler) imagesRequestFromPod(ctx context.Context, obj client.Object) []ctrl.Request {