# version-checker: Turning Stale Container Images Into Prometheus Metrics > version-checker is an Apache-2.0 licensed Go utility that runs in a Kubernetes cluster, compares the container images and Kubernetes version actually running against the latest upstream releases, and exports the gap as Prometheus metrics. It suits platform teams who want an upgrade backlog as a dashboard. **jetstack/version-checker** — Kubernetes utility for exposing image versions in use, compared to latest available upstream, as metrics. - Repository: https://github.com/jetstack/version-checker - Website: https://jetstack.io - Stars: 778 · Forks: 83 - Language: Go - License: Apache-2.0 - Published: 2026-10-20 · Updated: 2026-10-20 · Language: en - Canonical page: https://hysenlabs.com/projects/jetstack-version-checker ## Two version questions answered as metrics version-checker is a Kubernetes utility for observing the current versions of images running in the cluster, as well as the latest available upstream, and it also monitors the Kubernetes cluster version against the latest available releases using the official Kubernetes release channels. The checks are exposed as Prometheus metrics to be viewed on a dashboard, or to softly alert cluster operators. That word softly is the design brief. The tool does not restart anything and does not pull anything; it observes and reports, and a human or an alerting rule decides. The four feature bullets are the same idea in four places: container image version checking against the latest upstream versions, Kubernetes version monitoring against official release channels, Prometheus metrics integration, and flexible channel selection so you can track stable, latest or another channel. ## The registries it can read, and their authentication The registry list explains the scope of the tool. It supports ACR, Docker Hub, ECR, GCR including facades such as k8s.gcr.io, Quay, and self-hosted registries that speak the Docker V2 API, with registry and artifactory given as examples. Multiple self-hosted registries can be configured at once, which matters for organisations running a mix of hosted and internal registries across clusters. These registries support authentication, and the go.mod file shows how that is implemented: the Azure autorest and JWT libraries for ACR, the AWS SDK v2 with a dedicated ECR service client for ECR, and go-github with a rate limit helper for GitHub-based registries, alongside go-containerregistry for the generic path and retryablehttp and a small in-memory cache for resilience. The presence of a client per cloud vendor is what makes private registry scanning work across providers. ## Why the tool needs a per-registry configuration file There is a page in the repository called known-configurations.md, and the readme explains its existence in unusually candid terms. From time to time, version-checker may need some of these options applied to determine the latest version, depending on how the maintainers publish their images, and the project says it is making a conscious effort to collate these configurations. In other words, the hard part of this tool is not scraping a registry for a tag list, it is interpreting what a tag means. A registry may publish latest, a floating tag, a build number, a date, or nothing that sorts into an order at all, and the tool needs to be told which convention applies for that repository. That is the same class of problem as sorting Debian versions or Maven versions, and the reason the answers live in a data file rather than in code. Anyone deploying this will spend time in that file. ## The dependency set of a cluster-side observer The go.mod file is worth reading because it describes the architecture. The module is github.com/jetstack/version-checker on Go 1.26.4, and the core dependencies are the Prometheus client libraries, cobra and pflag for the command line, logrus and the logrusr adapter for logging, and a set of Kubernetes libraries at v0.37.1 including the API, apimachinery, cli-runtime, client-go and component-base, plus controller-runtime at v0.25.1. The Kubernetes client is what lets the utility enumerate the images actually running across the cluster, and controller-runtime is what lets it run as a controller inside the cluster rather than as a one-shot job. There is one replace directive, pinning mergo to v0.3.16, and the file carries a comment asking that replace statements stay at the top for visibility. The testing dependencies are minimal, httpmock and testify. ## Building it, and the container image it ships as The Makefile has a small set of targets. The deps target downloads the dependencies, test runs the tests with a coverage profile, build produces a binary in the bin directory with CGO disabled, verify runs test and build together, and image builds the container image with a version tag of v0.11.0 on quay.io. ```bash CGO_ENABLED=0 go build -o ./bin/version-checker ./cmd/. ``` ```bash docker build -t quay.io/jetstack/version-checker:v0.11.0 . ``` The Dockerfile does the same thing in two stages. The builder is golang:1.27-alpine and cross-compiles with CGO_ENABLED=0 and the TARGETOS and TARGETARCH build arguments, so one image definition produces images for several architectures. The runtime stage is alpine:3.24 with the certificate bundle installed and the binary copied to /usr/bin/version-checker, which is the entrypoint. A static binary in a small base image is the right choice for something that is scheduled to run across a fleet, since it keeps the pull small and removes a class of runtime dependency. ## The reasons the project gives for running it The readme lists seven reasons, and they are worth reading as a statement of what an SRE is actually trying to achieve. Improved security, since up-to-date images and clusters reduce the risk of running vulnerable or compromised versions. Enhanced visibility, a clear overview of running container and cluster versions across clusters. Operational efficiency, automating version tracking and reducing manual intervention. Compliance and policy enforcement, maintaining version consistency and adherence to organisational policies for both applications and infrastructure. Incremental upgrades, which facilitates frequent small updates and reduces the risk of large disruptive ones. Add-on compatibility, since add-ons and dependencies have their own version requirements. And proactive cluster management, staying informed about security updates and new features. The incremental upgrade point is the one with the most operational weight, since the cost of an upgrade is mostly the cost of the downtime and the surprise, and a dashboard that shows how far behind each workload is makes the upgrade smaller. ## What to expect, and where the dashboard fits A Grafana dashboard is published to the Grafana dashboard catalogue, dashboard 12833, which shows the image versions as a table rather than as the raw metric stream. The documentation is split into an installation guide, a metrics reference and a new features page, and the readme says the checks get exposed as metrics to be viewed on a dashboard or to softly alert cluster operators. The distinction between a dashboard and an alert is the practical decision you have to make with this tool, because the same metric can drive either. A dashboard answers the question of where the drift is; an alert answers whether to wake someone up. Given that the upstream comparison is a network call to a registry, an alert on every image check would be noisy, which is why the soft framing in the readme is the right default. ## Conclusion version-checker fits a platform team that wants to see version drift across many clusters as a metric it can alert on, rather than as a spreadsheet someone refreshes. It is the wrong tool if you run a single cluster with a handful of images, since the setup is a per-cluster deployment, and the wrong tool if your images are tagged in a way the tool cannot interpret, since the known configurations page exists precisely because publishing conventions vary. Before you deploy it, check the metric names in the metrics documentation and add them to your alerting rules as a soft alert first. ## FAQ ### What does jetstack version-checker monitor? Two things: the container images running in the cluster compared against their latest upstream versions, and the cluster's own Kubernetes version compared against the latest releases from the official Kubernetes release channels. Both are exposed as Prometheus metrics. ### Which container registries does version-checker support? ACR, Docker Hub, ECR, GCR including facades such as k8s.gcr.io, Quay, and self-hosted registries that speak the Docker V2 API, with several self-hosted registries configurable at once. These registries support authentication, handled per cloud provider through the autorest, AWS SDK and GitHub client libraries. ### Why does version-checker need known-configurations.md? Because determining the latest version depends on how each registry's maintainers publish their images. The project says it may need those options applied from time to time and that it is making a conscious effort to collate them, so the answers live in a data file rather than in code. ### How do I build version-checker? The Makefile has deps, test, build, verify and image targets. The build runs go build with CGO disabled, and the image target builds a Docker image tagged quay.io/jetstack/version-checker:v0.11.0, cross-compiled from a golang:1.27-alpine builder stage. ### Does version-checker upgrade anything on its own? No. The checks are exposed as Prometheus metrics to be viewed on a dashboard or to softly alert cluster operators, so the tool observes and reports while the decision to act stays with an alerting rule or a human. A Grafana dashboard showing image versions as a table is also published. ## Sources - [jetstack/version-checker on GitHub](https://github.com/jetstack/version-checker) - [License: Apache-2.0](https://github.com/jetstack/version-checker/blob/main/LICENSE) - [Project website](https://jetstack.io) - [README](https://github.com/jetstack/version-checker/blob/main/README.md) - [Releases](https://github.com/jetstack/version-checker/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/jetstack-version-checker