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,ImageMirrorandImageMonitor. - Shared mirrors: an
ImageMirrorcan 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.ioinstead ofmpod-v1.kb.io, in a MutatingWebhookConfiguration named<release>-webhook: move the alerts and dashboards onapiserver_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.secretRefis copied as akuik-inject-<kind>-<name>pull Secret into the namespaces that need it, and added to the pod'simagePullSecrets. (#682, #701)
Routing
- An
ImageAlternativelists 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
repositoryfor one repository orrepositoryGroupfor every repository under a path, and digest-pinned images are routed too. (#680, #682) - An entry marked
unavailable: truedeclares 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-rewritesandkuik.enix.io/no-alternativesannotations. (#682) - A candidate the background loops report failing is tried last (
webhook.availabilityCheck.demoteKnownFailures, on by default). (#751, #753) - The status of an
ImageAlternativereports the pods it rewrote, its active fallbacks and the images no candidate could serve. (#696)
Mirroring
- An
ImageMirrorcopies the images of the pods it selects to a destination registry, digest unchanged, and routes to the copy unlessrewritePolicyisNone. (#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) excludeImageskeeps images out of a mirror with globs such asghcr.io/foo-bar/**or**:latest. (#682, #710)driftPolicy(Ignore,Warn,Sync) decides what happens when an upstream tag moves after its copy. (#710)cleanupdeletes the destination tags no pod uses any more onceretentionelapsed (168h by default), andcleanup.deleteByDigestdeletes by manifest digest for destinations that refuse tag deletion, such as Harbor. (#710, #824, closes #820)- A deleted
ImageMirrorwaits while live pods run its copies, then deletes its tags; itsDeletionBlockedcondition says why it staysTerminating. (#710, #849, closes #832)
Monitoring
- An
ImageMonitorchecks that the images of the pods it selects are still available upstream, and lists the failing ones instatus.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 alternativesImageAlternativeresources offer for those images. (#745)
Registries
- Background checks and copies are paced per host on fixed windows, set by
registriesin the global config, andregistries.<host>.requestIntervalspaces 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 specificfallbackAuthentry, then anonymous. (#680) - The
tlskey of the global config trusts a private CA (caSecretRef) or a self-signed certificate (insecureSkipVerify) per registry host, andinsecure: trueon 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 onlyReadyisTruewhen all is well. (#696, #703, #710, #732) - The Pod webhook is named
pods.kuik.enix.io, so the API server'sapiserver_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.alertsandmonitoring.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.