github enix/kube-image-keeper v3.0.0

2 hours ago

kuik v3 is generally available! 🎉

This is the first stable release and a complete rewrite from a clean tree that routes, copies and monitors the images of your pods with 3 new resources.

There is no upgrade path from v2 (yet): install v3 on a cluster without v2. A migration path is coming, and v2 stays maintained until then.

✨ Highlights

  • New resources: kuik v3 routes, copies and monitors pod images with 3 new cluster-scoped resources: ImageAlternative, ImageMirror and ImageMonitor.
  • Shared mirrors: an ImageMirror can share its destination registry with other clusters: each cluster only creates, checks and deletes its own tags.
  • 3 processes: kuik runs as a webhook, a reconciler and a secret syncer, each with its own Deployment and 2 replicas by default.
  • Paced registry reads: every background read of a registry is paced per host, slowly by default, to spare rate limits and quotas.
  • Ready-made monitoring: the chart can ship a ServiceMonitor for Prometheus, a PrometheusRule of alerts, and a Grafana dashboard.

⚠️ Breaking changes

From v2

  • kuik v3 reads none of the v2 resources (ImageSetMirror, ClusterImageSetMirror, ReplicatedImageSet, ClusterReplicatedImageSet, ClusterImageSetAvailability) nor the v2 chart values. Install v3 on a cluster without v2; a migration path is coming, and v2 stays maintained until then. (#670)
  • The chart requires Kubernetes 1.30 or later, and cert-manager for the webhook certificate. (#752)
  • The processes log JSON instead of console text, with no chart value to switch back: see how to read the logs. (#703)

From 3.0.0-beta.5

  • The Pod webhook is named pods.kuik.enix.io instead of mpod-v1.kb.io, in a MutatingWebhookConfiguration named <release>-webhook: move the alerts and dashboards on apiserver_admission_webhook_*{name="mpod-v1.kb.io"}. Pods created in the few seconds of the upgrade before cert-manager injects the CA may be admitted unrouted. (#880, closes #868)

📋 Changelog

Changes since 2.3.1.

Features

27 new features
  • Pull secrets: A candidate's auth.secretRef is copied as a kuik-inject-<kind>-<name> pull Secret into the namespaces that need it, and added to the pod's imagePullSecrets. (#682, #701)

Routing

  • An ImageAlternative lists repositories that hold the same images, and the webhook places the first candidate that answers, as a fallback (rewritePolicy: OnFailure, the default) or ahead of the original (Always). (#682)
  • Images match on whole path segments, with repository for one repository or repositoryGroup for every repository under a path, and digest-pinned images are routed too. (#680, #682)
  • An entry marked unavailable: true declares a source gone, so an image from it is tried last. (#682)
  • The webhook records each decision on the pod in the kuik.enix.io/rewrites, kuik.enix.io/conceded-rewrites and kuik.enix.io/no-alternatives annotations. (#682)
  • A candidate the background loops report failing is tried last (webhook.availabilityCheck.demoteKnownFailures, on by default). (#751, #753)
  • The status of an ImageAlternative reports the pods it rewrote, its active fallbacks and the images no candidate could serve. (#696)

Mirroring

  • An ImageMirror copies the images of the pods it selects to a destination registry, digest unchanged, and routes to the copy unless rewritePolicy is None. (#682, #710)
  • Several clusters can share one destination: each copy carries a _<clusterID> tag suffix, and each cluster only creates, checks and deletes its own tags. (#710)
  • excludeImages keeps images out of a mirror with globs such as ghcr.io/foo-bar/** or **:latest. (#682, #710)
  • driftPolicy (Ignore, Warn, Sync) decides what happens when an upstream tag moves after its copy. (#710)
  • cleanup deletes the destination tags no pod uses any more once retention elapsed (168h by default), and cleanup.deleteByDigest deletes by manifest digest for destinations that refuse tag deletion, such as Harbor. (#710, #824, closes #820)
  • A deleted ImageMirror waits while live pods run its copies, then deletes its tags; its DeletionBlocked condition says why it stays Terminating. (#710, #849, closes #832)

Monitoring

  • An ImageMonitor checks that the images of the pods it selects are still available upstream, and lists the failing ones in status.unavailableImages. (#717, #732)
  • An image no pod uses any more stays monitored for unusedImageRetention (168h by default), so a CronJob's image stays checked between runs. (#717)
  • With monitorAlternatives: true, it also checks the alternatives ImageAlternative resources offer for those images. (#745)

Registries

  • Background checks and copies are paced per host on fixed windows, set by registries in the global config, and registries.<host>.requestInterval spaces every request to a rate-limited source. (#697, #854, closes #841)
  • Credentials are tried in the kubelet's order: the resource's auth, the pod's pull secrets, the most specific fallbackAuth entry, then anonymous. (#680)
  • The tls key of the global config trusts a private CA (caSecretRef) or a self-signed certificate (insecureSkipVerify) per registry host, and insecure: true on an entry reaches a registry over plain HTTP. (#682, #710, #767, #856, closes #750)

Configuration

  • The global config file is validated whole and reloaded without a restart; a reload that does not validate keeps the previous config. (#680)
  • kuik generates its cluster ID and keeps it in the ConfigMap kuik-cluster-id. (#764, closes #727)

Observability

  • Kubernetes events on pods and resources, kuik_* Prometheus metrics for routing, copies, checks, anomalies and pacing, JSON logs, and conditions where only Ready is True when all is well. (#696, #703, #710, #732)
  • The Pod webhook is named pods.kuik.enix.io, so the API server's apiserver_admission_webhook_* metrics show the calls that failed and let the pod through unrouted. (#880, closes #868)

Chart

  • The webhook, the reconciler and the secret syncer run as 3 Deployments, with 2 replicas each by default and a standby that takes over the lease. (#672, #701, closes #548)
  • A ValidatingAdmissionPolicy refuses any Secret write by the secret syncer that is not a pull Secret it owns. (#752)
  • The default config paces every host to a check every 3 minutes and a copy every 5, Docker Hub to 5 and 15, and both hosts of ECR Public to 1 request per second. (#854, #874)
  • monitoring.serviceMonitor, monitoring.alerts and monitoring.dashboard, off by default, ship a ServiceMonitor, a PrometheusRule of ready-made alerts and a Grafana dashboard (Grafana 13 or later). (#876)

Fixes

None in this release.

Don't miss a new kube-image-keeper release

NewReleases is sending notifications on new releases.